Please read Contributing to Shaarli
- Unit tests
make eslintto check JS style.
- GnuPG signature for tags/releases
- Yahoo UI CSS Reset - standardize cross-browser rendering
- Awesomeplete (GitHub) - autocompletion in input forms
- bLazy (GitHub) - lazy loading for thumbnails
- qr.js (GitHub) - QR code generation
PHP (managed through
- RainTPL - HTML templating for PHP
shaarli/netscape-bookmark-parser- Import bookmarks from Netscape files
erusev/parsedown- Parse MarkDown syntax for the MarkDown plugin
slim/slim- Handle routes and middleware for the REST API
ArthurHoaro/web-thumbnailer- PHP library which will retrieve a thumbnail for any given URL
pubsubhubbub/publisher- A PubSubHubbub publisher module for PHP.
gettext/gettext- PHP library to collect and manipulate gettext (.po, .mo, .php, .json, etc)
- The password is salted, hashed and stored in the data subdirectory, in a PHP file, and protected by htaccess. Even if the webserver does not support htaccess, the hash is not readable by URL. Even if the .php file is stolen, the password cannot deduced from the hash. The salt prevents rainbow-tables attacks.
- Directories are protected using
- Forms are protected against XSRF:
- Forms which act on data (save,delete…) contain a token generated by the server.
- Any posted form which does not contain a valid token is rejected.
- Any token can only be used once.
- Tokens are attached to the session and cannot be reused in another session.
- Sessions automatically expire after 60 minutes.
- Sessions are protected against hijacking: the session ID cannot be used from a different IP address.
- Links are stored as an associative array which is serialized, compressed (with deflate), base64-encoded and saved as a comment in a
.phpfile - even if the server does not support
.htaccessfiles, the data file will still not be readable by URL.
- Bruteforce protection: Successful and failed login attempts are logged - IP bans are enforced after a configurable amount of failures. Logs can also be used consumed by fail2ban
- A pop-up notification is shown when a new release is available.
Every link available through the
LinkDB object is represented as an array
containing the following fields:
id(integer): Unique identifier.
title(string): Title of the link.
url(string): URL of the link. Used for displayable links (without redirector, url encoding, etc.). Can be absolute or relative for Notes.
real_url(string): Real destination URL, can be redirected, encoded, etc.
shorturl(string): Permalink small hash.
description(string): Link text description.
private(boolean): whether the link is private or not.
tags(string): all link tags separated by a single space
thumbnail(string|boolean): relative path of the thumbnail cache file, or false if there isn't any.
created(DateTime): link creation date time.
updated(DateTime): last modification date time.
Small hashes are used to make a link to an entry in Shaarli. They are unique: the date of the item (eg.
20110923_150523) is hashed with CRC32, then converted to base64 and some characters are replaced. They are always 6 characters longs and use only
A-Z a-z 0-9 - _ and
Here is the directory structure of Shaarli and the purpose of the different files:
Shaarli needs read access to:
- the root index.php file
Shaarli needs read/write access to the
Makefile is available to perform project-related operations:
- Static analysis - check that the code is compliant to PHP conventions
- Unit tests - ensure there are no regressions introduced by new commits
- Documentation - generate a local HTML copy of the markdown documentation
Github Actions is a Continuous Integration build server, that runs a build:
- each time a commit is pushed to any branch
- each time a Pull Request is submitted or updated
After all jobs have finished, Github Actions returns the results to GitHub:
- a status icon represents the result for the
- Pull Requests are updated with the Github Actions build result.
Github Actions is also used to build and push Docker images to https://github.com/shaarli/Shaarli/pkgs/container/shaarli for the
master branch and on every git
mkdocs is used to convert markdown documentation to HTML pages. The public documentation website is rendered and hosted by readthedocs.org. A copy of the documentation is also included in prebuilt release archives (
doc/html/ path in your Shaarli installation). To generate the HTML documentation locally, install a recent version of Python
setuptools and run
Patches should try to stick to the PHP Standard Recommendations (PSR), and must follow:
These are enforced on pull requests using our Continuous Integration tools with PHP Code Sniffer.
Static analysis tools are installed with Composer dependencies, and used through Shaarli's Makefile with
For an overview of the available features, see: