3 Please read [Contributing to Shaarli](https://github.com/shaarli/Shaarli/tree/master/CONTRIBUTING.md)
8 - [Unit tests](Unit-tests)
9 - Javascript linting - Shaarli uses [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript).
10 Run `make eslint` to check JS style.
11 - [GnuPG signature](GnuPG-signature) for tags/releases
14 ## Third-party libraries
18 - Yahoo UI [CSS Reset](http://yuilibrary.com/yui/docs/cssreset/) - standardize cross-browser rendering
22 - [Awesomeplete](https://leaverou.github.io/awesomplete/) ([GitHub](https://github.com/LeaVerou/awesomplete)) - autocompletion in input forms
23 - [bLazy](http://dinbror.dk/blazy/) ([GitHub](https://github.com/dinbror/blazy)) - lazy loading for thumbnails
24 - [qr.js](http://neocotic.com/qr.js/) ([GitHub](https://github.com/neocotic/qr.js)) - QR code generation
26 PHP (managed through [`composer.json`](https://github.com/shaarli/Shaarli/blob/master/composer.json)):
28 - [RainTPL](https://github.com/rainphp/raintpl) - HTML templating for PHP
29 - [`shaarli/netscape-bookmark-parser`](https://packagist.org/packages/shaarli/netscape-bookmark-parser) - Import bookmarks from Netscape files
30 - [`erusev/parsedown`](https://packagist.org/packages/erusev/parsedown) - Parse MarkDown syntax for the MarkDown plugin
31 - [`slim/slim`](https://packagist.org/packages/slim/slim) - Handle routes and middleware for the REST API
32 - [`ArthurHoaro/web-thumbnailer`](https://github.com/ArthurHoaro/web-thumbnailer) - PHP library which will retrieve a thumbnail for any given URL
33 - [`pubsubhubbub/publisher`](https://github.com/pubsubhubbub/php-publisher) - A PubSubHubbub publisher module for PHP.
34 - [`gettext/gettext`](https://github.com/php-gettext/Gettext) - PHP library to collect and manipulate gettext (.po, .mo, .php, .json, etc)
39 - 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.
40 - Directories are protected using `.htaccess` files
41 - Forms are protected against [XSRF](http://en.wikipedia.org/wiki/Cross-site_request_forgery):
42 - Forms which act on data (save,delete…) contain a token generated by the server.
43 - Any posted form which does not contain a valid token is rejected.
44 - Any token can only be used once.
45 - Tokens are attached to the session and cannot be reused in another session.
46 - Sessions automatically expire after 60 minutes.
47 - Sessions are protected against hijacking: the session ID cannot be used from a different IP address.
48 - Links are stored as an associative array which is serialized, compressed (with deflate), base64-encoded and saved as a comment in a `.php` file - even if the server does not support `.htaccess` files, the data file will still not be readable by URL.
49 - 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](../Server-configuration.md#fail2ban)
50 - A pop-up notification is shown when a new release is available.
54 Every link available through the `LinkDB` object is represented as an array
55 containing the following fields:
57 * `id` (integer): Unique identifier.
58 * `title` (string): Title of the link.
59 * `url` (string): URL of the link. Used for displayable links (without redirector, url encoding, etc.).
60 Can be absolute or relative for Notes.
61 * `real_url` (string): Real destination URL, can be redirected, encoded, etc.
62 * `shorturl` (string): Permalink small hash.
63 * `description` (string): Link text description.
64 * `private` (boolean): whether the link is private or not.
65 * `tags` (string): all link tags separated by a single space
66 * `thumbnail` (string|boolean): relative path of the thumbnail cache file, or false if there isn't any.
67 * `created` (DateTime): link creation date time.
68 * `updated` (DateTime): last modification date time.
70 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 `@`.
73 ## Directory structure
75 Here is the directory structure of Shaarli and the purpose of the different files:
78 index.php # Main program
79 application/ # Shaarli classes
85 tests/ # Shaarli unitary & functional tests
90 ├── utils # utilities to ease testing
91 │ └── ReferenceLinkDB.php
94 ├── common/ # Assets shared by multiple themes
96 ├── default/ # Assets for the default template, before compilation
97 ├── fonts/ # Font files
98 ├── img/ # Images used by the default theme
99 ├── js/ # JavaScript files in ES6 syntax
100 ├── scss/ # SASS files
101 └── vintage/ # Assets for the vintage template, before compilation
103 COPYING # Shaarli license
104 inc/ # static assets and 3rd party libraries
105 └── rain.tpl.class.php # RainTPL templating library
106 images/ # Images and icons used in Shaarli
107 data/ # data storage: bookmark database, configuration, logs, banlist...
108 ├── config.json.php # Shaarli configuration (login, password, timezone, title...)
109 ├── datastore.php # Your link database (compressed).
110 ├── ipban.php # IP address ban system data
111 ├── lastupdatecheck.txt # Update check timestamp file
112 └── log.txt # login/IPban log.
113 tpl/ # RainTPL templates for Shaarli. They are used to build the pages.
114 ├── default/ # Default Shaarli theme
115 ├── fonts/ # Font files
117 ├── js/ # JavaScript files compiled by Babel and compatible with all browsers
118 ├── css/ # CSS files compiled with SASS
119 └── vintage/ # Legacy Shaarli theme
121 cache/ # thumbnails cache
122 # This directory is automatically created. You can erase it anytime you want.
123 tmp/ # Temporary directory for compiled RainTPL templates.
124 # This directory is automatically created. You can erase it anytime you want.
125 vendor/ # Third-party dependencies. This directory is created by Composer
128 Shaarli needs read access to:
130 - the root index.php file
131 - the `application/`, `plugins/` and `inc/` directories (recursively)
133 Shaarli needs read/write access to the `cache/`, `data/`, `pagecache/`, and `tmp/` directories
138 A [`Makefile`](https://github.com/shaarli/Shaarli/blob/master/Makefile) is available to perform project-related operations:
140 - [Static analysis](#Static-analysis) - check that the code is compliant to PHP conventions
141 - [Unit tests](#Unit-tests) - ensure there are no regressions introduced by new commits
142 - Documentation - generate a local HTML copy of the markdown documentation
144 ### Continuous Integration
146 [Travis CI](http://docs.travis-ci.com/) is a Continuous Integration build server, that runs a build:
148 - each time a commit is merged to the mainline (`master` branch)
149 - each time a Pull Request is submitted or updated
151 After all jobs have finished, Travis returns the results to GitHub:
153 - a status icon represents the result for the `master` branch: [![](https://api.travis-ci.org/shaarli/Shaarli.svg)](https://travis-ci.org/shaarli/Shaarli)
154 - Pull Requests are updated with the Travis build result.
156 See [`.travis.yml`](https://github.com/shaarli/Shaarli/blob/master/.travis.yml).
161 [mkdocs](https://www.mkdocs.org/) is used to convert markdown documentation to HTML pages. The [public documentation](https://shaarli.readthedocs.io/en/master/) website is rendered and hosted by [readthedocs.org](https://readthedocs.org/). A copy of the documentation is also included in prebuilt [release archives](https://github.com/shaarli/Shaarli/releases) (`doc/html/` path in your Shaarli installation). To generate the HTML documentation locally, install a recent version of Python `setuptools` and run `make doc`.
166 Patches should try to stick to the [PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), and must follow:
168 - [PSR-1](http://www.php-fig.org/psr/psr-1/) - Basic Coding Standard
169 - [PSR-2](http://www.php-fig.org/psr/psr-2/) - Coding Style Guide
170 - [PSR-12](http://www.php-fig.org/psr/psr-12/) - Extended Coding Style Guide
172 These are enforced on pull requests using our Continuous Integration tools.
174 **Work in progress:** Static analysis is currently being discussed here: in [#95 - Fix coding style (static analysis)](https://github.com/shaarli/Shaarli/issues/95), [#130 - Continuous Integration tools & features](https://github.com/shaarli/Shaarli/issues/130)
176 Static analysis tools can be installed with Composer, and used through Shaarli's [Makefile](https://github.com/shaarli/Shaarli/blob/master/Makefile).
178 For an overview of the available features, see:
180 - [Code quality: Makefile to run static code checkers](https://github.com/shaarli/Shaarli/pull/124) (#124)
181 - [Run PHPCS against different coding standards](https://github.com/shaarli/Shaarli/pull/276) (#276)