-
327 ArthurHoaro <arthur@hoa.ro>
- 188 VirtualTam <virtualtam@flibidi.net>
+
472 ArthurHoaro <arthur@hoa.ro>
+ 201 VirtualTam <virtualtam@flibidi.net>
132 nodiscc <nodiscc@gmail.com>
56 Sébastien Sauvage <sebsauvage@sebsauvage.net>
15 Florian Eula <eula.florian@gmail.com>
13 Emilien Klein <emilien@klein.st>
12 Nicolas Danelon <hi@nicolasmd.com.ar>
- 7 Christophe HENRY <christophe.henry@sbgodin.fr>
+ 8 Christophe HENRY <christophe.henry@sbgodin.fr>
4 Alexandre Alapetite <alexandre@alapetite.fr>
4 David Sferruzza <david.sferruzza@gmail.com>
3 Teromene <teromene@teromene.fr>
1 Sbgodin <Sbgodin@users.noreply.github.com>
1 TsT <tst2005@gmail.com>
1 dimtion <zizou.xena@gmail.com>
+ 1 philipp-r <philipp-r@users.noreply.github.com>
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
</div>
<h1 id="browsing-and-searching">Browsing and searching</h1>
<h1 id="browsing-and-searching-1">Browsing and Searching</h1>
-<p>Status: DRAFT</p>
<p><embed src="(http://pix.toile-libre.org/upload/original/1455571378.png).html" /></p>
<h2 id="plain-text-search">Plain text search</h2>
<p>Use the <code>Search text</code> field to search in <em>any</em> of the fields of all links (Title, URL, Description...)</p>
<p>Use the <code>Filter by tags</code> field to restrict displayed links to entries tagged with one or multiple tags (use space to separate tags).</p>
<p><strong>Hidden tags:</strong> Tags starting with a dot <code>.</code> (example <code>.secret</code>) are private. They can only be seen and searched when logged in.</p>
<p>Alternatively you can use the <code>Tag cloud</code> to discover all tags and click on any of them to display related links.</p>
+<p>To search for links that are not tagged, enter <code>""</code> in the tag search field.</p>
<h2 id="filtering-rss-feedspicture-wall">Filtering RSS feeds/Picture wall</h2>
<p>RSS feeds can also be restricted to only return items matching a text/tag search: see <a href="RSS-feeds.html">RSS feeds</a>.</p>
</body>
#Browsing and searching
# Browsing and Searching
-Status: DRAFT
-
.html)
## Plain text search
Alternatively you can use the `Tag cloud` to discover all tags and click on any of them to display related links.
+To search for links that are not tagged, enter `""` in the tag search field.
+
## Filtering RSS feeds/Picture wall
RSS feeds can also be restricted to only return items matching a text/tag search: see [RSS feeds](RSS-feeds.html).
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<li><a href="http://sebsauvage.net/wiki/doku.php?id=php:shaarli:history">Original revisions history</a><a href=".html"></a></li>
<li><a href="https://www.shaarli.fr/my.php">Shaarli.fr/my</a> - Unofficial, unsupported (old fork) hosted Shaarlis provider, courtesy of <a href="https://github.com/DMeloni">DMeloni</a><a href=".html"></a></li>
</ul>
+<h3 id="articles-and-social-media-discussions">Articles and social media discussions</h3>
+<ul>
+<li>2016-09-22 - Hacker News - <a href="https://news.ycombinator.com/item?id=12552176" class="uri">https://news.ycombinator.com/item?id=12552176</a></li>
+<li>2015-08-15 - Reddit - <a href="https://www.reddit.com/r/selfhosted/comments/3h3zwh/question_about_migrating_from_wordpress_to_shaarli/">Question about migrating from WordPress to Shaarli.</a><a href=".html"></a></li>
+<li>2015-06-22 - Hacker News - <a href="https://news.ycombinator.com/item?id=9755366" class="uri">https://news.ycombinator.com/item?id=9755366</a></li>
+<li>2015-05-12 - Reddit - <a href="https://www.reddit.com/r/selfhosted/comments/35pkkc/shaarli_self_hosted_bookmarking_delicious_php/">shaarli - Self hosted Bookmarking / Delicious (PHP, MySQL)</a><a href=".html"></a></li>
+</ul>
<h3 id="third-party-plugins">Third party plugins</h3>
<ul>
<li><a href="https://github.com/kalvn/shaarli-plugin-autosave">autosave</a> by <a href="https://github.com/kalvn">@kalvn</a>: Automatically saves data when editing a link to avoid any loss in case of crash or unexpected shutdown.<a href=".html"></a></li>
<li><a href="https://github.com/ArthurHoaro/code-coloration">Code Coloration</a> by <a href="https://github.com/ArthurHoaro">@ArthurHoaro</a>: client side code syntax highlighter.<a href=".html"></a></li>
<li><a href="https://github.com/kalvn/shaarli-plugin-disqus">Disqus</a> by <a href="https://github.com/kalvn">@kalvn</a>: Adds Disqus comment system to your Shaarli.<a href=".html"></a></li>
<li><a href="https://github.com/NerosTie/emojione">emojione</a> by <a href="https://github.com/NerosTie">@NerosTie</a>: Add colorful emojis to your Shaarli.<a href=".html"></a></li>
+<li><a href="https://github.com/ericjuden/Shaarli-Google-Analytics-Plugin">google analytics</a> by <a href="http://github.com/ericjuden">@ericjuden</a>: Adds Google Analytics tracking support<a href=".html"></a></li>
<li><a href="https://github.com/ArthurHoaro/launch-plugin">launch</a> - Launch Plugin is a plugin designed to enhance and customize Launch Theme for Shaarli.<a href=".html"></a></li>
<li><a href="https://github.com/alexisju/social">social</a> by <a href="https://github.com/alexisju">@alexisju</a>: share links to social networks.<a href=".html"></a></li>
<li><a href="https://github.com/ArthurHoaro/shaarli2twitter">shaarli2twitter</a> by <a href="https://github.com/ArthurHoaro">@ArthurHoaro</a> - Automatically tweet your shared links from Shaarli<a href=".html"></a></li>
- [Original revisions history](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:history)[](.html)
- [Shaarli.fr/my](https://www.shaarli.fr/my.php) - Unofficial, unsupported (old fork) hosted Shaarlis provider, courtesy of [DMeloni](https://github.com/DMeloni)[](.html)
+### Articles and social media discussions
+- 2016-09-22 - Hacker News - https://news.ycombinator.com/item?id=12552176
+- 2015-08-15 - Reddit - [Question about migrating from WordPress to Shaarli.](https://www.reddit.com/r/selfhosted/comments/3h3zwh/question_about_migrating_from_wordpress_to_shaarli/)[](.html)
+- 2015-06-22 - Hacker News - https://news.ycombinator.com/item?id=9755366
+- 2015-05-12 - Reddit - [shaarli - Self hosted Bookmarking / Delicious (PHP, MySQL)](https://www.reddit.com/r/selfhosted/comments/35pkkc/shaarli_self_hosted_bookmarking_delicious_php/)[](.html)
### Third party plugins
* [Code Coloration](https://github.com/ArthurHoaro/code-coloration) by [@ArthurHoaro](https://github.com/ArthurHoaro): client side code syntax highlighter.[](.html)
* [Disqus](https://github.com/kalvn/shaarli-plugin-disqus) by [@kalvn](https://github.com/kalvn): Adds Disqus comment system to your Shaarli.[](.html)
* [emojione](https://github.com/NerosTie/emojione) by [@NerosTie](https://github.com/NerosTie): Add colorful emojis to your Shaarli.[](.html)
+ * [google analytics](https://github.com/ericjuden/Shaarli-Google-Analytics-Plugin) by [@ericjuden](http://github.com/ericjuden): Adds Google Analytics tracking support[](.html)
* [launch](https://github.com/ArthurHoaro/launch-plugin) - Launch Plugin is a plugin designed to enhance and customize Launch Theme for Shaarli.[](.html)
* [social](https://github.com/alexisju/social) by [@alexisju](https://github.com/alexisju): share links to social networks.[](.html)
* [shaarli2twitter](https://github.com/ArthurHoaro/shaarli2twitter) by [@ArthurHoaro](https://github.com/ArthurHoaro) - Automatically tweet your shared links from Shaarli[](.html)
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
</div>
<h1 id="directory-structure">Directory structure</h1>
<p>Here is the directory structure of Shaarli and the purpose of the different files:</p>
-<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"> <span class="ex">index.php</span> <span class="co"># Main program</span>
- <span class="ex">application/</span> <span class="co"># Shaarli classes</span>
+<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"> <span class="ex">index.php</span> # Main program
+ <span class="ex">application/</span> # Shaarli classes
├── <span class="ex">LinkDB.php</span>
└── <span class="ex">Utils.php</span>
- <span class="ex">tests/</span> <span class="co"># Shaarli unitary & functional tests</span>
+ <span class="ex">tests/</span> # Shaarli unitary <span class="kw">&</span> <span class="ex">functional</span> tests
├── <span class="ex">LinkDBTest.php</span>
- ├── <span class="ex">utils</span> <span class="co"># utilities to ease testing</span>
+ ├── <span class="ex">utils</span> # utilities to ease testing
│ └── <span class="ex">ReferenceLinkDB.php</span>
└── <span class="ex">UtilsTest.php</span>
- <span class="ex">COPYING</span> <span class="co"># Shaarli license</span>
- <span class="ex">inc/</span> <span class="co"># static assets and 3rd party libraries</span>
- ├── <span class="ex">awesomplete.*</span> <span class="co"># tags autocompletion library</span>
- ├── <span class="ex">blazy.*</span> <span class="co"># picture wall lazy image loading library</span>
+ <span class="ex">COPYING</span> # Shaarli license
+ <span class="ex">inc/</span> # static assets and 3rd party libraries
+ ├── <span class="ex">awesomplete.*</span> # tags autocompletion library
+ ├── <span class="ex">blazy.*</span> # picture wall lazy image loading library
├── <span class="ex">shaarli.css</span>, reset.css <span class="co"># Shaarli stylesheet.</span>
- ├── <span class="ex">qr.*</span> <span class="co"># qr code generation library</span>
- └──<span class="ex">rain.tpl.class.php</span> <span class="co"># RainTPL templating library</span>
- <span class="ex">tpl/</span> <span class="co"># RainTPL templates for Shaarli. They are used to build the pages.</span>
- <span class="ex">images/</span> <span class="co"># Images and icons used in Shaarli</span>
- <span class="ex">data/</span> <span class="co"># data storage: bookmark database, configuration, logs, banlist…</span>
- ├── <span class="ex">config.php</span> <span class="co"># Shaarli configuration (login, password, timezone, title…)</span>
- ├── <span class="ex">datastore.php</span> <span class="co"># Your link database (compressed).</span>
- ├── <span class="ex">ipban.php</span> <span class="co"># IP address ban system data</span>
- ├── <span class="ex">lastupdatecheck.txt</span> <span class="co"># Update check timestamp file</span>
- └──<span class="ex">log.txt</span> <span class="co"># login/IPban log.</span>
- <span class="ex">cache/</span> <span class="co"># thumbnails cache</span>
+ ├── <span class="ex">qr.*</span> # qr code generation library
+ └──<span class="ex">rain.tpl.class.php</span> # RainTPL templating library
+ <span class="ex">tpl/</span> # RainTPL templates for Shaarli. They are used to build the pages.
+ <span class="ex">images/</span> # Images and icons used in Shaarli
+ <span class="ex">data/</span> # data storage: bookmark database, configuration, logs, banlist…
+ ├── <span class="ex">config.php</span> # Shaarli configuration (login, password, timezone, title…)
+ ├── <span class="ex">datastore.php</span> # Your link database (compressed)<span class="ex">.</span>
+ ├── <span class="ex">ipban.php</span> # IP address ban system data
+ ├── <span class="ex">lastupdatecheck.txt</span> # Update check timestamp file
+ └──<span class="ex">log.txt</span> # login/IPban log.
+ <span class="ex">cache/</span> # thumbnails cache
<span class="co"># This directory is automatically created. You can erase it anytime you want.</span>
- <span class="ex">tmp/</span> <span class="co"># Temporary directory for compiled RainTPL templates.</span>
+ <span class="ex">tmp/</span> # Temporary directory for compiled RainTPL templates.
<span class="co"># This directory is automatically created. You can erase it anytime you want.</span></code></pre></div>
</body>
</html>
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<span class="ex">CONTAINER</span> ID IMAGE COMMAND CREATED STATUS PORTS NAMES
<span class="ex">d40b7af693d6</span> shaarli/shaarli /usr/bin/supervisor 15 seconds ago Up 4 seconds 0.0.0.0:8000-<span class="op">></span>80/tcp backstabbing_galileo</code></pre></div>
<h3 id="stop-and-destroy-a-container">Stop and destroy a container</h3>
-<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash">$ <span class="ex">docker</span> stop backstabbing_galileo <span class="co"># those docker guys are really rude to physicists!</span>
+<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash">$ <span class="ex">docker</span> stop backstabbing_galileo # those docker guys are really rude to physicists!
<span class="ex">backstabbing_galileo</span>
<span class="co"># check the container is stopped</span>
<span class="ex">d40b7af693d6</span> shaarli/shaarli /usr/bin/supervisor 5 minutes ago Exited (0) <span class="ex">48</span> seconds ago backstabbing_galileo
<span class="co"># destroy the container</span>
-$ <span class="ex">docker</span> rm backstabbing_galileo <span class="co"># let's put an end to these barbarian practices</span>
-<span class="ex">backstabbing_galileo</span>
+$ <span class="ex">docker</span> rm backstabbing_galileo # let<span class="st">'s put an end to these barbarian practices</span>
+<span class="st">backstabbing_galileo</span>
-$ <span class="ex">docker</span> ps -a
-<span class="ex">CONTAINER</span> ID IMAGE COMMAND CREATED STATUS PORTS NAMES</code></pre></div>
+<span class="st">$ docker ps -a</span>
+<span class="st">CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES</span></code></pre></div>
<h2 id="resources">Resources</h2>
<h3 id="docker-1">Docker</h3>
<ul>
+<li><a href="https://www.katacoda.com/courses/docker/">Interactive Docker training portal</a> on <a href="https://www.katacoda.com/">Katakoda</a><a href=".html"></a></li>
<li><a href="http://blog.thoward37.me/articles/where-are-docker-images-stored/">Where are Docker images stored?</a><a href=".html"></a></li>
<li><a href="https://docs.docker.com/reference/builder/">Dockerfile reference</a><a href=".html"></a></li>
<li><a href="https://docs.docker.com/articles/dockerfile_best-practices/">Dockerfile best practices</a><a href=".html"></a></li>
## Resources
### Docker
+- [Interactive Docker training portal](https://www.katacoda.com/courses/docker/) on [Katakoda](https://www.katacoda.com/)[](.html)
- [Where are Docker images stored?](http://blog.thoward37.me/articles/where-are-docker-images-stored/)[](.html)
- [Dockerfile reference](https://docs.docker.com/reference/builder/)[](.html)
- [Dockerfile best practices](https://docs.docker.com/articles/dockerfile_best-practices/)[](.html)
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<span class="kw">function</span> copyUserStyleFrom<span class="ot">(</span><span class="kw">$url</span><span class="ot">,</span> <span class="kw">$name</span><span class="ot">,</span> <span class="kw">$knownStyles</span><span class="ot">)</span> {
<span class="kw">$userStyle</span> = <span class="kw">$url</span>.<span class="st">"inc/user.css"</span><span class="ot">;</span>
<span class="kw">if</span><span class="ot">(</span><span class="fu">in_array</span><span class="ot">(</span><span class="kw">$url</span><span class="ot">,</span> <span class="kw">$knownStyles</span><span class="ot">))</span> {
- <span class="co">// TODO add log message</span>
+ <span class="co">// </span><span class="al">TODO</span><span class="co"> add log message</span>
} <span class="kw">else</span> {
<span class="kw">$statusCode</span> = get_http_response_code<span class="ot">(</span><span class="kw">$userStyle</span><span class="ot">);</span>
<span class="kw">if</span><span class="ot">(</span><span class="fu">intval</span><span class="ot">(</span><span class="kw">$statusCode</span><span class="ot">)</span><<span class="dv">300</span><span class="ot">)</span> {
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<h3 id="download-as-an-archive">Download as an archive</h3>
<p>Get the latest released version from the <a href="https://github.com/shaarli/Shaarli/releases">releases</a> page.<a href=".html"></a></p>
<p><strong>Download our <em>shaarli-full</em> archive</strong> to include dependencies.</p>
-<p>The current latest released version is <code>v0.8.0</code></p>
+<p>The current latest released version is <code>v0.8.4</code></p>
<p>Or in command lines:</p>
-<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash">$ <span class="fu">wget</span> https://github.com/shaarli/Shaarli/releases/download/v0.8.0/shaarli-v0.8.0-full.zip
-$ <span class="fu">unzip</span> shaarli-v0.8.0-full.zip
+<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash">$ <span class="fu">wget</span> https://github.com/shaarli/Shaarli/releases/download/v0.8.4/shaarli-v0.8.4-full.zip
+$ <span class="fu">unzip</span> shaarli-v0.8.4-full.zip
$ <span class="fu">mv</span> Shaarli /path/to/shaarli/</code></pre></div>
<table style="width:46%;">
<colgroup>
</table>
<h3 id="using-git">Using git</h3>
<pre><code>mkdir -p /path/to/shaarli && cd /path/to/shaarli/
-git clone -b v0.8.0 https://github.com/shaarli/Shaarli.git .
-composer update --no-dev</code></pre>
+git clone -b v0.8 https://github.com/shaarli/Shaarli.git .
+composer install --no-dev</code></pre>
<hr />
<h2 id="stable-version">Stable version</h2>
<p>The stable version has been experienced by Shaarli users, and will receive security updates.</p>
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash">$ <span class="fu">git</span> clone https://github.com/shaarli/Shaarli.git -b stable /path/to/shaarli/
<span class="co"># install/update third-party dependencies</span>
$ <span class="bu">cd</span> /path/to/shaarli/
-$ <span class="ex">composer</span> update --no-dev</code></pre></div>
+$ <span class="ex">composer</span> install --no-dev</code></pre></div>
<hr />
<h2 id="development-version-mainline">Development version (mainline)</h2>
<p><em>Use at your own risk!</em></p>
<p>To get the latest changes from the <code>master</code> branch:</p>
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="co"># clone the repository </span>
-$ <span class="fu">git</span> clone https://github.com/shaarli/Shaarli.git master /path/to/shaarli/
+$ <span class="fu">git</span> clone https://github.com/shaarli/Shaarli.git -b master /path/to/shaarli/
<span class="co"># install/update third-party dependencies</span>
$ <span class="bu">cd</span> /path/to/shaarli
-$ <span class="ex">composer</span> update --no-dev</code></pre></div>
+$ <span class="ex">composer</span> install --no-dev</code></pre></div>
<hr />
<h2 id="finish-installation">Finish Installation</h2>
<p>Once Shaarli is downloaded and files have been placed at the correct location, open it this location your favorite browser.</p>
**Download our *shaarli-full* archive** to include dependencies.
-The current latest released version is `v0.8.0`
+The current latest released version is `v0.8.4`
Or in command lines:
```bash
-$ wget https://github.com/shaarli/Shaarli/releases/download/v0.8.0/shaarli-v0.8.0-full.zip
-$ unzip shaarli-v0.8.0-full.zip
+$ wget https://github.com/shaarli/Shaarli/releases/download/v0.8.4/shaarli-v0.8.4-full.zip
+$ unzip shaarli-v0.8.4-full.zip
$ mv Shaarli /path/to/shaarli/
```
```
mkdir -p /path/to/shaarli && cd /path/to/shaarli/
-git clone -b v0.8.0 https://github.com/shaarli/Shaarli.git .
-composer update --no-dev
+git clone -b v0.8 https://github.com/shaarli/Shaarli.git .
+composer install --no-dev
```
--------------------------------------------------------
$ git clone https://github.com/shaarli/Shaarli.git -b stable /path/to/shaarli/
# install/update third-party dependencies
$ cd /path/to/shaarli/
-$ composer update --no-dev
+$ composer install --no-dev
```
--------------------------------------------------------
```bash
# clone the repository
-$ git clone https://github.com/shaarli/Shaarli.git master /path/to/shaarli/
+$ git clone https://github.com/shaarli/Shaarli.git -b master /path/to/shaarli/
# install/update third-party dependencies
$ cd /path/to/shaarli
-$ composer update --no-dev
+$ composer install --no-dev
```
--------------------------------------------------------
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
</ul>
</div>
<h1 id="plugin-system">Plugin System</h1>
-<blockquote>
-<p>Note: Plugin current status - in development (not merged into master).</p>
-</blockquote>
<p><a href="#developer-api"><strong>I am a developer.</strong> Developer API.</a><a href=".html"></a></p>
<p><a href="#guide-for-template-designer"><strong>I am a template designer.</strong> Guide for template designer.</a><a href=".html"></a></p>
<h2 id="developer-api">Developer API</h2>
| plugins/
|---| demo_plugin/
| |---| demo_plugin.php</code></pre>
+<h3 id="plugin-initialization">Plugin initialization</h3>
+<p>At the beginning of Shaarli execution, all enabled plugins are loaded. At this point, the plugin system looks for an <code>init()</code> function to execute and run it if it exists. This function must be named this way, and takes the <code>ConfigManager</code> as parameter.</p>
+<pre><code><plugin_name>_init($conf)</code></pre>
+<p>This function can be used to create initial data, load default settings, etc. But also to set <em>plugin errors</em>. If the initialization function returns an array of strings, they will be understand as errors, and displayed in the header to logged in users.</p>
<h3 id="understanding-hooks">Understanding hooks</h3>
<p>A plugin is a set of functions. Each function will be triggered by the plugin system at certain point in Shaarli execution.</p>
<p>These functions need to be named with this pattern:</p>
-<pre><code>hook_<plugin_name>_<hook_name></code></pre>
+<pre><code>hook_<plugin_name>_<hook_name>($data, $conf)</code></pre>
+<p>Parameters:</p>
+<ul>
+<li>data: see <a href="https://github.com/shaarli/Shaarli/wiki/Plugin-System#plugins-data">$data section</a><a href=".html"></a></li>
+<li>conf: the <code>ConfigManager</code> instance.</li>
+</ul>
<p>For exemple, if my plugin want to add data to the header, this function is needed:</p>
-<pre><code>hook_demo_plugin_render_header()</code></pre>
+<pre><code>hook_demo_plugin_render_header</code></pre>
<p>If this function is declared, and the plugin enabled, it will be called every time Shaarli is rendering the header.</p>
<h3 id="plugins-data">Plugin's data</h3>
<h4 id="parameters">Parameters</h4>
<ul>
<li><code>description</code>: plugin description</li>
<li><code>parameters</code>: user parameter names, separated by a <code>;</code>.</li>
+<li><code>parameter.<PARAMETER_NAME></code>: add a text description the specified parameter.</li>
</ul>
<blockquote>
<p>Note: In PHP, <code>parse_ini_file()</code> seems to want strings to be between by quotes <code>"</code> in the ini file.</p>
</tr>
<tr class="even">
<td><a href="#render_tagcloud">render_tagcloud</a></td>
-<td style="text-align: center;">Allow to add content at the top and bottom of the page.</td>
+<td style="text-align: center;">Allow to add content at the top and bottom of the page, and after all tags.</td>
</tr>
<tr class="odd">
+<td><a href="#render_taglist">render_taglist</a></td>
+<td style="text-align: center;">Allow to add content at the top and bottom of the page, and after all tags.</td>
+</tr>
+<tr class="even">
<td><a href="#render_daily">render_daily</a></td>
<td style="text-align: center;">Allow to add content at the top and bottom of the page, the bottom of each link and to alter data.</td>
</tr>
+<tr class="odd">
+<td><a href="#render_feed">render_feed</a></td>
+<td style="text-align: center;">Allow to do add tags in RSS and ATOM feeds.</td>
+</tr>
<tr class="even">
-<td><a href="#savelink">savelink</a></td>
+<td><a href="#save_link">save_link</a></td>
<td style="text-align: center;">Allow to alter the link being saved in the datastore.</td>
</tr>
+<tr class="odd">
+<td><a href="#delete_link">delete_link</a></td>
+<td style="text-align: center;">Allow to do an action before a link is deleted from the datastore.</td>
+</tr>
</tbody>
</table>
<h4 id="render_header">render_header</h4>
<li><p><code>plugin_start_zone</code>: before displaying the template content.</p></li>
<li><p><code>plugin_end_zone</code>: after displaying the template content.</p></li>
</ul>
+<p>For each tag, the following placeholder can be used:</p>
+<ul>
+<li><code>tag_plugin</code>: after each tag</li>
+</ul>
<p><img src="http://i.imgur.com/vHmyT3a.png" alt="plugin_start_end_zone_example" /><a href=".html"></a></p>
+<h4 id="render_taglist">render_taglist</h4>
+<p>Triggered when taglist is displayed.</p>
+<p>Allow to add content at the top and bottom of the page.</p>
+<h5 id="data-8">Data</h5>
+<p><code>$data</code> is an array containing:</p>
+<ul>
+<li><code>_LOGGEDIN_</code>: true if user is logged in, false otherwise.</li>
+<li>All templates data.</li>
+</ul>
+<h5 id="template-placeholders-8">Template placeholders</h5>
+<p>Items can be displayed in templates by adding an entry in <code>$data['<placeholder>']</code> array.<a href=".html"></a></p>
+<p>List of placeholders:</p>
+<ul>
+<li><p><code>plugin_start_zone</code>: before displaying the template content.</p></li>
+<li><p><code>plugin_end_zone</code>: after displaying the template content.</p></li>
+</ul>
+<p>For each tag, the following placeholder can be used:</p>
+<ul>
+<li><code>tag_plugin</code>: after each tag</li>
+</ul>
<h4 id="render_daily">render_daily</h4>
<p>Triggered when tagcloud is displayed.</p>
<p>Allow to add content at the top and bottom of the page, the bottom of each link and to alter data.</p>
-<h5 id="data-8">Data</h5>
+<h5 id="data-9">Data</h5>
<p><code>$data</code> is an array containing:</p>
<ul>
<li><code>_LOGGEDIN_</code>: true if user is logged in, false otherwise.</li>
<li>All templates data, including links.</li>
</ul>
-<h5 id="template-placeholders-8">Template placeholders</h5>
+<h5 id="template-placeholders-9">Template placeholders</h5>
<p>Items can be displayed in templates by adding an entry in <code>$data['<placeholder>']</code> array.<a href=".html"></a></p>
<p>List of placeholders:</p>
<ul>
<li><p><code>plugin_start_zone</code>: before displaying the template content.</p></li>
<li><p><code>plugin_end_zone</code>: after displaying the template content.</p></li>
</ul>
-<h4 id="savelink">savelink</h4>
+<h4 id="render_feed">render_feed</h4>
+<p>Triggered when the ATOM or RSS feed is displayed.</p>
+<p>Allow to add tags in the feed, either in the header or for each items. Items (links) can also be altered before being rendered.</p>
+<h5 id="data-10">Data</h5>
+<p><code>$data</code> is an array containing:</p>
+<ul>
+<li><code>_LOGGEDIN_</code>: true if user is logged in, false otherwise.</li>
+<li><code>_PAGE_</code>: containing either <code>rss</code> or <code>atom</code>.</li>
+<li>All templates data, including links.</li>
+</ul>
+<h5 id="template-placeholders-10">Template placeholders</h5>
+<p>Tags can be added in feeds by adding an entry in <code>$data['<placeholder>']</code> array.<a href=".html"></a></p>
+<p>List of placeholders:</p>
+<ul>
+<li><code>feed_plugins_header</code>: used as a header tag in the feed.</li>
+</ul>
+<p>For each links:</p>
+<ul>
+<li><code>feed_plugins</code>: additional tag for every link entry.</li>
+</ul>
+<h4 id="save_link">save_link</h4>
<p>Triggered when a link is save (new link or edit).</p>
<p>Allow to alter the link being saved in the datastore.</p>
-<h5 id="data-9">Data</h5>
+<h5 id="data-11">Data</h5>
<p><code>$data</code> is an array containing the link being saved:</p>
<ul>
+<li>id</li>
<li>title</li>
<li>url</li>
+<li>shorturl</li>
<li>description</li>
-<li>linkdate</li>
<li>private</li>
<li>tags</li>
+<li>created</li>
+<li>updated</li>
+</ul>
+<h4 id="delete_link">delete_link</h4>
+<p>Triggered when a link is deleted.</p>
+<p>Allow to execute any action before the link is actually removed from the datastore</p>
+<h5 id="data-12">Data</h5>
+<p><code>$data</code> is an array containing the link being saved:</p>
+<ul>
+<li>id</li>
+<li>title</li>
+<li>url</li>
+<li>shorturl</li>
+<li>description</li>
+<li>private</li>
+<li>tags</li>
+<li>created</li>
+<li>updated</li>
</ul>
<h2 id="guide-for-template-designer">Guide for template designer</h2>
<h3 id="plugin-administration">Plugin administration</h3>
{$value}
{/loop}
<span class="kw"></div></span></code></pre></div>
+<p><strong>feed.atom.xml</strong> and <strong>feed.rss.xml</strong>:</p>
+<p>In headers tags section:</p>
+<div class="sourceCode"><pre class="sourceCode xml"><code class="sourceCode xml">{loop="$feed_plugins_header"}
+ {$value}
+{/loop}</code></pre></div>
+<p>After each entry:</p>
+<div class="sourceCode"><pre class="sourceCode xml"><code class="sourceCode xml">{loop="$value.feed_plugins"}
+ {$value}
+{/loop}</code></pre></div>
</body>
</html>
#Plugin System
-> Note: Plugin current status - in development (not merged into master).
-
[**I am a developer.** Developer API.](#developer-api)[](.html)
[**I am a template designer.** Guide for template designer.](#guide-for-template-designer)[](.html)
| |---| demo_plugin.php
```
+### Plugin initialization
+
+At the beginning of Shaarli execution, all enabled plugins are loaded. At this point, the plugin system looks for an `init()` function to execute and run it if it exists. This function must be named this way, and takes the `ConfigManager` as parameter.
+
+ <plugin_name>_init($conf)
+
+This function can be used to create initial data, load default settings, etc. But also to set *plugin errors*. If the initialization function returns an array of strings, they will be understand as errors, and displayed in the header to logged in users.
+
### Understanding hooks
A plugin is a set of functions. Each function will be triggered by the plugin system at certain point in Shaarli execution.
These functions need to be named with this pattern:
```
-hook_<plugin_name>_<hook_name>
+hook_<plugin_name>_<hook_name>($data, $conf)
```
+Parameters:
+
+ - data: see [$data section](https://github.com/shaarli/Shaarli/wiki/Plugin-System#plugins-data)[](.html)
+ - conf: the `ConfigManager` instance.
+
For exemple, if my plugin want to add data to the header, this function is needed:
- hook_demo_plugin_render_header()
+ hook_demo_plugin_render_header
If this function is declared, and the plugin enabled, it will be called every time Shaarli is rendering the header.
* `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.
| [render_editlink](#render_editlink) | Allow to add fields in the form, or display elements. |[](.html)
| [render_tools](#render_tools) | Allow to add content at the end of the page. |[](.html)
| [render_picwall](#render_picwall) | Allow to add content at the top and bottom of the page. |[](.html)
-| [render_tagcloud](#render_tagcloud) | Allow to add content at the top and bottom of the page. |[](.html)
+| [render_tagcloud](#render_tagcloud) | Allow to add content at the top and bottom of the page, and after all tags. |[](.html)
+| [render_taglist](#render_taglist) | Allow to add content at the top and bottom of the page, and after all tags. |[](.html)
| [render_daily](#render_daily) | Allow to add content at the top and bottom of the page, the bottom of each link and to alter data. |[](.html)
-| [savelink](#savelink) | Allow to alter the link being saved in the datastore. |[](.html)
+| [render_feed](#render_feed) | Allow to do add tags in RSS and ATOM feeds. |[](.html)
+| [save_link](#save_link) | Allow to alter the link being saved in the datastore. |[](.html)
+| [delete_link](#delete_link) | Allow to do an action before a link is deleted from the datastore. |[](.html)
+
#### render_header
* `plugin_end_zone`: after displaying the template content.
+For each tag, the following placeholder can be used:
+
+ * `tag_plugin`: after each tag
+
[](.html)
+
+#### render_taglist
+
+Triggered when taglist is displayed.
+
+Allow to add content at the top and bottom of the page.
+
+##### Data
+
+`$data` is an array containing:
+
+ * `_LOGGEDIN_`: true if user is logged in, false otherwise.
+ * All templates data.
+
+##### Template placeholders
+
+Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.[](.html)
+
+List of placeholders:
+
+ * `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
+
#### render_daily
Triggered when tagcloud is displayed.
* `plugin_end_zone`: after displaying the template content.
-#### savelink
+#### render_feed
+
+Triggered when the ATOM or RSS feed is displayed.
+
+Allow to add tags in the feed, either in the header or for each items. Items (links) can also be altered before being rendered.
+
+##### Data
+
+`$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.
+
+##### Template placeholders
+
+Tags can be added in feeds by adding an entry in `$data['<placeholder>']` array.[](.html)
+
+List of placeholders:
+
+ * `feed_plugins_header`: used as a header tag in the feed.
+
+For each links:
+
+ * `feed_plugins`: additional tag for every link entry.
+
+#### save_link
Triggered when a link is save (new link or edit).
`$data` is an array containing the link being saved:
+ * id
+ * title
+ * url
+ * shorturl
+ * description
+ * private
+ * tags
+ * created
+ * updated
+
+
+#### delete_link
+
+Triggered when a link is deleted.
+
+Allow to execute any action before the link is actually removed from the datastore
+
+##### Data
+
+`$data` is an array containing the link being saved:
+
+ * id
* title
* url
+ * shorturl
* description
- * linkdate
* private
* tags
+ * created
+ * updated
## Guide for template designer
{/loop}
</div>
```
+
+**feed.atom.xml** and **feed.rss.xml**:
+
+In headers tags section:
+```xml
+{loop="$feed_plugins_header"}
+ {$value}
+{/loop}
+```
+
+After each entry:
+```xml
+{loop="$value.feed_plugins"}
+ {$value}
+{/loop}
+```
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<li><a href="https://github.com/shaarli/Shaarli/blob/master/plugins/markdown/README.md"><code>markdown</code></a>: Render shaare description with Markdown syntax.<a href=".html"></a></li>
<li><a href="https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md"><code>playvideos</code></a>: Add a button in the toolbar allowing to watch all videos.<a href=".html"></a></li>
<li><code>qrcode</code>: For each link, add a QRCode icon.</li>
-<li><code>readityourself</code>: For each link, add a ReadItYourself icon to save the shaared URL</li>
<li><a href="https://github.com/shaarli/Shaarli/blob/master/plugins/wallabag/README.md"><code>wallabag</code></a>: For each link, add a Wallabag icon to save it in your instance.<a href=".html"></a></li>
</ul>
<h4 id="third-party-plugins">Third party plugins</h4>
* [`markdown`](https://github.com/shaarli/Shaarli/blob/master/plugins/markdown/README.md): Render shaare description with Markdown syntax.[](.html)
* [`playvideos`](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md): Add a button in the toolbar allowing to watch all videos.[](.html)
* `qrcode`: For each link, add a QRCode icon.
- * `readityourself`: For each link, add a ReadItYourself icon to save the shaared URL
* [`wallabag`](https://github.com/shaarli/Shaarli/blob/master/plugins/wallabag/README.md): For each link, add a Wallabag icon to save it in your instance.[](.html)
--- /dev/null
+<!DOCTYPE html>
+<html>
+<head>
+ <meta charset="utf-8">
+ <meta name="generator" content="pandoc">
+ <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
+ <title>Shaarli – REST API</title>
+ <style type="text/css">code{white-space: pre;}</style>
+ <style type="text/css">
+div.sourceCode { overflow-x: auto; }
+table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode {
+ margin: 0; padding: 0; vertical-align: baseline; border: none; }
+table.sourceCode { width: 100%; line-height: 100%; }
+td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; color: #aaaaaa; border-right: 1px solid #aaaaaa; }
+td.sourceCode { padding-left: 5px; }
+code > span.kw { color: #007020; font-weight: bold; } /* Keyword */
+code > span.dt { color: #902000; } /* DataType */
+code > span.dv { color: #40a070; } /* DecVal */
+code > span.bn { color: #40a070; } /* BaseN */
+code > span.fl { color: #40a070; } /* Float */
+code > span.ch { color: #4070a0; } /* Char */
+code > span.st { color: #4070a0; } /* String */
+code > span.co { color: #60a0b0; font-style: italic; } /* Comment */
+code > span.ot { color: #007020; } /* Other */
+code > span.al { color: #ff0000; font-weight: bold; } /* Alert */
+code > span.fu { color: #06287e; } /* Function */
+code > span.er { color: #ff0000; font-weight: bold; } /* Error */
+code > span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
+code > span.cn { color: #880000; } /* Constant */
+code > span.sc { color: #4070a0; } /* SpecialChar */
+code > span.vs { color: #4070a0; } /* VerbatimString */
+code > span.ss { color: #bb6688; } /* SpecialString */
+code > span.im { } /* Import */
+code > span.va { color: #19177c; } /* Variable */
+code > span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
+code > span.op { color: #666666; } /* Operator */
+code > span.bu { } /* BuiltIn */
+code > span.ex { } /* Extension */
+code > span.pp { color: #bc7a00; } /* Preprocessor */
+code > span.at { color: #7d9029; } /* Attribute */
+code > span.do { color: #ba2121; font-style: italic; } /* Documentation */
+code > span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
+code > span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
+code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
+ </style>
+ <link rel="stylesheet" href="github-markdown.css">
+ <!--[if lt IE 9]>
+ <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
+ <![endif]-->
+</head>
+<body>
+<div id="local-sidebar">
+<ul>
+<li><a href="Home.html">Home</a></li>
+<li>Setup
+<ul>
+<li><a href="Download-and-Installation.html">Download and Installation</a></li>
+<li><a href="Upgrade-and-migration.html">Upgrade and migration</a></li>
+<li><a href="Server-requirements.html">Server requirements</a></li>
+<li><a href="Server-configuration.html">Server configuration</a></li>
+<li><a href="Server-security.html">Server security</a></li>
+<li><a href="Shaarli-configuration.html">Shaarli configuration</a></li>
+<li><a href="Plugins.html">Plugins</a></li>
+</ul></li>
+<li><a href="Docker.html">Docker</a></li>
+<li><a href="Usage.html">Usage</a>
+<ul>
+<li><a href="Sharing-button.html">Sharing button</a> (bookmarklet)</li>
+<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
+<li><a href="Firefox-share.html">Firefox share</a></li>
+<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
+</ul></li>
+<li>How To
+<ul>
+<li><a href="Backup,-restore,-import-and-export.html">Backup, restore, import and export</a></li>
+<li><a href="Copy-an-existing-installation-over-SSH-and-serve-it-locally.html">Copy an existing installation over SSH and serve it locally</a></li>
+<li><a href="Create-and-serve-multiple-Shaarlis-(farm).html">Create and serve multiple Shaarlis (farm)</a></li>
+<li><a href="Download-CSS-styles-from-an-OPML-list.html">Download CSS styles from an OPML list</a></li>
+<li><a href="Datastore-hacks.html">Datastore hacks</a></li>
+</ul></li>
+<li><a href="Troubleshooting.html">Troubleshooting</a></li>
+<li><a href="Development.html">Development</a>
+<ul>
+<li><a href="GnuPG-signature.html">GnuPG signature</a></li>
+<li><a href="Coding-guidelines.html">Coding guidelines</a></li>
+<li><a href="Directory-structure.html">Directory structure</a></li>
+<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
+<li><a href="Plugin-System.html">Plugin System</a></li>
+<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
+<li><a href="Security.html">Security</a></li>
+<li><a href="Static-analysis.html">Static analysis</a></li>
+<li><a href="Theming.html">Theming</a></li>
+<li><a href="Unit-tests.html">Unit tests</a></li>
+</ul></li>
+<li>About
+<ul>
+<li><a href="FAQ.html">FAQ</a></li>
+<li><a href="Community-&-Related-software.html">Community & Related software</a></li>
+</ul></li>
+</ul>
+</div>
+<h1 id="rest-api">REST API</h1>
+<h2 id="usage">Usage</h2>
+<p>See the <a href="http://shaarli.github.io/api-documentation/">REST API documentation</a>.<a href=".html"></a></p>
+<h2 id="authentication">Authentication</h2>
+<p>All requests to Shaarli's API must include a JWT token to verify their authenticity.</p>
+<p>This token has to be included as an HTTP header called <code>Authentication: Bearer <jwt token></code>.</p>
+<p>JWT resources :</p>
+<ul>
+<li><a href="https://jwt.io">jwt.io</a> (including a list of client per language).<a href=".html"></a></li>
+<li>RFC : <a href="https://tools.ietf.org/html/rfc7519" class="uri">https://tools.ietf.org/html/rfc7519</a></li>
+<li><a href="https://float-middle.com/json-web-tokens-jwt-vs-sessions/" class="uri">https://float-middle.com/json-web-tokens-jwt-vs-sessions/</a></li>
+<li>HackerNews thread: <a href="https://news.ycombinator.com/item?id=11929267" class="uri">https://news.ycombinator.com/item?id=11929267</a></li>
+</ul>
+<h3 id="shaarli-jwt-token">Shaarli JWT Token</h3>
+<p>JWT tokens are composed by three parts, separated by a dot <code>.</code> and encoded in base64:</p>
+<pre><code>[header].[payload].[signature][](.html)</code></pre>
+<h4 id="header">Header</h4>
+<p>Shaarli only allow one hash algorithm, so the header will always be the same:</p>
+<div class="sourceCode"><pre class="sourceCode json"><code class="sourceCode json"><span class="fu">{</span>
+ <span class="dt">"typ"</span><span class="fu">:</span> <span class="st">"JWT"</span><span class="fu">,</span>
+ <span class="dt">"alg"</span><span class="fu">:</span> <span class="st">"HS512"</span>
+<span class="fu">}</span></code></pre></div>
+<p>Encoded in base64, it gives:</p>
+<pre><code>ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==</code></pre>
+<h4 id="payload">Payload</h4>
+<p><strong>Validity duration</strong></p>
+<p>To avoid infinite token validity, JWT tokens must include their creation date in UNIX timestamp format (timezone independant - UTC) under the key <code>iat</code> (issued at). This token will be accepted during 9 minutes.</p>
+<div class="sourceCode"><pre class="sourceCode json"><code class="sourceCode json"><span class="fu">{</span>
+ <span class="dt">"iat"</span><span class="fu">:</span> <span class="dv">1468663519</span>
+<span class="fu">}</span></code></pre></div>
+<p>See <a href="https://tools.ietf.org/html/rfc7519#section-4.1.6">RFC reference</a>.<a href=".html"></a></p>
+<h4 id="signature">Signature</h4>
+<p>The signature authenticate the token validity. It contains the base64 of the header and the body, separated by a dot <code>.</code>, hashed in SHA512 with the API secret available in Shaarli administration page.</p>
+<p>Signature example with PHP:</p>
+<div class="sourceCode"><pre class="sourceCode php"><code class="sourceCode php"><span class="kw">$content</span> = <span class="fu">base64_encode</span><span class="ot">(</span><span class="kw">$header</span><span class="ot">)</span> . <span class="st">'.'</span> . <span class="fu">base64_encode</span><span class="ot">(</span><span class="kw">$payload</span><span class="ot">);</span>
+<span class="kw">$signature</span> = <span class="fu">hash_hmac</span><span class="ot">(</span><span class="st">'sha512'</span><span class="ot">,</span> <span class="kw">$content</span><span class="ot">,</span> <span class="kw">$secret</span><span class="ot">);</span></code></pre></div>
+<h3 id="complete-example">Complete example</h3>
+<h4 id="php">PHP</h4>
+<div class="sourceCode"><pre class="sourceCode php"><code class="sourceCode php"><span class="kw">function</span> generateToken<span class="ot">(</span><span class="kw">$secret</span><span class="ot">)</span> {
+ <span class="kw">$header</span> = <span class="fu">base64_encode</span><span class="ot">(</span><span class="st">'{</span>
+<span class="st"> "typ": "JWT",</span>
+<span class="st"> "alg": "HS512"</span>
+<span class="st"> }'</span><span class="ot">);</span>
+ <span class="kw">$payload</span> = <span class="fu">base64_encode</span><span class="ot">(</span><span class="st">'{</span>
+<span class="st"> "iat": '</span>. <span class="fu">time</span><span class="ot">()</span> .<span class="st">'</span>
+<span class="st"> }'</span><span class="ot">);</span>
+ <span class="kw">$signature</span> = <span class="fu">hash_hmac</span><span class="ot">(</span><span class="st">'sha512'</span><span class="ot">,</span> <span class="kw">$header</span> .<span class="st">'.'</span>. <span class="kw">$payload</span> <span class="ot">,</span> <span class="kw">$secret</span><span class="ot">);</span>
+ <span class="kw">return</span> <span class="kw">$header</span> .<span class="st">'.'</span>. <span class="kw">$payload</span> .<span class="st">'.'</span>. <span class="kw">$signature</span><span class="ot">;</span>
+}
+
+<span class="kw">$secret</span> = <span class="st">'mysecret'</span><span class="ot">;</span>
+<span class="kw">$token</span> = generateToken<span class="ot">(</span><span class="kw">$secret</span><span class="ot">);</span>
+<span class="fu">echo</span> <span class="kw">$token</span><span class="ot">;</span></code></pre></div>
+<blockquote>
+<p><code>ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==.ewogICAgICAgICJpYXQiOiAxNDY4NjY3MDQ3CiAgICB9.1d2c54fa947daf594fdbf7591796195652c8bc63bffad7f6a6db2a41c313f495a542cbfb595acade79e83f3810d709b4251d7b940bbc10b531a6e6134af63a68</code></p>
+</blockquote>
+<div class="sourceCode"><pre class="sourceCode php"><code class="sourceCode php"><span class="kw">$options</span> = <span class="ot">[[](</span>.html<span class="ot">)</span>
+ <span class="st">'http'</span> => <span class="ot">[[](</span>.html<span class="ot">)</span>
+ <span class="st">'method'</span> => <span class="st">'GET'</span><span class="ot">,</span>
+ <span class="st">'jwt'</span> => <span class="kw">$token</span><span class="ot">,</span>
+ <span class="ot">],</span>
+<span class="ot">];</span>
+<span class="kw">$context</span> = <span class="fu">stream_context_create</span><span class="ot">(</span><span class="kw">$options</span><span class="ot">);</span>
+<span class="fu">file_get_contents</span><span class="ot">(</span><span class="kw">$apiEndpoint</span><span class="ot">,</span> <span class="kw">false</span><span class="ot">,</span> <span class="kw">$context</span><span class="ot">);</span></code></pre></div>
+</body>
+</html>
--- /dev/null
+#REST API
+## Usage
+
+See the [REST API documentation](http://shaarli.github.io/api-documentation/).[](.html)
+
+## Authentication
+
+All requests to Shaarli's API must include a JWT token to verify their authenticity.
+
+This token has to be included as an HTTP header called `Authentication: Bearer <jwt token>`.
+
+JWT resources :
+
+ * [jwt.io](https://jwt.io) (including a list of client per language).[](.html)
+ * 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
+
+JWT tokens are composed by three parts, separated by a dot `.` and encoded in base64:
+
+```
+[header].[payload].[signature][](.html)
+```
+
+#### Header
+
+Shaarli only allow one hash algorithm, so the header will always be the same:
+
+```json
+{
+ "typ": "JWT",
+ "alg": "HS512"
+}
+```
+
+Encoded in base64, it gives:
+
+```
+ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==
+```
+
+#### Payload
+
+**Validity duration**
+
+To avoid infinite token validity, JWT tokens must include their creation date in UNIX timestamp format (timezone independant - UTC) under the key `iat` (issued at). This token will be accepted during 9 minutes.
+
+```json
+{
+ "iat": 1468663519
+}
+```
+
+See [RFC reference](https://tools.ietf.org/html/rfc7519#section-4.1.6).[](.html)
+
+
+#### Signature
+
+The signature authenticate the token validity. It contains the base64 of the header and the body, separated by a dot `.`, hashed in SHA512 with the API secret available in Shaarli administration page.
+
+Signature example with PHP:
+
+```php
+$content = base64_encode($header) . '.' . base64_encode($payload);
+$signature = hash_hmac('sha512', $content, $secret);
+```
+
+
+### Complete example
+
+#### PHP
+
+```php
+function generateToken($secret) {
+ $header = base64_encode('{
+ "typ": "JWT",
+ "alg": "HS512"
+ }');
+ $payload = base64_encode('{
+ "iat": '. time() .'
+ }');
+ $signature = hash_hmac('sha512', $header .'.'. $payload , $secret);
+ return $header .'.'. $payload .'.'. $signature;
+}
+
+$secret = 'mysecret';
+$token = generateToken($secret);
+echo $token;
+```
+
+> `ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==.ewogICAgICAgICJpYXQiOiAxNDY4NjY3MDQ3CiAgICB9.1d2c54fa947daf594fdbf7591796195652c8bc63bffad7f6a6db2a41c313f495a542cbfb595acade79e83f3810d709b4251d7b940bbc10b531a6e6134af63a68`
+
+```php
+$options = [[](.html)
+ 'http' => [[](.html)
+ 'method' => 'GET',
+ 'jwt' => $token,
+ ],
+];
+$context = stream_context_create($options);
+file_get_contents($apiEndpoint, false, $context);
+```
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<span class="ex">gpg</span>: Signature made Thu 30 Jul 2015 11:46:34 CEST using RSA key ID 4100DF6F
<span class="ex">gpg</span>: Good signature from <span class="st">"VirtualTam <virtualtam@flibidi.net>"</span> [ultimate][](.html)</code></pre></div>
<h2 id="publish-the-github-release">Publish the GitHub release</h2>
+<h3 id="update-release-badges">Update release badges</h3>
+<p>Update <code>README.md</code> so version badges display and point to the newly released Shaarli version(s).</p>
<h3 id="create-a-github-release-from-a-git-tag">Create a GitHub release from a Git tag</h3>
<p>From the previously drafted release:</p>
<ul>
```
## Publish the GitHub release
+### Update release badges
+Update `README.md` so version badges display and point to the newly released Shaarli version(s).
+
### Create a GitHub release from a Git tag
From the previously drafted release:
- edit the release notes (if needed)
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<h3 id="htaccess">.htaccess</h3>
<p>Shaarli use <code>.htaccess</code> Apache files to deny access to files that shouldn't be directly accessed (datastore, config, etc.). You need the directive <code>AllowOverride All</code> in your virtual host configuration for them to work.</p>
<p><strong>Warning</strong>: If you use Apache 2.2 or lower, you need <a href="https://httpd.apache.org/docs/current/mod/mod_version.html">mod_version</a> to be installed and enabled.<a href=".html"></a></p>
+<p>Apache module <code>mod_rewrite</code> <strong>must</strong> be enabled to use the REST API. URL rewriting rules for the Slim microframework are stated in the root <code>.htaccess</code> file.</p>
<h2 id="lighthttpd">LightHttpd</h2>
<h2 id="nginx">Nginx</h2>
<h3 id="foreword">Foreword</h3>
error_log /var/log/nginx/error.log;
location /shaarli/ {
+ try_files $uri /shaarli/index.php$is_args$args;
access_log /var/log/nginx/shaarli.access.log;
error_log /var/log/nginx/shaarli.error.log;
}
location ~ (index)\.php$ {
+ try_files $uri =404;
+ fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
fastcgi_index index.php;
include fastcgi.conf;
}</code></pre>
<pre class="nginx"><code># /etc/nginx/php.conf
location ~ (index)\.php$ {
+ # Slim - split URL path into (script_filename, path_info)
+ try_files $uri =404;
+ fastcgi_split_path_info ^(.+\.php)(/.+)$;
+
# filter and proxy PHP requests to PHP-FPM
fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
fastcgi_index index.php;
server_name my.first.domain.org;
location /shaarli/ {
+ # Slim - rewrite URLs
+ try_files $uri /shaarli/index.php$is_args$args;
+
access_log /var/log/nginx/shaarli.access.log;
error_log /var/log/nginx/shaarli.error.log;
}
ssl_certificate_key /home/john/ssl/localhost.key;
location /shaarli/ {
+ # Slim - rewrite URLs
+ try_files $uri /index.php$is_args$args;
+
access_log /var/log/nginx/shaarli.access.log;
error_log /var/log/nginx/shaarli.error.log;
}
Shaarli use `.htaccess` Apache files to deny access to files that shouldn't be directly accessed (datastore, config, etc.). You need the directive `AllowOverride All` in your virtual host configuration for them to work.
**Warning**: If you use Apache 2.2 or lower, you need [mod_version](https://httpd.apache.org/docs/current/mod/mod_version.html) to be installed and enabled.[](.html)
+
+Apache module `mod_rewrite` **must** be enabled to use the REST API. URL rewriting rules for the Slim microframework are stated in the root `.htaccess` file.
## LightHttpd
error_log /var/log/nginx/error.log;
location /shaarli/ {
+ try_files $uri /shaarli/index.php$is_args$args;
access_log /var/log/nginx/shaarli.access.log;
error_log /var/log/nginx/shaarli.error.log;
}
location ~ (index)\.php$ {
+ try_files $uri =404;
+ fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
fastcgi_index index.php;
include fastcgi.conf;
```nginx
# /etc/nginx/php.conf
location ~ (index)\.php$ {
+ # Slim - split URL path into (script_filename, path_info)
+ try_files $uri =404;
+ fastcgi_split_path_info ^(.+\.php)(/.+)$;
+
# filter and proxy PHP requests to PHP-FPM
fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
fastcgi_index index.php;
server_name my.first.domain.org;
location /shaarli/ {
+ # Slim - rewrite URLs
+ try_files $uri /shaarli/index.php$is_args$args;
+
access_log /var/log/nginx/shaarli.access.log;
error_log /var/log/nginx/shaarli.error.log;
}
ssl_certificate_key /home/john/ssl/localhost.key;
location /shaarli/ {
+ # Slim - rewrite URLs
+ try_files $uri /index.php$is_args$args;
+
access_log /var/log/nginx/shaarli.access.log;
error_log /var/log/nginx/shaarli.error.log;
}
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
</thead>
<tbody>
<tr class="odd">
+<td style="text-align: center;">7.1</td>
+<td style="text-align: center;">Supported (v0.9.x)</td>
+<td style="text-align: center;">✅</td>
+</tr>
+<tr class="even">
<td style="text-align: center;">7.0</td>
<td style="text-align: center;">Supported</td>
<td style="text-align: center;">✅</td>
</tr>
-<tr class="even">
+<tr class="odd">
<td style="text-align: center;">5.6</td>
<td style="text-align: center;">Supported</td>
<td style="text-align: center;">✅</td>
</tr>
-<tr class="odd">
+<tr class="even">
<td style="text-align: center;">5.5</td>
<td style="text-align: center;">EOL: 2016-07-10</td>
<td style="text-align: center;">✅</td>
</tr>
-<tr class="even">
+<tr class="odd">
<td style="text-align: center;">5.4</td>
<td style="text-align: center;">EOL: 2015-09-14</td>
<td style="text-align: center;">✅ (up to Shaarli 0.8.x)</td>
</tr>
-<tr class="odd">
+<tr class="even">
<td style="text-align: center;">5.3</td>
<td style="text-align: center;">EOL: 2014-08-14</td>
<td style="text-align: center;">✅ (up to Shaarli 0.8.x)</td>
<td style="text-align: center;">All</td>
<td>Import bookmarks from Netscape files<a href=".html"></a></td>
</tr>
+<tr class="even">
+<td><a href="https://packagist.org/packages/erusev/parsedown"><code>erusev/parsedown</code></a></td>
+<td style="text-align: center;">All</td>
+<td>Parse MarkDown syntax for the MarkDown plugin<a href=".html"></a></td>
+</tr>
+<tr class="odd">
+<td><a href="https://packagist.org/packages/slim/slim"><code>slim/slim</code></a></td>
+<td style="text-align: center;">All</td>
+<td>Handle routes and middleware for the REST API<a href=".html"></a></td>
+</tr>
</tbody>
</table>
<h3 id="extensions">Extensions</h3>
### 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:
Library | Required? | Usage
---|:---:|---
[`shaarli/netscape-bookmark-parser`](https://packagist.org/packages/shaarli/netscape-bookmark-parser) | All | Import bookmarks from Netscape files[](.html)
+[`erusev/parsedown`](https://packagist.org/packages/erusev/parsedown) | All | Parse MarkDown syntax for the MarkDown plugin[](.html)
+[`slim/slim`](https://packagist.org/packages/slim/slim) | All | Handle routes and middleware for the REST API[](.html)
### Extensions
Extension | Required? | Usage
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<h3 id="resources">Resources</h3>
<p><strong>data_dir</strong>: Data directory.<br />
<strong>datastore</strong>: Shaarli's links database file path.<br />
+<strong>history</strong>: Shaarli's operation history file path.<br />
<strong>updates</strong>: File path for the ran updates file.<br />
<strong>log</strong>: Log file path.<br />
<strong>update_check</strong>: Last update check file path.<br />
**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.
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
</ul>
</div>
<h1 id="theming">Theming</h1>
-<h2 id="user-css">User CSS</h2>
+<h2 id="foreword">Foreword</h2>
+<p>There are two ways of customizing how Shaarli looks:</p>
+<ol>
+<li>by using a custom CSS to override Shaarli's CSS</li>
+<li>by using a full theme that provides its own RainTPL templates, CSS and Javascript resources</li>
+</ol>
+<h2 id="custom-css">Custom CSS</h2>
+<p>Shaarli's appearance can be modified by adding CSS rules to:</p>
<ul>
-<li>Shaarli's apparence can be modified by editing CSS rules in <code>inc/user.css</code>. This file allows to override rules defined in the main <code>inc/shaarli.css</code> (only add changed rules), or define a whole new theme.</li>
-<li>Do not edit <code>inc/shaarli.css</code>! Your changes would be overriden when updating Shaarli.</li>
-<li>Some themes are available at <a href="https://github.com/shaarli/shaarli-themes" class="uri">https://github.com/shaarli/shaarli-themes</a>.</li>
+<li>Shaarli < <code>v0.9.0</code>: <code>inc/user.css</code></li>
+<li>Shaarli >= <code>v0.9.0</code>: <code>data/user.css</code></li>
</ul>
-<p>See also:</p>
-<ul>
-<li><a href="Download-CSS-styles-from-an-OPML-list.html">Download CSS styles from an OPML list</a></li>
-</ul>
-<h2 id="raintpl-template">RainTPL template</h2>
+<p>This file allows overriding rules defined in the template CSS files (only add changed rules), or define a whole new theme.</p>
+<p><strong>Note</strong>: Do not edit <code>tpl/default/css/shaarli.css</code>! Your changes would be overridden when updating Shaarli.</p>
+<p>See also <a href="Download-CSS-styles-from-an-OPML-list.html">Download CSS styles from an OPML list</a></p>
+<h2 id="themes">Themes</h2>
<p><em>WARNING - This feature is currently being worked on and will be improved in the next releases. Experimental.</em></p>
+<p>Installation:</p>
<ul>
-<li>Find the template you'd like to install (see the list of <a href="available-templates%7CTheming#community-themes--templates.html">available templates|Theming#community-themes--templates</a>)</li>
-<li>Find it's git clone URL or download the zip archive for the template.</li>
-<li>In your Shaarli <code>tpl/</code> directory, run <code>git clone https://url/of/my-template/</code> or unpack the zip archive.
+<li>find a theme you'd like to install</li>
+<li>copy or clone the theme folder under <code>tpl/<a_sweet_theme></code></li>
+<li>enable the theme:
<ul>
-<li>There should now be a <code>my-template/</code> directory under the <code>tpl/</code> dir, containing directly all the template files.</li>
+<li>Shaarli < <code>v0.9.0</code>: edit <code>data/config.json.php</code> and set the value of <code>raintpl_tpl</code> to the new theme name:<br />
+<code>"raintpl_tpl": "tpl\/my-template\/"</code></li>
+<li>Shaarli >= <code>v0.9.0</code>: select the theme through the <em>Tools</em> page</li>
</ul></li>
-<li><p>Edit <code>data/config.json.php</code> to have Shaarli use this template, in <code>"resource"</code> e.g.</p>
-<div class="sourceCode"><pre class="sourceCode json"><code class="sourceCode json"><span class="er">"raintpl_tpl":</span> <span class="er">"tpl\/my-template\/",</span></code></pre></div></li>
</ul>
-<h2 id="community-themes-templates">Community themes & templates</h2>
+<h2 id="community-css-themes">Community CSS & themes</h2>
+<h3 id="custom-css-1">Custom CSS</h3>
+<ul>
+<li><a href="https://github.com/mrjovanovic/serious-theme-shaarli">mrjovanovic/serious-theme-shaarli</a> - A serious theme for Shaarli<a href=".html"></a></li>
+<li><a href="https://github.com/shaarli/shaarli-themes">shaarli/shaarli-themes</a><a href=".html"></a></li>
+</ul>
+<h3 id="themes-1">Themes</h3>
<ul>
<li><a href="https://github.com/AkibaTech/Shaarli---SuperHero-Theme">AkibaTech/Shaarli Superhero Theme</a> - A template/theme for Shaarli<a href=".html"></a></li>
<li><a href="https://github.com/alexisju/albinomouse-template">alexisju/albinomouse-template</a> - A full template for Shaarli<a href=".html"></a></li>
-<li><a href="https://github.com/ArthurHoaro/shaarli-launch">ArthurHoaro/shaarli-launch</a> - Customizable Shaarli theme
.<a href=".html"></a></li>
+<li><a href="https://github.com/ArthurHoaro/shaarli-launch">ArthurHoaro/shaarli-launch</a> - Customizable Shaarli theme<a href=".html"></a></li>
<li><a href="https://github.com/dhoko/ShaarliTemplate">dhoko/ShaarliTemplate</a> - A template/theme for Shaarli<a href=".html"></a></li>
<li><a href="https://github.com/kalvn/shaarli-blocks">kalvn/shaarli-blocks</a> - A template/theme for Shaarli<a href=".html"></a></li>
-<li><a href="https://github.com/kalvn/Shaarli-Material">kalvn/Shaarli-Material</a> - A theme (template) based on Google's Material Design for Shaarli, the superfast delicious clone.<a href=".html"></a></li>
-<li><a href="https://github.com/ManufacturaInd/shaarli-2004licious-theme">ManufacturaInd/shaarli-2004licious-theme</a> - A template/theme as a humble homage to the early looks of the del.icio.us site.<a href=".html"></a></li>
+<li><a href="https://github.com/kalvn/Shaarli-Material">kalvn/Shaarli-Material</a> - A theme (template) based on Google's Material Design for Shaarli, the superfast delicious clone<a href=".html"></a></li>
+<li><a href="https://github.com/ManufacturaInd/shaarli-2004licious-theme">ManufacturaInd/shaarli-2004licious-theme</a> - A template/theme as a humble homage to the early looks of the del.icio.us site<a href=".html"></a></li>
+</ul>
+<h3 id="shaarli-forks">Shaarli forks</h3>
+<ul>
<li><a href="https://github.com/misterair/limonade">misterair/Limonade</a> - A fork of (legacy) Shaarli with a new template<a href=".html"></a></li>
-<li><a href="https://github.com/mrjovanovic/serious-theme-shaarli">mrjovanovic/serious-theme-shaarli</a> - A serious theme for SHaarli.<a href=".html"></a></li>
<li><a href="https://github.com/vivienhaese/shaarlitheme">vivienhaese/shaarlitheme</a> - A Shaarli fork meant to be run in an openshift instance<a href=".html"></a></li>
</ul>
-<h3 id="example-installation-albinomouse-template">Example installation: AlbinoMouse template</h3>
+<h2 id="example-installation-albinomouse-theme">Example installation: AlbinoMouse theme</h2>
<p>With the following configuration:</p>
<ul>
<li>Apache 2 / PHP 5.6</li>
#Theming
-## User CSS
+## Foreword
+There are two ways of customizing how Shaarli looks:
-- Shaarli's apparence can be modified by editing CSS rules in `inc/user.css`. This file allows to override rules defined in the main `inc/shaarli.css` (only add changed rules), or define a whole new theme.
-- Do not edit `inc/shaarli.css`! Your changes would be overriden when updating Shaarli.
-- Some themes are available at https://github.com/shaarli/shaarli-themes.
+1. by using a custom CSS to override Shaarli's CSS
+2. by using a full theme that provides its own RainTPL templates, CSS and Javascript resources
-See also:
-- [Download CSS styles from an OPML list](Download-CSS-styles-from-an-OPML-list.html)
+## 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`
-## RainTPL template
+This file allows overriding rules defined in the template CSS files (only add changed rules), or define a whole new theme.
+**Note**: Do not edit `tpl/default/css/shaarli.css`! Your changes would be overridden when updating Shaarli.
+
+See also [Download CSS styles from an OPML list](Download-CSS-styles-from-an-OPML-list.html)
+
+## Themes
_WARNING - This feature is currently being worked on and will be improved in the next releases. Experimental._
-- Find the template you'd like to install (see the list of [available templates|Theming#community-themes--templates](available-templates|Theming#community-themes--templates.html))
-- Find it's git clone URL or download the zip archive for the template.
-- In your Shaarli `tpl/` directory, run `git clone https://url/of/my-template/` or unpack the zip archive.
- - There should now be a `my-template/` directory under the `tpl/` dir, containing directly all the template files.
-- Edit `data/config.json.php` to have Shaarli use this template, in `"resource"` e.g.
-```json
-"raintpl_tpl": "tpl\/my-template\/",
-```
+Installation:
+- find a theme you'd like to install
+- copy or clone the theme folder under `tpl/<a_sweet_theme>`
+- enable the theme:
+ - Shaarli < `v0.9.0`: edit `data/config.json.php` and set the value of `raintpl_tpl` to the new theme name:
+ `"raintpl_tpl": "tpl\/my-template\/"`
+ - Shaarli >= `v0.9.0`: select the theme through the _Tools_ page
-## Community themes & templates
+## Community CSS & themes
+### Custom CSS
+- [mrjovanovic/serious-theme-shaarli](https://github.com/mrjovanovic/serious-theme-shaarli) - A serious theme for Shaarli[](.html)
+- [shaarli/shaarli-themes](https://github.com/shaarli/shaarli-themes)[](.html)
+
+### Themes
- [AkibaTech/Shaarli Superhero Theme](https://github.com/AkibaTech/Shaarli---SuperHero-Theme) - A template/theme for Shaarli[](.html)
- [alexisju/albinomouse-template](https://github.com/alexisju/albinomouse-template) - A full template for Shaarli[](.html)
-- [ArthurHoaro/shaarli-launch](https://github.com/ArthurHoaro/shaarli-launch) - Customizable Shaarli theme.[](.html)
+- [ArthurHoaro/shaarli-launch](https://github.com/ArthurHoaro/shaarli-launch) - Customizable Shaarli theme[](.html)
- [dhoko/ShaarliTemplate](https://github.com/dhoko/ShaarliTemplate) - A template/theme for Shaarli[](.html)
- [kalvn/shaarli-blocks](https://github.com/kalvn/shaarli-blocks) - A template/theme for Shaarli[](.html)
-- [kalvn/Shaarli-Material](https://github.com/kalvn/Shaarli-Material) - A theme (template) based on Google's Material Design for Shaarli, the superfast delicious clone.[](.html)
-- [ManufacturaInd/shaarli-2004licious-theme](https://github.com/ManufacturaInd/shaarli-2004licious-theme) - A template/theme as a humble homage to the early looks of the del.icio.us site.[](.html)
+- [kalvn/Shaarli-Material](https://github.com/kalvn/Shaarli-Material) - A theme (template) based on Google's Material Design for Shaarli, the superfast delicious clone[](.html)
+- [ManufacturaInd/shaarli-2004licious-theme](https://github.com/ManufacturaInd/shaarli-2004licious-theme) - A template/theme as a humble homage to the early looks of the del.icio.us site[](.html)
+
+### Shaarli forks
- [misterair/Limonade](https://github.com/misterair/limonade) - A fork of (legacy) Shaarli with a new template[](.html)
-- [mrjovanovic/serious-theme-shaarli](https://github.com/mrjovanovic/serious-theme-shaarli) - A serious theme for SHaarli.[](.html)
- [vivienhaese/shaarlitheme](https://github.com/vivienhaese/shaarlitheme) - A Shaarli fork meant to be run in an openshift instance[](.html)
-### Example installation: AlbinoMouse template
+## 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`
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<li>If you have the error <code>Warning: file_get_contents() [function.file-get-contents]: URL file-access is disabled in the server configuration in /…/index.php on line xxx</code>, 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:<a href=".html"></a></li>
</ul>
<div class="sourceCode"><pre class="sourceCode php"><code class="sourceCode php"><span class="co">//list($status,$headers,$data) = getHTTP($url,4); // Short timeout to keep the application responsive.</span>
-<span class="co">// FIXME: Decode charset according to charset specified in either 1) HTTP response headers or 2) <head> in html </span>
+<span class="co">// </span><span class="al">FIXME</span><span class="co">: Decode charset according to charset specified in either 1) HTTP response headers or 2) <head> in html </span>
<span class="co">//if (strpos($status,'200 OK')) $title=html_extract_title($data);</span></code></pre></div>
<ul>
<li>On hosts which forbid outgoing HTTP requests (such as free.fr), some thumbnails will not work.</li>
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<li>a detailed HTML report with metrics for tested code</li>
<li>to open it in a web browser: <code>firefox coverage/index.html &</code></li>
</ul>
+<h3 id="executing-specific-tests">Executing specific tests</h3>
+<p>Add a <a href="https://phpunit.de/manual/current/en/appendixes.annotations.html#appendixes.annotations.group"><code>@group</code></a> annotation in a test class or method comment:<a href=".html"></a></p>
+<div class="sourceCode"><pre class="sourceCode php"><code class="sourceCode php"><span class="co">/**</span>
+<span class="co"> * Netscape bookmark import</span>
+<span class="co"> * </span><span class="an">@group</span><span class="co"> WIP</span>
+<span class="co"> */</span>
+<span class="kw">class</span> BookmarkImportTest <span class="kw">extends</span> PHPUnit_Framework_TestCase
+{
+ <span class="ot">[</span><span class="st">...</span><span class="ot">][](</span>.html<span class="ot">)</span>
+}</code></pre></div>
+<p>To run all tests annotated with <code>@group WIP</code>:</p>
+<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash">$ <span class="ex">vendor/bin/phpunit</span> --group WIP tests/</code></pre></div>
</body>
</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
+Add a [`@group`](https://phpunit.de/manual/current/en/appendixes.annotations.html#appendixes.annotations.group) annotation in a test class or method comment:[](.html)
+
+```php
+/**
+ * Netscape bookmark import
+ * @group WIP
+ */
+class BookmarkImportTest extends PHPUnit_Framework_TestCase
+{
+ [...][](.html)
+}
+```
+
+To run all tests annotated with `@group WIP`:
+```bash
+$ vendor/bin/phpunit --group WIP tests/
+```
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
</div>
<h1 id="upgrade-and-migration">Upgrade and migration</h1>
<h2 id="preparation">Preparation</h2>
+<h3 id="note-your-current-version">Note your current version</h3>
+<p>If anything goes wrong, it's important for us to know which version you're upgrading from.<br />
+The current version is present in the <code>version.php</code> file.</p>
<h3 id="backup-your-data">Backup your data</h3>
<p>Shaarli stores all user data under the <code>data</code> directory:</p>
<ul>
<li><code>data/config.php</code> - main configuration file</li>
<li><code>data/datastore.php</code> - bookmarked links</li>
<li><code>data/ipbans.php</code> - banned IP addresses</li>
+<li><code>data/updates.txt</code> - contains all automatic update to the configuration and datastore files already run</li>
</ul>
<p>See <a href="Shaarli-configuration.html">Shaarli configuration</a> for more information about Shaarli resources.</p>
<p>It is recommended to backup this repository <em>before</em> starting updating/upgrading Shaarli:</p>
</ul></li>
<li>check or restore the <code>data</code> directory</li>
</ul>
-<h2 id="upgrading-from-release-archives">Upgrading from release archives</h2>
+<h2 id="recommended-upgrading-from-release-archives">Recommended : Upgrading from release archives</h2>
<p>All tagged revisions can be downloaded as tarballs or ZIP archives from the <a href="https://github.com/shaarli/Shaarli/releases">releases</a> page.<a href=".html"></a></p>
-<p>We <em>recommend</em> using the releases from the <code>stable</code> branch, which are available as:</p>
-<ul>
-<li>gzipped tarball - <a href="https://github.com/shaarli/Shaarli/archive/stable.tar.gz" class="uri">https://github.com/shaarli/Shaarli/archive/stable.tar.gz</a></li>
-<li>ZIP archive - <a href="https://github.com/shaarli/Shaarli/archive/stable.zip" class="uri">https://github.com/shaarli/Shaarli/archive/stable.zip</a></li>
-</ul>
-<p>Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the contents of the <code>data</code> directory!</p>
-<p>After upgrading, access your fresh Shaarli installation from a web browser; the configuration will then be automatically updated, and new settings added to <code>data/config.php</code> (see <a href="Shaarli-configuration.html">Shaarli configuration</a> for more details).</p>
+<p>We recommend that you use the latest release tarball with the <code>-full</code> suffix. It contains the dependencies, please read <a href="Download-and-installation.html">Download and installation</a> for <code>git</code> complete instructions.</p>
+<p>Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the content of the <code>data</code> directory!</p>
+<p>After upgrading, access your fresh Shaarli installation from a web browser; the configuration and data store will then be automatically updated, and new settings added to <code>data/config.json.php</code> (see <a href="Shaarli-configuration.html">Shaarli configuration</a> for more details).</p>
<h2 id="upgrading-with-git">Upgrading with Git</h2>
<h3 id="updating-a-community-shaarli">Updating a community Shaarli</h3>
<p>If you have installed Shaarli from the <a href="Download#clone-with-git-recommended">community Git repository</a>, simply <a href="https://www.git-scm.com/docs/git-pull">pull new changes</a> from your local clone:<a href=".html"></a></p>
<span class="ex">tests/Url/UrlTest.php</span> <span class="kw">|</span> <span class="ex">1</span> +
<span class="ex">3</span> files changed, 3 insertions(+), <span class="ex">1</span> deletion(-)</code></pre></div>
<p>Shaarli >= <code>v0.8.x</code>: install/update third-party PHP dependencies using <a href="https://getcomposer.org/">Composer</a>:<a href=".html"></a></p>
-<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash">$ <span class="ex">composer</span> update --no-dev
+<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash">$ <span class="ex">composer</span> install --no-dev
<span class="ex">Loading</span> composer repositories with package information
<span class="ex">Updating</span> dependencies
<span class="ex">master</span> 029f75f [sebsauvage/master] Update README.md[](.html)
<span class="ex">*</span> stable 890afc3 [origin/stable] Merge pull request <span class="co">#509 from ArthurHoaro/v0.6.5[](.html)</span></code></pre></div>
<p>Shaarli >= <code>v0.8.x</code>: install/update third-party PHP dependencies using <a href="https://getcomposer.org/">Composer</a>:<a href=".html"></a></p>
-<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash">$ <span class="ex">composer</span> update --no-dev
+<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash">$ <span class="ex">composer</span> install --no-dev
<span class="ex">Loading</span> composer repositories with package information
<span class="ex">Updating</span> dependencies
<span class="ex">Total</span> 3317 (delta 2050), <span class="ex">reused</span> 3301 (delta 2034)<span class="ex">to</span></code></pre></div>
<h4 id="step-3-configuration">Step 3: configuration</h4>
<p>After migrating, access your fresh Shaarli installation from a web browser; the configuration will then be automatically updated, and new settings added to <code>data/config.php</code> (see <a href="Shaarli-configuration.html">Shaarli configuration</a> for more details).</p>
+<h2 id="troubleshooting">Troubleshooting</h2>
+<p>If the solutions provided here doesn't work, please open an issue specifying which version you're upgrading from and to.</p>
+<h3 id="you-must-specify-an-integer-as-a-key">You must specify an integer as a key</h3>
+<p>In <code>v0.8.1</code> we changed how link keys are handled (from timestamps to incremental integers).<br />
+Take a look at <code>data/updates.txt</code> content.</p>
+<h4 id="updates.txt-contains-updatemethoddatastoreids"><code>updates.txt</code> contains <code>updateMethodDatastoreIds</code></h4>
+<p>Try to delete it and refresh your page while being logged in.</p>
+<h4 id="updates.txt-doesnt-exists-or-doesnt-contain-updatemethoddatastoreids"><code>updates.txt</code> doesn't exists or doesn't contain <code>updateMethodDatastoreIds</code></h4>
+<ol>
+<li>Create <code>data/updates.txt</code> if it doesn't exist.</li>
+<li>Paste this string in the update file <code>;updateMethodRenameDashTags;</code></li>
+<li>Login to Shaarli.</li>
+<li>Delete the update file.</li>
+<li>Refresh.</li>
+</ol>
</body>
</html>
#Upgrade and migration
## Preparation
+### Note your current version
+
+If anything goes wrong, it's important for us to know which version you're upgrading from.
+The current version is present in the `version.php` file.
+
### 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
+- `data/updates.txt` - contains all automatic update to the configuration and datastore files already run
See [Shaarli configuration](Shaarli-configuration.html) for more information about Shaarli resources.
- update - see the following sections
- check or restore the `data` directory
-## Upgrading from release archives
+## Recommended : Upgrading from release archives
All tagged revisions can be downloaded as tarballs or ZIP archives from the [releases](https://github.com/shaarli/Shaarli/releases) page.[](.html)
-We _recommend_ using the releases from the `stable` branch, which are available as:
-- gzipped tarball - https://github.com/shaarli/Shaarli/archive/stable.tar.gz
-- ZIP archive - https://github.com/shaarli/Shaarli/archive/stable.zip
+We recommend that you use the latest release tarball with the `-full` suffix. It contains the dependencies, please read [Download and installation](Download-and-installation.html) for `git` complete instructions.
-Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the contents of the `data` directory!
+Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the content of the `data` directory!
-After upgrading, access your fresh Shaarli installation from a web browser; the configuration will then be automatically updated, and new settings added to `data/config.php` (see [Shaarli configuration](Shaarli-configuration.html) for more details).
+After upgrading, access your fresh Shaarli installation from a web browser; the configuration and data store will then be automatically updated, and new settings added to `data/config.json.php` (see [Shaarli configuration](Shaarli-configuration.html) for more details).
## Upgrading with Git
### Updating a community Shaarli
Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/):[](.html)
```bash
-$ composer update --no-dev
+$ composer install --no-dev
Loading composer repositories with package information
Updating dependencies
Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/):[](.html)
```bash
-$ composer update --no-dev
+$ composer install --no-dev
Loading composer repositories with package information
Updating dependencies
#### Step 3: configuration
After migrating, access your fresh Shaarli installation from a web browser; the configuration will then be automatically updated, and new settings added to `data/config.php` (see [Shaarli configuration](Shaarli-configuration.html) for more details).
+
+## Troubleshooting
+
+If the solutions provided here doesn't work, please open an issue specifying which version you're upgrading from and to.
+
+### You must specify an integer as a key
+
+In `v0.8.1` we changed how link keys are handled (from timestamps to incremental integers).
+Take a look at `data/updates.txt` content.
+
+#### `updates.txt` contains `updateMethodDatastoreIds`
+
+Try to delete it and refresh your page while being logged in.
+
+#### `updates.txt` doesn't exists 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.
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
--- /dev/null
+<!DOCTYPE html>
+<html>
+<head>
+ <meta charset="utf-8">
+ <meta name="generator" content="pandoc">
+ <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
+ <title>Shaarli – Versioning and Branches</title>
+ <style type="text/css">code{white-space: pre;}</style>
+ <style type="text/css">
+div.sourceCode { overflow-x: auto; }
+table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode {
+ margin: 0; padding: 0; vertical-align: baseline; border: none; }
+table.sourceCode { width: 100%; line-height: 100%; }
+td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; color: #aaaaaa; border-right: 1px solid #aaaaaa; }
+td.sourceCode { padding-left: 5px; }
+code > span.kw { color: #007020; font-weight: bold; } /* Keyword */
+code > span.dt { color: #902000; } /* DataType */
+code > span.dv { color: #40a070; } /* DecVal */
+code > span.bn { color: #40a070; } /* BaseN */
+code > span.fl { color: #40a070; } /* Float */
+code > span.ch { color: #4070a0; } /* Char */
+code > span.st { color: #4070a0; } /* String */
+code > span.co { color: #60a0b0; font-style: italic; } /* Comment */
+code > span.ot { color: #007020; } /* Other */
+code > span.al { color: #ff0000; font-weight: bold; } /* Alert */
+code > span.fu { color: #06287e; } /* Function */
+code > span.er { color: #ff0000; font-weight: bold; } /* Error */
+code > span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
+code > span.cn { color: #880000; } /* Constant */
+code > span.sc { color: #4070a0; } /* SpecialChar */
+code > span.vs { color: #4070a0; } /* VerbatimString */
+code > span.ss { color: #bb6688; } /* SpecialString */
+code > span.im { } /* Import */
+code > span.va { color: #19177c; } /* Variable */
+code > span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
+code > span.op { color: #666666; } /* Operator */
+code > span.bu { } /* BuiltIn */
+code > span.ex { } /* Extension */
+code > span.pp { color: #bc7a00; } /* Preprocessor */
+code > span.at { color: #7d9029; } /* Attribute */
+code > span.do { color: #ba2121; font-style: italic; } /* Documentation */
+code > span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
+code > span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
+code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
+ </style>
+ <link rel="stylesheet" href="github-markdown.css">
+ <!--[if lt IE 9]>
+ <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
+ <![endif]-->
+</head>
+<body>
+<div id="local-sidebar">
+<ul>
+<li><a href="Home.html">Home</a></li>
+<li>Setup
+<ul>
+<li><a href="Download-and-Installation.html">Download and Installation</a></li>
+<li><a href="Upgrade-and-migration.html">Upgrade and migration</a></li>
+<li><a href="Server-requirements.html">Server requirements</a></li>
+<li><a href="Server-configuration.html">Server configuration</a></li>
+<li><a href="Server-security.html">Server security</a></li>
+<li><a href="Shaarli-configuration.html">Shaarli configuration</a></li>
+<li><a href="Plugins.html">Plugins</a></li>
+</ul></li>
+<li><a href="Docker.html">Docker</a></li>
+<li><a href="Usage.html">Usage</a>
+<ul>
+<li><a href="Sharing-button.html">Sharing button</a> (bookmarklet)</li>
+<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
+<li><a href="Firefox-share.html">Firefox share</a></li>
+<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
+</ul></li>
+<li>How To
+<ul>
+<li><a href="Backup,-restore,-import-and-export.html">Backup, restore, import and export</a></li>
+<li><a href="Copy-an-existing-installation-over-SSH-and-serve-it-locally.html">Copy an existing installation over SSH and serve it locally</a></li>
+<li><a href="Create-and-serve-multiple-Shaarlis-(farm).html">Create and serve multiple Shaarlis (farm)</a></li>
+<li><a href="Download-CSS-styles-from-an-OPML-list.html">Download CSS styles from an OPML list</a></li>
+<li><a href="Datastore-hacks.html">Datastore hacks</a></li>
+</ul></li>
+<li><a href="Troubleshooting.html">Troubleshooting</a></li>
+<li><a href="Development.html">Development</a>
+<ul>
+<li><a href="GnuPG-signature.html">GnuPG signature</a></li>
+<li><a href="Coding-guidelines.html">Coding guidelines</a></li>
+<li><a href="Directory-structure.html">Directory structure</a></li>
+<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
+<li><a href="Plugin-System.html">Plugin System</a></li>
+<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
+<li><a href="Security.html">Security</a></li>
+<li><a href="Static-analysis.html">Static analysis</a></li>
+<li><a href="Theming.html">Theming</a></li>
+<li><a href="Unit-tests.html">Unit tests</a></li>
+</ul></li>
+<li>About
+<ul>
+<li><a href="FAQ.html">FAQ</a></li>
+<li><a href="Community-&-Related-software.html">Community & Related software</a></li>
+</ul></li>
+</ul>
+</div>
+<h1 id="versioning-and-branches">Versioning and Branches</h1>
+<p>[<strong>WORK IN PROGRESS</strong>][](.html)</p>
+<p>It's important to understand how Shaarli branches work, especially if you're maintaining a 3rd party tools for Shaarli (theme, plugin, etc.), to be sure stay compatible.</p>
+<h2 id="master-branch"><code>master</code> branch</h2>
+<p>The <code>master</code> branch is the development branch. Any new change MUST go through this branch using Pull Requests.</p>
+<p>Remarks:</p>
+<ul>
+<li>This branch shouldn't be used for production as it isn't necessary stable.</li>
+<li>3rd party aren't required to be compatible with the latest changes.</li>
+<li>Official plugins, themes and libraries (contained within Shaarli organization repos) must be compatible with the master branch.</li>
+<li>The version in this branch is always <code>dev</code>.</li>
+</ul>
+<h2 id="v0.x-branch"><code>v0.x</code> branch</h2>
+<p>This <code>v0.x</code> branch, points to the latest <code>v0.x.y</code> release.</p>
+<p>Explanation:</p>
+<p>When a new version is released, it might contains a major bug which isn't detected right away. For example, a new PHP version is released, containing backward compatibility issue which doesn't work with Shaarli.</p>
+<p>In this case, the issue is fixed in the <code>master</code> branch, and the fix is backported the to the <code>v0.x</code> branch. Then a new release is made from the <code>v0.x</code> branch.</p>
+<p>This workflow allow us to fix any major bug detected, without having to release bleeding edge feature too soon.</p>
+<h2 id="latest-branch"><code>latest</code> branch</h2>
+<p>This branch point the latest release. It recommended to use it to get the latest tested changes.</p>
+<h2 id="stable-branch"><code>stable</code> branch</h2>
+<p>The <code>stable</code> branch doesn't contain any major bug, and is one major digit version behind the latest release.</p>
+<p>For example, the current latest release is <code>v0.8.3</code>, the stable branch is an alias to the latest <code>v0.7.x</code> release. When the <code>v0.9.0</code> version will be released, the stable will move to the latest <code>v0.8.x</code> release.</p>
+<p>Remarks:</p>
+<ul>
+<li>Shaarli release pace isn't fast, and the stable branch might be a few months behind the latest release.</li>
+</ul>
+<h2 id="releases">Releases</h2>
+<p>Releases are always made from the latest <code>v0.x</code> branch.</p>
+<p>Note that for every release, we manually generate a tarball which contains all Shaarli dependencies, making Shaarli's installation only one step.</p>
+<h2 id="advices-on-3rd-party-git-repos-workflow">Advices on 3rd party git repos workflow</h2>
+<h3 id="versioning">Versioning</h3>
+<p>Any time a new Shaarli release is published, you should publish a new release of your repo if the changes affected you since the latest release (take a look at the <a href="https://github.com/shaarli/Shaarli/releases">changelog</a> (<em>Draft</em> means not released yet) and the commit log (like <a href="https://github.com/shaarli/Shaarli/commits/master/tpl/default"><code>tpl</code> folder</a> for themes)). You can either:<a href=".html"></a></p>
+<ul>
+<li>use the Shaarli version number, with your repo version. For example, if Shaarli <code>v0.8.3</code> is released, publish a <code>v0.8.3-1</code> release, where <code>v0.8.3</code> states Shaarli compatibility and <code>-1</code> is your own version digit for the current Shaarli version.</li>
+<li>use your own versioning scheme, and state Shaarli compatibility in the release description.</li>
+</ul>
+<p>Using this, any user will be able to pick the release matching his own Shaarli version.</p>
+<h3 id="major-bugfix-backport-releases">Major bugfix backport releases</h3>
+<p>To be able to support backported fixes, it recommended to use our workflow:</p>
+<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="co"># In master, fix the major bug</span>
+<span class="fu">git</span> commit -m <span class="st">"Katastrophe"</span>
+<span class="fu">git</span> push origin master
+<span class="co"># Get your commit hash</span>
+<span class="fu">git</span> log --format=<span class="st">"%H"</span> -n 1
+<span class="co"># Create a new branch from your latest release, let's say v0.8.2-1 (the tag name)</span>
+<span class="fu">git</span> checkout -b katastrophe v0.8.2-1
+<span class="co"># Backport the fix commit to your brand new branch</span>
+<span class="fu">git</span> cherry-pick <span class="op"><</span>fix commit hash<span class="op">></span>
+<span class="fu">git</span> push origin katastrophe
+<span class="co"># Then you just have to make a new release from the `katastrophe` branch tagged `v0.8.3-1`</span></code></pre></div>
+</body>
+</html>
--- /dev/null
+#Versioning and Branches
+[**WORK IN PROGRESS**][](.html)
+
+It's important to understand how Shaarli branches work, especially if you're maintaining a 3rd party tools for Shaarli (theme, plugin, etc.), to be sure stay compatible.
+
+## `master` branch
+
+The `master` branch is the development branch. Any new change MUST go through this branch using Pull Requests.
+
+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`.
+
+## `v0.x` branch
+
+This `v0.x` branch, points to the latest `v0.x.y` release.
+
+Explanation:
+
+When a new version is released, it might contains a major bug which isn't detected right away. For example, a new PHP version is released, containing backward compatibility issue which doesn't work with Shaarli.
+
+In this case, the issue is fixed in the `master` branch, and the fix is backported the to the `v0.x` branch. Then a new release is made from the `v0.x` branch.
+
+This workflow allow us to fix any major bug detected, without having to release bleeding edge feature too soon.
+
+## `latest` branch
+
+This branch point the latest release. It recommended to use it to get the latest tested changes.
+
+## `stable` branch
+
+The `stable` branch doesn't contain any major bug, and is one major digit version behind the latest release.
+
+For example, the current latest release is `v0.8.3`, the stable branch is an alias to the latest `v0.7.x` release. When the `v0.9.0` version will be released, the stable will move to the latest `v0.8.x` release.
+
+Remarks:
+
+ * Shaarli release pace isn't fast, and the stable branch might be a few months behind the latest release.
+
+## Releases
+
+Releases are always made from the latest `v0.x` branch.
+
+Note that for every release, we manually generate a tarball which contains all Shaarli dependencies, making Shaarli's installation only one step.
+
+## Advices on 3rd party git repos workflow
+
+### Versioning
+
+Any time a new Shaarli release is published, you should publish a new release of your repo if the changes affected you since the latest release (take a look at the [changelog](https://github.com/shaarli/Shaarli/releases) (*Draft* means not released yet) and the commit log (like [`tpl` folder](https://github.com/shaarli/Shaarli/commits/master/tpl/default) for themes)). You can either:[](.html)
+
+ - use the Shaarli version number, with your repo version. For example, if Shaarli `v0.8.3` is released, publish a `v0.8.3-1` release, where `v0.8.3` states Shaarli compatibility and `-1` is your own version digit for the current Shaarli version.
+ - use your own versioning scheme, and state Shaarli compatibility in the release description.
+
+Using this, any user will be able to pick the release matching his own Shaarli version.
+
+### Major bugfix backport releases
+
+To be able to support backported fixes, it recommended to use our workflow:
+
+```bash
+# In master, fix the major bug
+git commit -m "Katastrophe"
+git push origin master
+# Get your commit hash
+git log --format="%H" -n 1
+# Create a new branch from your latest release, let's say v0.8.2-1 (the tag name)
+git checkout -b katastrophe v0.8.2-1
+# Backport the fix commit to your brand new branch
+git cherry-pick <fix commit hash>
+git push origin katastrophe
+# Then you just have to make a new release from the `katastrophe` branch tagged `v0.8.3-1`
+```
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
- [Browsing and Searching](Browsing-and-Searching.html)
- [Firefox share](Firefox-share.html)
- [RSS feeds](RSS-feeds.html)
+ - [REST API](REST-API.html)
- How To
- [Backup, restore, import and export](Backup,-restore,-import-and-export.html)
- [Copy an existing installation over SSH and serve it locally](Copy-an-existing-installation-over-SSH-and-serve-it-locally.html)
- [3rd party libraries](3rd-party-libraries.html)
- [Plugin System](Plugin-System.html)
- [Release Shaarli](Release-Shaarli.html)
+ - [Versioning and Branches](Versioning-and-Branches.html)
- [Security](Security.html)
- [Static analysis](Static-analysis.html)
- [Theming](Theming.html)
<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
<li><a href="Firefox-share.html">Firefox share</a></li>
<li><a href="RSS-feeds.html">RSS feeds</a></li>
+<li><a href="REST-API.html">REST API</a></li>
</ul></li>
<li>How To
<ul>
<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
<li><a href="Plugin-System.html">Plugin System</a></li>
<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
+<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
<li><a href="Security.html">Security</a></li>
<li><a href="Static-analysis.html">Static analysis</a></li>
<li><a href="Theming.html">Theming</a></li>
projects / github / shaarli / Shaarli.git / commitdiff
