-
- * [Backup and restore the datastore file](#backup-and-restore-the-datastore-file)
- * [Export links as...](#export-links-as)
- * [Import links from...](#import-links-from)
- * [Import Shaarli links to Firefox](#import-shaarli-links-to-firefox)
-
-----------------------
-
## Backup and restore the datastore file
Backup the file `data/datastore.php` (by FTP or SSH). Restore by putting the file back in place.
## Export links as...
To export links as an HTML file, under _Tools > Export_, choose:
+
- _Export all_ to export both public and private links
- _Export public_ to export public links only
- _Export private_ to export private links only
Restore by using the `Import` feature.
-* This can be done using the [shaarchiver](https://github.com/nodiscc/shaarchiver) tool.
+
+- This can be done using the [shaarchiver](https://github.com/nodiscc/shaarchiver) tool.
Example command:
```bash
### Scuttle
-Shaarli cannot import data directly from [Scuttle](https://github.com/scronide/scuttle). However, you can use this third party tool: https://github.com/q2apro/scuttle-to-shaarli to export the Scuttle database to the Netscape HTML format compatible with the Shaarli importer.
+Shaarli cannot import data directly from [Scuttle](https://github.com/scronide/scuttle).
+
+However, you can use the third-party [scuttle-to-shaarli](https://github.com/q2apro/scuttle-to-shaarli)
+tool to export the Scuttle database to the Netscape HTML format compatible with the Shaarli importer.
## Import Shaarli links to Firefox
- * Export your Shaarli links as described above.
- * For compatibility reasons, check `Prepend note permalinks with this Shaarli instance's URL (useful to import bookmarks in a web browser)`
- * In Firefox, open the bookmark manager (not the sidebar! `Bookmarks menu > Show all bookmarks` or `Ctrl+Shift+B`)
- * Select `Import and Backup > Import bookmarks in HTML format`
+- Export your Shaarli links as described above.
+ - For compatibility reasons, check `Prepend note permalinks with this Shaarli instance's URL (useful to import bookmarks in a web browser)`
+- In Firefox, open the bookmark manager (not the sidebar! `Bookmarks menu > Show all bookmarks` or `Ctrl+Shift+B`)
+- Select `Import and Backup > Import bookmarks in HTML format`
Your bookmarks will be imported in Firefox, ready to use, with tags and descriptions retained. "Self" (notes) shaares will still point to the Shaarli instance you exported them from, but the note text can be viewed directly in the bookmark properties inside your browser. Depending on the number of bookmarks, the import can take some time.
You may be interested in these Firefox addons to manage links imported from Shaarli
- * [Bookmark Deduplicator](https://addons.mozilla.org/en-US/firefox/addon/bookmark-deduplicator/) - provides an easy way to deduplicate your bookmarks
- * [TagSieve](https://addons.mozilla.org/en-US/firefox/addon/tagsieve/) - browse your bookmarks by their tags
+- [Bookmark Deduplicator](https://addons.mozilla.org/en-US/firefox/addon/bookmark-deduplicator/) - provides an easy way to deduplicate your bookmarks
+- [TagSieve](https://addons.mozilla.org/en-US/firefox/addon/tagsieve/) - browse your bookmarks by their tags
-### Add the sharing button (_bookmarklet_) to your browser
+## Add the sharing button (_bookmarklet_) to your browser
- * Open your Shaarli and `Login`
- * Click the `Tools` button in the top bar
- * Drag the **`✚Shaare link` button**, and drop it to your browser's bookmarks bar.
+- Open your Shaarli and `Login`
+- Click the `Tools` button in the top bar
+- Drag the **`✚Shaare link` button**, and drop it to your browser's bookmarks bar.
_This bookmarklet button is compatible with Firefox, Opera, Chrome and Safari. Under Opera, you can't drag'n drop the button: You have to right-click on it and add a bookmark to your personal toolbar._
-### Share links using the _bookmarklet_
+## Share links using the _bookmarklet_
- * When you are visiting a webpage you would like to share with Shaarli, click the _bookmarklet_ you just added.
- * A window opens.
- * You can freely edit title, description, tags... to find it later using the text search or tag filtering.
- * You will be able to edit this link later using the  edit button.
- * You can also check the “Private” box so that the link is saved but only visible to you.
- * Click `Save`.**Voilà! Your link is now shared.**
+- When you are visiting a webpage you would like to share with Shaarli, click the _bookmarklet_ you just added.
+- A window opens.
+ - You can freely edit title, description, tags... to find it later using the text search or tag filtering.
+ - You will be able to edit this link later using the  edit button.
+ - You can also check the “Private” box so that the link is saved but only visible to you.
+- Click `Save`.**Voilà! Your link is now shared.**
-### Troubleshooting: The bookmarklet doesn't work with a few website (e.g. Github.com)
+## Troubleshooting: The bookmarklet doesn't work with a few websites (e.g. Github.com)
Websites which enforce Content Security Policy (CSP), such as github.com, disallow usage of bookmarklets. Unfortunatly, there is nothing Shaarli can do about it.
There is an open bug for both Firefox and Chromium:
- * https://bugzilla.mozilla.org/show_bug.cgi?id=866522
- * https://code.google.com/p/chromium/issues/detail?id=233903
-
+- https://bugzilla.mozilla.org/show_bug.cgi?id=866522
+- https://code.google.com/p/chromium/issues/detail?id=233903
## WIP
This topic is currently being discussed here:
+
- [Fix coding style (static analysis)](https://github.com/shaarli/Shaarli/issues/95) (#95)
- [Continuous Integration tools & features](https://github.com/shaarli/Shaarli/issues/130) (#130)
### Third party plugins
- * [autosave](https://github.com/kalvn/shaarli-plugin-autosave) by [@kalvn](https://github.com/kalvn): Automatically saves data when editing a link to avoid any loss in case of crash or unexpected shutdown.
- * [Code Coloration](https://github.com/ArthurHoaro/code-coloration) by [@ArthurHoaro](https://github.com/ArthurHoaro): client side code syntax highlighter.
- * [Disqus](https://github.com/kalvn/shaarli-plugin-disqus) by [@kalvn](https://github.com/kalvn): Adds Disqus comment system to your Shaarli.
- * [emojione](https://github.com/NerosTie/emojione) by [@NerosTie](https://github.com/NerosTie): Add colorful emojis to your Shaarli.
- * [google analytics](https://github.com/ericjuden/Shaarli-Google-Analytics-Plugin) by [@ericjuden](http://github.com/ericjuden): Adds Google Analytics tracking support
- * [launch](https://github.com/ArthurHoaro/launch-plugin) - Launch Plugin is a plugin designed to enhance and customize Launch Theme for Shaarli.
- * [related](https://github.com/ilesinge/shaarli-related) by [@ilesinge](https://github.com/ilesinge) - Show related links based on the number of identical tags.
- * [social](https://github.com/alexisju/social) by [@alexisju](https://github.com/alexisju): share links to social networks.
- * [shaarli2twitter](https://github.com/ArthurHoaro/shaarli2twitter) by [@ArthurHoaro](https://github.com/ArthurHoaro) - Automatically tweet your shared links from Shaarli
+- [autosave](https://github.com/kalvn/shaarli-plugin-autosave) by [@kalvn](https://github.com/kalvn): Automatically saves data when editing a link to avoid any loss in case of crash or unexpected shutdown.
+- [Code Coloration](https://github.com/ArthurHoaro/code-coloration) by [@ArthurHoaro](https://github.com/ArthurHoaro): client side code syntax highlighter.
+- [Disqus](https://github.com/kalvn/shaarli-plugin-disqus) by [@kalvn](https://github.com/kalvn): Adds Disqus comment system to your Shaarli.
+- [emojione](https://github.com/NerosTie/emojione) by [@NerosTie](https://github.com/NerosTie): Add colorful emojis to your Shaarli.
+- [google analytics](https://github.com/ericjuden/Shaarli-Google-Analytics-Plugin) by [@ericjuden](http://github.com/ericjuden): Adds Google Analytics tracking support
+- [launch](https://github.com/ArthurHoaro/launch-plugin) - Launch Plugin is a plugin designed to enhance and customize Launch Theme for Shaarli.
+- [related](https://github.com/ilesinge/shaarli-related) by [@ilesinge](https://github.com/ilesinge) - Show related links based on the number of identical tags.
+- [social](https://github.com/alexisju/social) by [@alexisju](https://github.com/alexisju): share links to social networks.
+- [shaarli2twitter](https://github.com/ArthurHoaro/shaarli2twitter) by [@ArthurHoaro](https://github.com/ArthurHoaro) - Automatically tweet your shared links from Shaarli
### Themes
## Local development
A [`Makefile`](https://github.com/shaarli/Shaarli/blob/master/Makefile) is available to perform project-related operations:
+
- Documentation - generate a local HTML copy of the GitHub wiki
- [Static analysis](Static analysis) - check that the code is compliant to PHP conventions
- [Unit tests](Unit tests) - ensure there are no regressions introduced by new commits
## Automatic builds
[Travis CI](http://docs.travis-ci.com/) is a Continuous Integration build server, that runs a build:
+
- each time a commit is merged to the mainline (`master` branch)
- each time a Pull Request is submitted or updated
A build is composed of several jobs: one for each supported PHP version (see [Server requirements](Server requirements)).
Each build job:
+
- updates Composer
- installs 3rd-party test dependencies with Composer
- runs [Unit tests](Unit tests)
After all jobs have finished, Travis returns the results to GitHub:
+
- a status icon represents the result for the `master` branch: [](https://travis-ci.org/shaarli/Shaarli)
- Pull Requests are updated with the Travis result
- Green: all tests have passed
## Development guidelines
Please have a look at the following pages:
+
- [Contributing to Shaarli](https://github.com/shaarli/Shaarli/tree/master/CONTRIBUTING.md)
- [Static analysis](Static analysis) - patches should try to stick to the [PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), especially:
- [PSR-1](http://www.php-fig.org/psr/psr-1/) - Basic Coding Standard
-To install Shaarli, simply place the files in a directory under your webserver's Document Root (or directly at the document root). Make sure your [server](Server-requirements) is properly [configured](Server-configuration).
+To install Shaarli, simply place the files in a directory under your webserver's
+Document Root (or directly at the document root).
+
+Also, please make sure your server meets the [requirements](Server-requirements)
+and is properly [configured](Server-configuration).
Several releases are available:
---------------------------------------------------------
+- by downloading full release archives including all dependencies
+- by downloading Github archives
+- by cloning the Git repository
+
+---
## Latest release (recommended)
### Download as an archive
$ mv Shaarli /path/to/shaarli/
```
-| ! |In most cases, download Shaarli from the [releases](https://github.com/shaarli/Shaarli/releases) page. Cloning using `git` or downloading Github branches as zip files requires additional steps (see below).|
-|-----|--------------------------|
+In most cases, download Shaarli from the [releases](https://github.com/shaarli/Shaarli/releases) page. Cloning using `git` or downloading Github branches as zip files requires additional steps (see below).|
### Using git
```
-mkdir -p /path/to/shaarli && cd /path/to/shaarli/
-git clone -b v0.8 https://github.com/shaarli/Shaarli.git .
-composer install --no-dev
+$ mkdir -p /path/to/shaarli && cd /path/to/shaarli/
+$ git clone -b v0.8 https://github.com/shaarli/Shaarli.git .
+$ composer install --no-dev --prefer-dist
```
---------------------------------------------------------
-
## Stable version
The stable version has been experienced by Shaarli users, and will receive security updates.
$ git clone https://github.com/shaarli/Shaarli.git -b stable /path/to/shaarli/
# install/update third-party dependencies
$ cd /path/to/shaarli/
-$ composer install --no-dev
+$ composer install --no-dev --prefer-dist
```
---------------------------------------------------------
-
## Development version (mainline)
_Use at your own risk!_
$ git clone https://github.com/shaarli/Shaarli.git -b master /path/to/shaarli/
# install/update third-party dependencies
$ cd /path/to/shaarli
-$ composer install --no-dev
+$ composer install --no-dev --prefer-dist
```
---------------------------------------------------------
-
## Finish Installation
Once Shaarli is downloaded and files have been placed at the correct location, open it this location your favorite browser.
Setup your Shaarli installation, and it's ready to use!
---------------------------------------------------------
-
## Updating Shaarli
See [Upgrade and Migration](Upgrade-and-migration)
With Shaarli:
-* The data is yours: It's hosted on your server.
-* Never fear of having your data locked-in.
-* Never fear to have your data sold to third party.
-* Your private links are not hosted on a third party server.
-* You are not tracked by browser addons (like Diigo does)
-* You can change the look and feel of the pages if you want.
-* You can change the behaviour of the program.
-* It's magnitude faster than most bookmarking services.
+- The data is yours: It's hosted on your server.
+- Never fear of having your data locked-in.
+- Never fear to have your data sold to third party.
+- Your private links are not hosted on a third party server.
+- You are not tracked by browser addons (like Diigo does)
+- You can change the look and feel of the pages if you want.
+- You can change the behaviour of the program.
+- It's magnitude faster than most bookmarking services.
### What does Shaarli mean?
-Shaarli is for shaaring your links.
+Shaarli stands for _shaaring_ your _links_.
### My Shaarli is broken!
First of all, ensure that both the [web server](Server-configuration) and [Shaarli](Shaarli-configuration) are correctly configured, and that your installation is [supported](Server-requirements).
If everything looks right but the issue(s) remain(s), please:
+
- take a look at the [troubleshooting](Troubleshooting) section
- come [chat with us](https://gitter.im/shaarli/Shaarli) on Gitter, we'll be happy to help ;-)
- browse active [issues](https://github.com/shaarli/Shaarli/issues) and [Pull Requests](https://github.com/shaarli/Shaarli/pulls)
### Main features
Shaarli is intended:
- * to share, comment and save interesting links and news
- * to bookmark useful/frequent personal links (as private links) and share them between computers
- * as a minimal blog/microblog/writing platform (no character limit)
- * as a read-it-later list (for example items tagged `readlater`)
- * to draft and save articles/ideas
- * to keep code snippets
- * to keep notes and documentation
- * as a shared clipboard between machines
- * as a todo list
- * to store playlists (e.g. with the `music` or `video` tags)
- * to keep extracts/comments from webpages that may disappear
- * to keep track of ongoing discussions (for example items tagged `discussion`)
- * [to feed RSS aggregators](http://shaarli.chassegnouf.net/?9Efeiw) (planets) with specific tags
- * to feed other social networks, blogs... using RSS feeds and external services (dlvr.it, ifttt.com ...)
+
+- to share, comment and save interesting links and news
+- to bookmark useful/frequent personal links (as private links) and share them between computers
+- as a minimal blog/microblog/writing platform (no character limit)
+- as a read-it-later list (for example items tagged `readlater`)
+- to draft and save articles/ideas
+- to keep code snippets
+- to keep notes and documentation
+- as a shared clipboard between machines
+- as a todo list
+- to store playlists (e.g. with the `music` or `video` tags)
+- to keep extracts/comments from webpages that may disappear
+- to keep track of ongoing discussions (for example items tagged `discussion`)
+- [to feed RSS aggregators](http://shaarli.chassegnouf.net/?9Efeiw) (planets) with specific tags
+- to feed other social networks, blogs... using RSS feeds and external services (dlvr.it, ifttt.com ...)
### Using Shaarli as a blog, notepad, pastebin...
- * Go to your Shaarli setup and log in
- * Click the `Add Link` button
- * To share text only, do not enter any URL in the corresponding input field and click `Add Link`
- * Pick a title and enter your article, or note, in the description field; add a few tags; optionally check `Private` then click `Save`
- * Voilà! Your article is now published (privately if you selected that option) and accessible using its permalink.
+- Go to your Shaarli setup and log in
+- Click the `Add Link` button
+- To share text only, do not enter any URL in the corresponding input field and click `Add Link`
+- Pick a title and enter your article, or note, in the description field; add a few tags; optionally check `Private` then click `Save`
+- Voilà! Your article is now published (privately if you selected that option) and accessible using its permalink.
### Add Shaarli as a sharing service to Firefox
- * Open your Shaarli and `Login`
- * Click the `Tools` button in the top bar
- * Click the `✚Add to Firefox social` button and accept the activation.
+- Open your Shaarli and `Login`
+- Click the `Tools` button in the top bar
+- Click the `✚Add to Firefox social` button and accept the activation.
### Sharing links using Firefox share
- * Add the sharing service as described above
- * When you are visiting a webpage you would like to share with Shaarli, click the Firefox _Share_ button [images/firefoxshare.png](images/firefoxshare.png)
- * You can edit your link before and after saving, just like the bookmarklet above.
+- Add the sharing service as described above
+- When you are visiting a webpage you would like to share with Shaarli,
+ click the Firefox _Share_ button [images/firefoxshare.png](images/firefoxshare.png)
+- You can edit your link before and after saving, just like the bookmarklet above.
-| | Your Shaarli instance must be hosted on an HTTPS (SSL/TLS secure connection) enabled server for Firefox Share to work. Firefox Share will not work over plain HTTP connections. |
-|------|-------------------------------------------------------------------------------|
+_Your Shaarli instance must be hosted on an HTTPS (SSL/TLS secure connection)
+enabled server for Firefox Share to work. Firefox Share will not work over
+plain HTTP connections._
## Introduction
### PGP and GPG
-[Gnu Privacy Guard](https://gnupg.org/) (GnuPG) is an Open Source implementation of the [Pretty Good
-Privacy](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP) (OpenPGP) specification. Its main purposes are digital authentication,
-signature and encryption.
+[Gnu Privacy Guard](https://gnupg.org/) (GnuPG) is an Open Source implementation of the
+[Pretty Good Privacy](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP)
+(OpenPGP) specification. Its main purposes are digital authentication, signature and encryption.
It is often used by the [FLOSS](https://en.wikipedia.org/wiki/Free_and_open-source_software) community to verify:
+
- Linux package signatures: Debian [SecureApt](https://wiki.debian.org/SecureApt), ArchLinux [Master
Keys](https://www.archlinux.org/master-keys/)
- [SCM](https://en.wikipedia.org/wiki/Revision_control) releases & maintainer identity
> You MUST understand that presence of data in the keyserver (pools) in no way connotes trust. Anyone can generate a key, with any name or email address, and upload it. All security and trust comes from evaluating security at the “object level”, via PGP Web-Of-Trust signatures. This keyserver makes it possible to retrieve keys, looking them up via various indices, but the collection of keys in this public pool is KNOWN to contain malicious and fraudulent keys. It is the common expectation of server operators that users understand this and use software which, like all known common OpenPGP implementations, evaluates trust accordingly. This expectation is so common that it is not normally explicitly stated.
Trust can be gained by having your key signed by other people (and signing their key back, too :) ), for instance during [key signing parties](https://en.wikipedia.org/wiki/Key_signing_party), see:
+
- [The Keysigning party HOWTO](http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html)
- [Web of trust](https://en.wikipedia.org/wiki/Web_of_trust)
-[**I am a developer.** Developer API.](#developer-api)
+[**I am a developer: ** Developer API](#developer-api)
-[**I am a template designer.** Guide for template designer.](#guide-for-template-designer)
+[**I am a template designer: ** Guide for template designers](#guide-for-template-designer)
+
+---
## Developer API
The plugin system let you:
- * insert content into specific places across templates.
- * alter data before templates rendering.
- * alter data before saving new links.
+- insert content into specific places across templates.
+- alter data before templates rendering.
+- alter data before saving new links.
### How can I create a plugin for Shaarli?
Parameters:
- - data: see [$data section](https://github.com/shaarli/Shaarli/wiki/Plugin-System#plugins-data)
- - conf: the `ConfigManager` instance.
+- data: see [$data section](https://github.com/shaarli/Shaarli/wiki/Plugin-System#plugins-data)
+- conf: the `ConfigManager` instance.
For exemple, if my plugin want to add data to the header, this function is needed:
Each file contain two keys:
- * `description`: plugin description
- * `parameters`: user parameter names, separated by a `;`.
-
* `parameter.<PARAMETER_NAME>`: add a text description the specified parameter.
+- `description`: plugin description
+- `parameters`: user parameter names, separated by a `;`.
+
- `parameter.<PARAMETER_NAME>`: add a text description the specified parameter.
> Note: In PHP, `parse_ini_file()` seems to want strings to be between by quotes `"` in the ini file.
`$data` is an array containing:
- * `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
- * `_LOGGEDIN_`: true if user is logged in, false otherwise.
+- `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
+- `_LOGGEDIN_`: true if user is logged in, false otherwise.
##### Template placeholders
List of placeholders:
- * `buttons_toolbar`: after the list of buttons in the header.
+- `buttons_toolbar`: after the list of buttons in the header.
- * `fields_toolbar`: after search fields in the header.
+- `fields_toolbar`: after search fields in the header.
> Note: This will only be called in linklist.
`$data` is an array containing:
- * `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
- * `_LOGGEDIN_`: true if user is logged in, false otherwise.
+- `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
+- `_LOGGEDIN_`: true if user is logged in, false otherwise.
##### Template placeholders
List of placeholders:
- * `css_files`: called after loading default CSS.
+- `css_files`: called after loading default CSS.
> Note: only add the path of the CSS file. E.g: `plugins/demo_plugin/custom_demo.css`.
`$data` is an array containing:
- * `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
- * `_LOGGEDIN_`: true if user is logged in, false otherwise.
+- `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
+- `_LOGGEDIN_`: true if user is logged in, false otherwise.
##### Template placeholders
List of placeholders:
- * `text`: called after the end of the footer text.
- * `endofpage`: called at the end of the page.
+- `text`: called after the end of the footer text.
+- `endofpage`: called at the end of the page.
- * `js_files`: called at the end of the page, to include custom JS scripts.
+- `js_files`: called at the end of the page, to include custom JS scripts.
> Note: only add the path of the JS file. E.g: `plugins/demo_plugin/custom_demo.js`.
`$data` is an array containing:
- * `_LOGGEDIN_`: true if user is logged in, false otherwise.
- * All templates data, including links.
+- `_LOGGEDIN_`: true if user is logged in, false otherwise.
+- All templates data, including links.
##### Template placeholders
List of placeholders:
- * `action_plugin`: next to the button "private only" at the top and bottom of the page.
+- `action_plugin`: next to the button "private only" at the top and bottom of the page.
- * `link_plugin`: for every link, between permalink and link URL.
+- `link_plugin`: for every link, between permalink and link URL.
- * `plugin_start_zone`: before displaying the template content.
+- `plugin_start_zone`: before displaying the template content.
- * `plugin_end_zone`: after displaying the template content.
+- `plugin_end_zone`: after displaying the template content.
`$data` is an array containing:
- * All templates data.
+- All templates data.
##### Template placeholders
List of placeholders:
- * `edit_link_plugin`: after tags field.
+- `edit_link_plugin`: after tags field.
`$data` is an array containing:
- * All templates data.
+- All templates data.
##### Template placeholders
List of placeholders:
- * `tools_plugin`: at the end of the page.
+- `tools_plugin`: at the end of the page.
`$data` is an array containing:
- * `_LOGGEDIN_`: true if user is logged in, false otherwise.
- * All templates data.
+- `_LOGGEDIN_`: true if user is logged in, false otherwise.
+- All templates data.
##### Template placeholders
List of placeholders:
- * `plugin_start_zone`: before displaying the template content.
-
- * `plugin_end_zone`: after displaying the template content.
+- `plugin_start_zone`: before displaying the template content.
+- `plugin_end_zone`: after displaying the template content.
`$data` is an array containing:
- * `_LOGGEDIN_`: true if user is logged in, false otherwise.
- * All templates data.
+- `_LOGGEDIN_`: true if user is logged in, false otherwise.
+- All templates data.
##### Template placeholders
List of placeholders:
- * `plugin_start_zone`: before displaying the template content.
-
- * `plugin_end_zone`: after displaying the template content.
+- `plugin_start_zone`: before displaying the template content.
+- `plugin_end_zone`: after displaying the template content.
For each tag, the following placeholder can be used:
- * `tag_plugin`: after each tag
+- `tag_plugin`: after each tag
`$data` is an array containing:
- * `_LOGGEDIN_`: true if user is logged in, false otherwise.
- * All templates data.
+- `_LOGGEDIN_`: true if user is logged in, false otherwise.
+- All templates data.
##### Template placeholders
List of placeholders:
- * `plugin_start_zone`: before displaying the template content.
-
- * `plugin_end_zone`: after displaying the template content.
+- `plugin_start_zone`: before displaying the template content.
+- `plugin_end_zone`: after displaying the template content.
For each tag, the following placeholder can be used:
- * `tag_plugin`: after each tag
+- `tag_plugin`: after each tag
#### render_daily
`$data` is an array containing:
- * `_LOGGEDIN_`: true if user is logged in, false otherwise.
- * All templates data, including links.
+- `_LOGGEDIN_`: true if user is logged in, false otherwise.
+- All templates data, including links.
##### Template placeholders
List of placeholders:
- * `link_plugin`: used at bottom of each link.
+- `link_plugin`: used at bottom of each link.
- * `plugin_start_zone`: before displaying the template content.
-
- * `plugin_end_zone`: after displaying the template content.
+- `plugin_start_zone`: before displaying the template content.
+- `plugin_end_zone`: after displaying the template content.
#### render_feed
`$data` is an array containing:
- * `_LOGGEDIN_`: true if user is logged in, false otherwise.
- * `_PAGE_`: containing either `rss` or `atom`.
- * All templates data, including links.
+- `_LOGGEDIN_`: true if user is logged in, false otherwise.
+- `_PAGE_`: containing either `rss` or `atom`.
+- All templates data, including links.
##### Template placeholders
List of placeholders:
- * `feed_plugins_header`: used as a header tag in the feed.
+- `feed_plugins_header`: used as a header tag in the feed.
For each links:
- * `feed_plugins`: additional tag for every link entry.
+- `feed_plugins`: additional tag for every link entry.
#### save_link
`$data` is an array containing the link being saved:
- * id
- * title
- * url
- * shorturl
- * description
- * private
- * tags
- * created
- * updated
+- id
+- title
+- url
+- shorturl
+- description
+- private
+- tags
+- created
+- updated
#### delete_link
`$data` is an array containing the link being saved:
- * id
- * title
- * url
- * shorturl
- * description
- * private
- * tags
- * created
- * updated
+- id
+- title
+- url
+- shorturl
+- description
+- private
+- tags
+- created
+- updated
## Guide for template designer
Aside from classic RainTPL loops, plugins order is handle by JavaScript. You can just include `plugin_admin.js`, only if:
- * you're using a table.
- * you call orderUp() and orderUp() onclick on arrows.
- * you add data-line and data-order to your rows.
+- you're using a table.
+- you call orderUp() and orderUp() onclick on arrows.
+- you add data-line and data-order to your rows.
Otherwise, you can use your own JS as long as this field is send by the form:
If you want to install a third party plugin:
- * Download it.
- * Put it in the `plugins` directory in Shaarli's installation folder.
- * Make sure you put it correctly:
+- Download it.
+- Put it in the `plugins` directory in Shaarli's installation folder.
+- Make sure you put it correctly:
```
| index.php
JWT resources :
- * [jwt.io](https://jwt.io) (including a list of client per language).
- * RFC : https://tools.ietf.org/html/rfc7519
- * https://float-middle.com/json-web-tokens-jwt-vs-sessions/
- * HackerNews thread: https://news.ycombinator.com/item?id=11929267
+- [jwt.io](https://jwt.io) (including a list of client per language).
+- RFC : https://tools.ietf.org/html/rfc7519
+- https://float-middle.com/json-web-tokens-jwt-vs-sessions/
+- HackerNews thread: https://news.ycombinator.com/item?id=11929267
### Shaarli JWT Token
Feeds are available in ATOM with `?do=atom` and RSS with `do=RSS`.
Options:
+
- You can use `permalinks` in the feed URL to get permalink to Shaares instead of direct link to shaared URL.
- E.G. `https://my.shaarli.domain/?do=atom&permalinks`.
- You can use `nb` parameter in the feed URL to specify the number of Shaares you want in a feed (default if not specified: `50`). The keyword `all` is available if you want everything.
It is possible to filter RSS/ATOM feeds and Picture Wall on a Shaarli to **only display results of a specific search, or for a specific tag**.
For example, if you want to subscribe only to links tagged `photography`:
+
- Go to the desired Shaarli instance.
- Search for the `photography` tag in the _Filter by tag_ box. Links tagged `photography` are displayed.
- Click on the `RSS Feed` button.
## Prerequisites
This guide assumes that you have:
+
- a GPG key matching your GitHub authentication credentials
- i.e., the email address identified by the GPG key is the same as the one in your `~/.gitconfig`
- a GitHub fork of Shaarli
```
-## Increment the version code, updated docs, create and push a signed tag
+## Increment the version code, update docs, create and push a signed tag
### Generate documentation
```bash
$ cd /path/to/shaarli
### Create a GitHub release from a Git tag
From the previously drafted release:
+
- edit the release notes (if needed)
- specify the appropriate Git tag
- publish the release
### Generate and upload all-in-one release archives
Users with a shared hosting may have:
+
- no SSH access
- no possibility to install PHP packages or server extensions
- no possibility to run scripts
```
This will create the following archives:
+
- `shaarli-vX.Y.Z-full.tar`
- `shaarli-vX.Y.Z-full.zip`
## Client browser
-* Shaarli relies on `HTTP_REFERER` for some functions (like redirects and clicking on tags). If you have disabled or masqueraded `HTTP_REFERER` in your browser, some features of Shaarli may not work
+- Shaarli relies on `HTTP_REFERER` for some functions (like redirects and clicking on tags). If you have disabled or masqueraded `HTTP_REFERER` in your browser, some features of Shaarli may not work
## PHP
-* `magic_quotes` is an horrible option of PHP which is often activated on servers. No serious developer should rely on this horror to secure their code against SQL injections. You should disable it (and Shaarli expects this option to be disabled). Nevertheless, I have added code to cope with `magic_quotes` on, so you should not be bothered even on crappy hosts.
+- `magic_quotes` is an horrible option of PHP which is often activated on servers. No serious developer should rely on this horror to secure their code against SQL injections. You should disable it (and Shaarli expects this option to be disabled). Nevertheless, I have added code to cope with `magic_quotes` on, so you should not be bothered even on crappy hosts.
## Server and sessions
-* Directories are protected using `.htaccess` files
-* Forms are protected against XSRF (Cross-site requests forgery):
- * 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.
+- Directories are protected using `.htaccess` files
+- Forms are protected against XSRF (Cross-site requests forgery):
+ - 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.
## Shaarli datastore and configuration
-* 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.
-* 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.
-* The database looks like this:
+- 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.
+- 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.
+- The database looks like this:
+
```php
<?php /* zP1ZjxxJtiYIvvevEPJ2lDOaLrZv7o...
...ka7gaco/Z+TFXM2i7BlfMf8qxpaSSYfKlvqv/x8= */ ?>
```
-* Small hashes are used to make a link to an entry in Shaarli. They are unique. In fact, the date of the items (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 `@`.
+- Small hashes are used to make a link to an entry in Shaarli. They are unique. In fact, the date of the items (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 `@`.
## Prerequisites
### Shaarli
-* Shaarli is installed in a directory readable/writeable by the user
-* the correct read/write permissions have been granted to the web server _user and/or group_
-* for HTTPS / SSL:
- * a key pair (public, private) and a certificate have been generated
- * the appropriate server SSL extension is installed and active
+- Shaarli is installed in a directory readable/writeable by the user
+- the correct read/write permissions have been granted to the web server _user and/or group_
+- for HTTPS / SSL:
+ - a key pair (public, private) and a certificate have been generated
+ - the appropriate server SSL extension is installed and active
### HTTPS, TLS and self-signed certificates
Related guides:
-* [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php)
-* [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority)
-* Generate a self-signed certificate (will trigger browser warnings) with apache2: `make-ssl-cert generate-default-snakeoil --force-overwrite` will create `/etc/ssl/certs/ssl-cert-snakeoil.pem` and `/etc/ssl/private/ssl-cert-snakeoil.key`
+
+- [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php)
+- [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority)
+- Generate a self-signed certificate (will trigger browser warnings) with apache2:
+ `make-ssl-cert generate-default-snakeoil --force-overwrite` will create `/etc/ssl/certs/ssl-cert-snakeoil.pem` and `/etc/ssl/private/ssl-cert-snakeoil.key`
### Proxies
If Shaarli is served behind a proxy (i.e. there is a proxy server between clients and the web server hosting Shaarli), please refer to the proxy server documentation for proper configuration. In particular, you have to ensure that the following server variables are properly set:
-- `X-Forwarded-Proto`;
-- `X-Forwarded-Host`;
-- `X-Forwarded-For`.
+
+- `X-Forwarded-Proto`
+- `X-Forwarded-Host`
+- `X-Forwarded-For`
See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%93&q=label%3Aproxy+) issues.
This configuration will log both Apache and PHP errors, which may prove useful to identify server configuration errors.
See:
-* [Apache/PHP - error log per VirtualHost](http://stackoverflow.com/q/176) (StackOverflow)
-* [PHP: php_value vs php_admin_value and the use of php_flag explained](https://ma.ttias.be/php-php_value-vs-php_admin_value-and-the-use-of-php_flag-explained/)
+
+- [Apache/PHP - error log per VirtualHost](http://stackoverflow.com/q/176) (StackOverflow)
+- [PHP: php_value vs php_admin_value and the use of php_flag explained](https://ma.ttias.be/php-php_value-vs-php_admin_value-and-the-use-of-php_flag-explained/)
```apache
<VirtualHost *:80>
Nginx does not natively interpret PHP scripts; to this effect, we will run a [FastCGI](https://en.wikipedia.org/wiki/FastCGI) service, to which Nginx's FastCGI module will proxy all requests to PHP resources.
Required packages:
+
- [nginx](http://nginx.org)
- [php-fpm](http://php-fpm.org) - PHP FastCGI Process Manager
Official documentation:
+
- [Beginner's guide](http://nginx.org/en/docs/beginners_guide.html)
- [ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html)
- [Pitfalls](http://wiki.nginx.org/Pitfalls)
Community resources:
+
- [Server-side TLS (Nginx)](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) (Mozilla)
- [PHP configuration examples](http://kbeezie.com/nginx-configuration-examples/) (Karl Blessing)
### Common setup
Once Nginx and PHP-FPM are installed, we need to ensure:
+
- Nginx and PHP-FPM are running using the _same user and group_
- both these user and group have
- `read` permissions for Shaarli resources
- `execute` permissions for Shaarli directories _AND_ their parent directories
On a production server:
+
- `user:group` will likely be `http:http`, `www:www` or `www-data:www-data`
- files will be located under `/var/www`, `/var/http` or `/usr/share/nginx`
On a development server:
+
- files may be located in a user's home directory
- in this case, make sure both Nginx and PHP-FPM are running as the local user/group!
For all following configuration examples, this user/group pair will be used:
+
- `user:group = john:users`,
which corresponds to the following service configuration:
### Modular
The previous setup is sufficient for development purposes, but has several major caveats:
+
- every content that does not match the PHP rule will be sent to client browsers:
- dotfiles - in our case, `.htaccess`
- temporary files, e.g. Vim or Emacs files: `index.php~`
```
### Redirect HTTP to HTTPS
-Assuming you have generated a (self-signed) key and certificate, and they are located under `/home/john/ssl/localhost.{key,crt}`, it is pretty straightforward to set an HTTP (:80) to HTTPS (:443) redirection to force SSL/TLS usage.
+Assuming you have generated a (self-signed) key and certificate, and they are
+located under `/home/john/ssl/localhost.{key,crt}`, it is pretty straightforward
+to set an HTTP (:80) to HTTPS (:443) redirection to force SSL/TLS usage.
```nginx
# /etc/nginx/nginx.conf
### Supported versions
Version | Status | Shaarli compatibility
:---:|:---:|:---:
-7.1 | Supported (v0.9.x) | :white_check_mark:
-7.0 | Supported | :white_check_mark:
-5.6 | Supported | :white_check_mark:
-5.5 | EOL: 2016-07-10 | :white_check_mark:
-5.4 | EOL: 2015-09-14 | :white_check_mark: (up to Shaarli 0.8.x)
-5.3 | EOL: 2014-08-14 | :white_check_mark: (up to Shaarli 0.8.x)
+7.1 | Supported (v0.9.x) | Yes
+7.0 | Supported | Yes
+5.6 | Supported | Yes
+5.5 | EOL: 2016-07-10 | Yes
+5.4 | EOL: 2015-09-14 | Yes (up to Shaarli 0.8.x)
+5.3 | EOL: 2014-08-14 | Yes (up to Shaarli 0.8.x)
See also:
- [Travis configuration](https://github.com/shaarli/Shaarli/blob/master/.travis.yml)
## php.ini
PHP settings are defined in:
+
- a main configuration file, usually found under `/etc/php5/php.ini`; some distributions provide different configuration environments, e.g.
- `/etc/php5/php.ini` - used when running console scripts
- `/etc/php5/apache2/php.ini` - used when a client requests PHP resources from Apache
## fail2ban
`fail2ban` is an intrusion prevention framework that reads server (Apache, SSH, etc.) and uses `iptables` profiles to block brute-force attempts:
+
- [Official website](http://www.fail2ban.org/wiki/index.php/Main_Page)
- [Source code](https://github.com/fail2ban/fail2ban)
```
See:
-- http://www.robotstxt.org/
+
+- http://www.robotstxt.org
- http://www.robotstxt.org/robotstxt.html
- http://www.robotstxt.org/meta.html
### Credentials
-> You shouldn't edit those.
+_These settings should not be edited_
-**login**: Login username.
-**hash**: Generated password hash.
-**salt**: Password salt.
+- **login**: Login username.
+- **hash**: Generated password hash.
+- **salt**: Password salt.
### General
-**title**: Shaarli's instance title.
-**header_link**: Link to the homepage.
-**links_per_page**: Number of shaares displayed per page.
-**timezone**: See [the list of supported timezones](http://php.net/manual/en/timezones.php).
-**enabled_plugins**: List of enabled plugins.
+- **title**: Shaarli's instance title.
+- **header_link**: Link to the homepage.
+- **links_per_page**: Number of shaares displayed per page.
+- **timezone**: See [the list of supported timezones](http://php.net/manual/en/timezones.php).
+- **enabled_plugins**: List of enabled plugins.
### Security
-**session_protection_disabled**: Disable session cookie hijacking protection (not recommended).
-It might be useful if your IP adress often changes.
-**ban_after**: Failed login attempts before being IP banned.
-**ban_duration**: IP ban duration in seconds.
-**open_shaarli**: Anyone can add a new link while logged out if enabled.
-**trusted_proxies**: List of trusted IP which won't be banned after failed login attemps. Useful if Shaarli is behind a reverse proxy.
-**allowed_protocols**: List of allowed protocols in shaare URLs or markdown-rendered descriptions. Useful if you want to store `javascript:` links (bookmarklets) in Shaarli (default: `["ftp", "ftps", "magnet"]`).
+- **session_protection_disabled**: Disable session cookie hijacking protection (not recommended).
+ It might be useful if your IP adress often changes.
+- **ban_after**: Failed login attempts before being IP banned.
+- **ban_duration**: IP ban duration in seconds.
+- **open_shaarli**: Anyone can add a new link while logged out if enabled.
+- **trusted_proxies**: List of trusted IP which won't be banned after failed login attemps. Useful if Shaarli is behind a reverse proxy.
+- **allowed_protocols**: List of allowed protocols in shaare URLs or markdown-rendered descriptions. Useful if you want to store `javascript:` links (bookmarklets) in Shaarli (default: `["ftp", "ftps", "magnet"]`).
### Resources
-**data_dir**: Data directory.
-**datastore**: Shaarli's links database file path.
-**history**: Shaarli's operation history file path.
-**updates**: File path for the ran updates file.
-**log**: Log file path.
-**update_check**: Last update check file path.
-**raintpl_tpl**: Templates directory.
-**raintpl_tmp**: Template engine cache directory.
-**thumbnails_cache**: Thumbnails cache directory.
-**page_cache**: Shaarli's internal cache directory.
-**ban_file**: Banned IP file path.
+- **data_dir**: Data directory.
+- **datastore**: Shaarli's links database file path.
+- **history**: Shaarli's operation history file path.
+- **updates**: File path for the ran updates file.
+- **log**: Log file path.
+- **update_check**: Last update check file path.
+- **raintpl_tpl**: Templates directory.
+- **raintpl_tmp**: Template engine cache directory.
+- **thumbnails_cache**: Thumbnails cache directory.
+- **page_cache**: Shaarli's internal cache directory.
+- **ban_file**: Banned IP file path.
### Updates
-**check_updates**: Enable or disable update check to the git repository.
-**check_updates_branch**: Git branch used to check updates (e.g. `stable` or `master`).
-**check_updates_interval**: Look for new version every N seconds (default: every day).
+- **check_updates**: Enable or disable update check to the git repository.
+- **check_updates_branch**: Git branch used to check updates (e.g. `stable` or `master`).
+- **check_updates_interval**: Look for new version every N seconds (default: every day).
### Privacy
-**default_private_links**: Check the private checkbox by default for every new link.
-**hide_public_links**: All links are hidden while logged out.
-**hide_timestamps**: Timestamps are hidden.
+- **default_private_links**: Check the private checkbox by default for every new link.
+- **hide_public_links**: All links are hidden while logged out.
+- **hide_timestamps**: Timestamps are hidden.
### Feed
-**rss_permalinks**: Enable this to redirect RSS links to Shaarli's permalinks instead of shaared URL.
-**show_atom**: Display ATOM feed button.
+- **rss_permalinks**: Enable this to redirect RSS links to Shaarli's permalinks instead of shaared URL.
+- **show_atom**: Display ATOM feed button.
### Thumbnail
-**enable_thumbnails**: Enable or disable thumbnail display.
-**enable_localcache**: Enable or disable local cache.
+- **enable_thumbnails**: Enable or disable thumbnail display.
+- **enable_localcache**: Enable or disable local cache.
### Redirector
-**url**: Redirector URL, such as `anonym.to`.
-**encode_url**: Enable this if the redirector needs encoded URL to work properly.
+- **url**: Redirector URL, such as `anonym.to`.
+- **encode_url**: Enable this if the redirector needs encoded URL to work properly.
## Configuration file example
## Additional configuration
-The playvideos plugin may require that you adapt your server's
+The `playvideos` plugin may require that you adapt your server's
[Content Security Policy](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md#troubleshooting)
-configuration to work properly.[](.html)
+configuration to work properly.
## WIP
This topic is currently being discussed here:
+
- [Fix coding style (static analysis)](https://github.com/shaarli/Shaarli/issues/95) (#95)
- [Continuous Integration tools & features](https://github.com/shaarli/Shaarli/issues/130) (#130)
Static analysis tools can be installed with Composer, and used through Shaarli's [Makefile](https://github.com/shaarli/Shaarli/blob/master/Makefile).
For an overview of the available features, see:
+
- [Code quality: Makefile to run static code checkers](https://github.com/shaarli/Shaarli/pull/124) (#124)
- [Run PHPCS against different coding standards](https://github.com/shaarli/Shaarli/pull/276) (#276)
## Custom CSS
Shaarli's appearance can be modified by adding CSS rules to:
+
- Shaarli < `v0.9.0`: `inc/user.css`
- Shaarli >= `v0.9.0`: `data/user.css`
_WARNING - This feature is currently being worked on and will be improved in the next releases. Experimental._
Installation:
+
- find a theme you'd like to install
- copy or clone the theme folder under `tpl/<a_sweet_theme>`
- enable the theme:
## Example installation: AlbinoMouse theme
With the following configuration:
+
- Apache 2 / PHP 5.6
- user sites are enabled, e.g. `/home/user/public_html/somedir` is served as `http://localhost/~user/somedir`
- `http` is the name of the Apache user
- fill the install form
- log in to Shaarli
-Edit Shaarli's [configuration|Shaarli configuration](configuration|Shaarli configuration):
+Edit Shaarli's [configuration](Shaarli-configuration):
```bash
# the file should be owned by Apache, thus not writeable => sudo
$ sudo sed -i s=tpl=tpl/albinomouse-template=g shaarli/data/config.php
Depending on its configuration and installed plugins, the browser may remove or alter (spoof) HTTP referers, thus preventing Shaarli from properly redirecting between pages.
See:
+
- [HTTP referer](https://en.wikipedia.org/wiki/HTTP_referer) (Wikipedia)
- [Improve online privacy by controlling referrer information](http://www.ghacks.net/2015/01/22/improve-online-privacy-by-controlling-referrer-information/)
- [Better security, privacy and anonymity in Firefox](http://b.agilob.net/better-security-privacy-and-anonymity-in-firefox/)
HTTP settings are available by browsing `about:config`, here are the available settings and their values.
`network.http.sendRefererHeader` - determines when to send the Referer HTTP header
-- 0: Never send the referring URL
+
+- `0`: Never send the referring URL
- not recommended, may break some sites
-- 1: Send only on clicked links
-- 2 (default): Send for links and images
+- `1`: Send only on clicked links
+- `2` (default): Send for links and images
`network.http.referer.XOriginPolicy` - Cross-domain origin policy
-- 0 (default): Always send
-- 1: Send if base domains match
-- 2: Send if hosts match
+
+- `0` (default): Always send
+- `1`: Send if base domains match
+- `2`: Send if hosts match
`network.http.referer.spoofSource` - Referer spoofing (~faking)
-- false (default): real referer
-- true: spoof referer (use target URI as referer)
- - known to break some functionality in Shaarli
+
+- `false` (default): real referer
+- `true`: spoof referer (use target URI as referer)
+ - known to break some functionality in Shaarli
`network.http.referer.trimmingPolicy` - trim the URI not to send a full Referer
-- 0 (default): send full URI
-- 1: scheme+host+port+path
-- 2: scheme+host+port
+
+- `0`: (default): send full URI
+- `1`: scheme+host+port+path
+- `2`: scheme+host+port
### Firefox, localhost and redirections
-`localhost` is not a proper Fully Qualified Domain Name (FQDN); if Firefox has been set up to spoof referers, or only accept requests from the same base domain/host, Shaarli redirections will not work properly.
+`localhost` is not a proper Fully Qualified Domain Name (FQDN); if Firefox has
+been set up to spoof referers, or only accept requests from the same base domain/host,
+Shaarli redirections will not work properly.
To solve this, assign a local domain to your host, e.g.
```
### Old PHP versions
- * On **free.fr** : free.fr now support php 5.6.x([link](http://les.pages.perso.chez.free.fr/migrations/php5v6.io))and so support now the tag autocompletion but you have to do the following : At the root of your webspace create a `sessions` directory and a `.htaccess` file containing:
+On **free.fr**: free.fr now supports php 5.6.x([link](http://les.pages.perso.chez.free.fr/migrations/php5v6.io))
+and so support now the tag autocompletion but you have to do the following.
+
+At the root of your webspace create a `sessions` directory and a `.htaccess` file containing:
-```ini
+```xml
<IfDefine Free>
php56 1
</IfDefine>
```
- * If you have an error such as: `Parse error: syntax error, unexpected '=', expecting '(' in /links/index.php on line xxx`, it means that your host is using php4, not php5. Shaarli requires php 5.1. Try changing the file extension to `.php5`
- * On **1and1** : If you add the link from the page (and not from the bookmarklet), Shaarli will no be able to get the title of the page. You will have to enter it manually. (Because they have disabled the ability to download a file through HTTP).
- * If you have the error `Warning: file_get_contents() [function.file-get-contents]: URL file-access is disabled in the server configuration in /…/index.php on line xxx`, it means that your host has disabled the ability to fetch a file by HTTP in the php config (Typically in 1and1 hosting). Bad host. Change host. Or comment the following lines:
+- If you have an error such as: `Parse error: syntax error, unexpected '=', expecting '(' in /links/index.php on line xxx`, it means that your host is using php4, not php5. Shaarli requires php 5.1. Try changing the file extension to `.php5`
+- On **1and1** : If you add the link from the page (and not from the bookmarklet), Shaarli will no be able to get the title of the page. You will have to enter it manually. (Because they have disabled the ability to download a file through HTTP).
+- If you have the error `Warning: file_get_contents() [function.file-get-contents]: URL file-access is disabled in the server configuration in /…/index.php on line xxx`, it means that your host has disabled the ability to fetch a file by HTTP in the php config (Typically in 1and1 hosting). Bad host. Change host. Or comment the following lines:
```php
//list($status,$headers,$data) = getHTTP($url,4); // Short timeout to keep the application responsive.
//if (strpos($status,'200 OK')) $title=html_extract_title($data);
```
- * On hosts which forbid outgoing HTTP requests (such as free.fr), some thumbnails will not work.
- * On **lost-oasis**, RSS doesn't work correctly, because of this message at the begining of the RSS/ATOM feed : `<? // tout ce qui est charge ici (generalement des includes et require) est charge en permanence. ?>`. To fix this, remove this message from `php-include/prepend.php`
+- On hosts which forbid outgoing HTTP requests (such as free.fr), some thumbnails will not work.
+- On **lost-oasis**, RSS doesn't work correctly, because of this message at the begining of the RSS/ATOM feed : `<? // tout ce qui est charge ici (generalement des includes et require) est charge en permanence. ?>`. To fix this, remove this message from `php-include/prepend.php`
### Dates are not properly formatted
On **CentOS**/RedHat derivatives, you may need to install the `php-mbstring` package.
-
### My session expires! I can't stay logged in
This can be caused by several things:
-* Your php installation may not have a proper directory setup for session files. (eg. on Free.fr you need to create a `session` directory on the root of your website.) You may need to create the session directory of set it up.
-* Most hosts regularly clean the temporary and session directories. Your host may be cleaning those directories too aggressively (eg.OVH hosts), forcing an expire of the session. You may want to set the session directory in your web root. (eg. Create the `sessions` subdirectory and add `ini_set('session.save_path', $_SERVER['DOCUMENT_ROOT'].'/../sessions');`. Make sure this directory is not browsable !)
-* If your IP address changes during surfing, Shaarli will force expire your session for security reasons (to prevent session cookie hijacking). This can happen when surfing from WiFi or 3G (you may have switched WiFi/3G access point), or in some corporate/university proxies which use load balancing (and may have proxies with several external IP addresses).
-* Some browser addons may interfer with HTTP headers (ipfuck/ipflood/GreaseMonkey…). Try disabling those.
-* You may be using OperaTurbo or OperaMini, which use their own proxies which may change from time to time.
-* If you have another application on the same webserver where Shaarli is installed, these application may forcefully expire php sessions.
+- Your php installation may not have a proper directory setup for session files. (eg. on Free.fr you need to create a `session` directory on the root of your website.) You may need to create the session directory of set it up.
+- Most hosts regularly clean the temporary and session directories. Your host may be cleaning those directories too aggressively (eg.OVH hosts), forcing an expire of the session. You may want to set the session directory in your web root. (eg. Create the `sessions` subdirectory and add `ini_set('session.save_path', $_SERVER['DOCUMENT_ROOT'].'/../sessions');`. Make sure this directory is not browsable !)
+- If your IP address changes during surfing, Shaarli will force expire your session for security reasons (to prevent session cookie hijacking). This can happen when surfing from WiFi or 3G (you may have switched WiFi/3G access point), or in some corporate/university proxies which use load balancing (and may have proxies with several external IP addresses).
+- Some browser addons may interfer with HTTP headers (ipfuck/ipflood/GreaseMonkey…). Try disabling those.
+- You may be using OperaTurbo or OperaMini, which use their own proxies which may change from time to time.
+- If you have another application on the same webserver where Shaarli is installed, these application may forcefully expire php sessions.
## Sessions do not seem to work correctly on your server
The framework used is [PHPUnit](https://phpunit.de/); it can be installed with [Composer](https://getcomposer.org/), which is a dependency management tool.
Regarding Composer, you can either use:
-* a system-wide version, e.g. installed through your distro's package manager
-* a local version, downloadable [here](https://getcomposer.org/download/)
+
+- a system-wide version, e.g. installed through your distro's package manager
+- a local version, downloadable [here](https://getcomposer.org/download/)
#### Sample usage
By default, PHPUnit will run all suitable tests found under the `tests` directory.
Each test has 3 possible outcomes:
-* `.` - success
-* `F` - failure: the test was run but its results are invalid
- * the code does not behave as expected
- * dependencies to external elements: globals, session, cache...
-* `E` - error: something went wrong and the tested code has crashed
- * typos in the code, or in the test code
- * dependencies to missing external elements
+
+- `.` - success
+- `F` - failure: the test was run but its results are invalid
+ - the code does not behave as expected
+ - dependencies to external elements: globals, session, cache...
+- `E` - error: something went wrong and the tested code has crashed
+ - typos in the code, or in the test code
+ - dependencies to missing external elements
If Xdebug has been installed and activated, two coverage reports will be generated:
-* a summary in the console
-* a detailed HTML report with metrics for tested code
- * to open it in a web browser: `firefox coverage/index.html &`
+
+- a summary in the console
+- a detailed HTML report with metrics for tested code
+ - to open it in a web browser: `firefox coverage/index.html &`
### Executing specific tests
### Backup your data
Shaarli stores all user data under the `data` directory:
+
- `data/config.php` - main configuration file
- `data/datastore.php` - bookmarked links
- `data/ipbans.php` - banned IP addresses
See [Shaarli configuration](Shaarli configuration) for more information about Shaarli resources.
It is recommended to backup this repository _before_ starting updating/upgrading Shaarli:
+
- users with SSH access: copy or archive the directory to a temporary location
- users with FTP access: download a local copy of your Shaarli installation using your favourite client
If you have installed Shaarli from [Sebsauvage's original Git repository](https://github.com/sebsauvage/Shaarli), you can use [Git remotes](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) to update your working copy.
The following guide assumes that:
+
- you have a basic knowledge of Git [branching](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) and [remote repositories](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes)
- the default remote is named `origin` and points to Sebsauvage's repository
- the current branch is `master`
## Troubleshooting
-If the solutions provided here doesn't work, please open an issue specifying which version you're upgrading from and to.
+If the solutions provided here don't work, please open an issue specifying which version you're upgrading from and to.
### You must specify an integer as a key
Try to delete it and refresh your page while being logged in.
-#### `updates.txt` doesn't exists or doesn't contain `updateMethodDatastoreIds`
+#### `updates.txt` doesn't exist or doesn't contain `updateMethodDatastoreIds`
- 1. Create `data/updates.txt` if it doesn't exist.
- 2. Paste this string in the update file `;updateMethodRenameDashTags;`
- 3. Login to Shaarli.
- 4. Delete the update file.
- 5. Refresh.
+1. Create `data/updates.txt` if it doesn't exist
+2. Paste this string in the update file `;updateMethodRenameDashTags;`
+3. Login to Shaarli
+4. Delete the update file
+5. Refresh
### Changing the timestamp for a shaare
-* Look for `<input type="hidden" name="lf_linkdate" value="{$link.linkdate}">` in `tpl/editlink.tpl` (line 14)
-* Replace `type="hidden"` with `type="text"` from this line
-* A new date/time field becomes available in the edit/new link dialog.
-* You can set the timestamp manually by entering it in the format `YYYMMDD_HHMMS`.
+- Look for `<input type="hidden" name="lf_linkdate" value="{$link.linkdate}">` in `tpl/editlink.tpl` (line 14)
+- Replace `type="hidden"` with `type="text"` from this line
+- A new date/time field becomes available in the edit/new link dialog.
+- You can set the timestamp manually by entering it in the format `YYYMMDD_HHMMS`.
### See also
- * [Add a new custom field to shaares (example patch)](https://gist.github.com/nodiscc/8b0194921f059d7b9ad89a581ecd482c)
- * [Download CSS styles for shaarlis listed in an opml file](https://gist.github.com/nodiscc/dede231c92cab22c3ad2cc24d5035012)
- * [Copy an existing Shaarli installation over SSH, and serve it locally](https://gist.github.com/nodiscc/ed161c66e5b028b5299b0a3733d01c77)
- * [Create multiple Shaarli instances, generate an HTML index of them](https://gist.github.com/nodiscc/52e711cda3bc47717c16065231cf6b20)
\ No newline at end of file
+- [Add a new custom field to shaares (example patch)](https://gist.github.com/nodiscc/8b0194921f059d7b9ad89a581ecd482c)
+- [Download CSS styles for shaarlis listed in an opml file](https://gist.github.com/nodiscc/dede231c92cab22c3ad2cc24d5035012)
+- [Copy an existing Shaarli installation over SSH, and serve it locally](https://gist.github.com/nodiscc/ed161c66e5b028b5299b0a3733d01c77)
+- [Create multiple Shaarli instances, generate an HTML index of them](https://gist.github.com/nodiscc/52e711cda3bc47717c16065231cf6b20)
Remarks:
- * This branch shouldn't be used for production as it isn't necessary stable.
- * 3rd party aren't required to be compatible with the latest changes.
- * Official plugins, themes and libraries (contained within Shaarli organization repos) must be compatible with the master branch.
- * The version in this branch is always `dev`.
+- This branch shouldn't be used for production as it isn't necessary stable.
+- 3rd party aren't required to be compatible with the latest changes.
+- Official plugins, themes and libraries (contained within Shaarli organization repos) must be compatible with the master branch.
+- The version in this branch is always `dev`.
## `v0.x` branch
Remarks:
- * Shaarli release pace isn't fast, and the stable branch might be a few months behind the latest release.
+- Shaarli release pace isn't fast, and the stable branch might be a few months behind the latest release.
## Releases
### Other usages
Though Shaarli is primarily a bookmarking application, it can serve other purposes
-(see [usage examples](https://github.com/shaarli/Shaarli/wiki#usage-examples)):
+(see [Features](Features)):
+
- micro-blogging
- pastebin
- online notepad
projects / github / shaarli / Shaarli.git / commitdiff
