Knah-Tsaeb/MyShaarli
Knah-Tsaeb/MyShaarli
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

[doc] sync doc with latest wiki, build HTML

Browse source
This commit is contained in:
nodiscc 2015-06-26 21:56:43 +02:00
parent 927a84119c
commit da9b0e3e80
9 changed files with 446 additions and 236 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

143
doc/Home.html
View file

@ -14,8 +14,7 @@
<body>
<h1 id="shaarli-wiki">Shaarli wiki</h1>
<p>Welcome to the <a href="https://github.com/shaarli/Shaarli/">Shaarli</a> wiki! Here you can find some info on how to use, configure, tweak and solve problems with your Shaarli. For general info, read the <a href="https://github.com/shaarli/Shaarli/blob/master/README.md">README</a>.</p>
<p>If you have any questions or ideas, please join the <a href="https://gitter.im/shaarli/Shaarli">chat</a> (also reachable via <a href="https://irc.gitter.im/">IRC</a>), post them in our <a href="https://github.com/shaarli/Shaarli/issues/44">general discussion</a> or read the current <a href="https://github.com/shaarli/Shaarli/issues">issues</a>. If you've found a bug, please create a <a href="https://github.com/shaarli/Shaarli/issues/new">new issue</a>.</p>
<p>If you'd like a feature added, see if it fits in the list of <a href="Ideas-for-plugins">Ideas for Plugins</a> and update the corresponding bug report.</p>
<p>If you have any questions or ideas, please join the <a href="https://gitter.im/shaarli/Shaarli">chat</a> (also reachable via <a href="https://irc.gitter.im/">IRC</a>), post them in our <a href="https://github.com/shaarli/Shaarli/issues/44">general discussion</a> or read the current <a href="https://github.com/shaarli/Shaarli/issues">issues</a>. If you've found a bug, please create a <a href="https://github.com/shaarli/Shaarli/issues/new">new issue</a>. If you would like a feature added to Shaarli, check the issues labeled <a href="https://github.com/shaarli/Shaarli/labels/feature"><code>feature</code></a>, <a href="https://github.com/shaarli/Shaarli/labels/enhancement"><code>enhancement</code></a>, and <a href="https://github.com/shaarli/Shaarli/labels/plugin"><code>plugin</code></a>.</p>
<p><em>Note: This documentation is available online at <a href="https://github.com/shaarli/Shaarli/wiki">https://github.com/shaarli/Shaarli/wiki</a>, and locally in the <code>doc/</code> directory of your Shaarli installation.</em></p>
<hr />
<!-- MarkdownTOC depth=3 -->
@ -25,7 +24,9 @@
<li><p><a href="#basic-usage">Basic Usage</a></p>
<ul>
<li><a href="#add-the-sharing-button-_bookmarklet_-to-your-browser">Add the sharing button (<em>bookmarklet</em>) to your browser</a><br /></li>
<li><a href="#add-shaarli-as-a-sharing-service-to-firefox">Add Shaarli as a sharing service to Firefox</a><br /></li>
<li><a href="#share-links-using-the-_bookmarklet_">Share links using the <em>bookmarklet</em></a><br /></li>
<li><a href="#sharing-links-using-firefox-share">Sharing links using Firefox share</a><br /></li>
</ul></li>
<li><p><a href="#other-usage-examples">Other usage examples</a></p>
<ul>
@ -59,7 +60,14 @@
<li><a href="#various-hacks">Various hacks</a><br /></li>
<li><a href="#changing-timestamp-for-a-link">Changing timestamp for a link</a><br /></li>
</ul></li>
<li><a href="#related-software">Related software</a><br /></li>
<li><p><a href="#related-software">Related software</a></p>
<ul>
<li><a href="#server-apps">Server apps</a><br /></li>
<li><a href="#android-apps">Android apps</a><br /></li>
<li><a href="#themes--templates">Themes &amp; templates</a><br /></li>
<li><a href="#integrate-shaarli-with-other-platforms">Integrate Shaarli with other platforms</a><br /></li>
<li><a href="#alternative-to-shaarli">Alternative to Shaarli</a><br /></li>
</ul></li>
<li><a href="#other-links">Other links</a><br /></li>
<li><p><a href="#faq">FAQ</a></p>
<ul>
@ -70,6 +78,7 @@
<li><p><a href="#technical-details">Technical details</a></p>
<ul>
<li><a href="#directory-structure">Directory structure</a><br /></li>
<li><a href="#development">Development</a><br /></li>
<li><a href="#why-not-use-a-real-database--files-are-slow-">Why not use a real database ? Files are slow !</a><br /></li>
</ul></li>
<li><p><a href="#wiki---todo">Wiki - TODO</a></p></li>
@ -89,6 +98,12 @@
</ul>
<p><em>This bookmarklet button in compatible with Firefox, Opera, Chrome and Safari. Under Opera, you can't drag'n drop the button: You have to right-click on it and add a bookmark to your personal toolbar.</em></p>
<p><img src="images/bookmarklet.png" /></p>
<h3 id="add-shaarli-as-a-sharing-service-to-firefox">Add Shaarli as a sharing service to Firefox</h3>
<ul>
<li>Open your Shaarli and <code>Login</code><br /></li>
<li>Click the <code>Tools</code> button in the top bar<br /></li>
<li>Click the <code>✚Add to Firefox social</code> button and accept the activation.</li>
</ul>
<h3 id="share-links-using-the-bookmarklet">Share links using the <em>bookmarklet</em></h3>
<ul>
<li>When you are visiting a webpage you would like to share with Shaarli, click the <em>bookmarklet</em> you just added.<br /></li>
@ -98,6 +113,12 @@
<li>You can also check the “Private” box so that the link is saved but only visible to you.<br /></li>
<li>Click <code>Save</code>.<strong>Voila! Your link is now shared.</strong></li>
</ul>
<h3 id="sharing-links-using-firefox-share">Sharing links using Firefox share</h3>
<ul>
<li>Add the sharing service as described above<br /></li>
<li>When you are visiting a webpage you would like to share with Shaarli, click the Firefox <em>Share</em> button [[images/firefoxshare.png]]<br /></li>
<li>You can edit your link before and after saving, just like the bookmarklet above.</li>
</ul>
<h1 id="other-usage-examples">Other usage examples</h1>
<p>Shaarli can be used:</p>
<ul>
@ -134,7 +155,7 @@
<li>The same method <strong>also works for a full-text search</strong> (<em>Search</em> box) <strong>and for the Picture Wall</strong> (want to only see pictures about <code>nature</code>?)<br /></li>
<li>You can also build the URL manually: <code>https://my.shaarli.domain/?do=rss&amp;searchtags=nature</code>, <code>https://my.shaarli.domain/links/?do=picwall&amp;searchterm=poney</code></li>
</ul>
<p><img src="rss-filter-1.png" /> <img src="rss-filter-2.png" /></p>
<p><img src="images/rss-filter-1.png" /> <img src="images/rss-filter-2.png" /></p>
<h1 id="configuration">Configuration</h1>
<h3 id="main-dataoptions.php-file">Main data/options.php file</h3>
<p>To change the configuration, create the file <code>data/options.php</code>, example:</p>
@ -153,10 +174,10 @@
<li><code>BAN_AFTER (4)</code> : An IP address will be banned after this many failed login attempts.<br /></li>
<li><code>BAN_DURATION (1800)</code> : Duration of ban (in seconds). (1800 seconds = 30 minutes)<br /></li>
<li><code>OPEN_SHAARLI (false)</code> : If you set this option to true, anyone will be able to add/modify/delete/import/exports links without having to login.<br /></li>
<li><code>HIDE_TIMESTAMPS (false)</code> : If you set this option to true, the date/time of each link will not be displayed (including in RSS Feed).<br /></li>
<li><code>HIDE_TIMESTAMPS (false)</code> : If you set this option to true, the date/time of each link will not be displayed (including in RSS Feed).#related-software<br /></li>
<li><code>ENABLE_THUMBNAILS (true)</code> : Enable/disable thumbnails.<br /></li>
<li><code>RAINTPL_TMP (tmp/)</code> : Raintpl cache directory (keep the trailing slash!)<br /></li>
<li>`RAINTPL_TPL (tpl/) : Raintpl template directory (keep the trailing slash!). Edit this option if you want to change the rendering template (page structure) used by Shaarli. See <a href="#changing-template">Changing template</a><br /></li>
<li><code>RAINTPL_TPL (tpl/)</code> : Raintpl template directory (keep the trailing slash!). Edit this option if you want to change the rendering template (page structure) used by Shaarli. See <a href="#changing-template">Changing template</a><br /></li>
<li><code>CACHEDIR ('cache')</code> : Directory where the thumbnails are stored.<br /></li>
<li><code>ENABLE_LOCALCACHE (true)</code> : If you have a limited quota on your webspace, you can set this option to false: Shaarli will not generate thumbnails which need to be cached locally (vimeo, flickr, etc.). Thumbnails will still be visible for the services which do not use the local cache (youtube.com, imgur.com, dailymotion.com, imageshack.us)<br /></li>
<li><code>UPDATECHECK_FILENAME ($GLOBALS['config']['DATADIR'].'/lastupdatecheck.txt')</code> : name of the file used to store available shaarli version.<br /></li>
@ -164,7 +185,8 @@
<li><code>ENABLE_UPDATECHECK</code>: Determines whether Shaarli check for new releases at <a href="https://github.com/shaarli/Shaarli">https://github.com/shaarli/Shaarli</a><br /></li>
<li><code>SHOW_ATOM (false)</code> : Show an <code>ATOM Feed</code> button next to the <code>Subscribe</code> (RSS) button. ATOM feeds are available at the address <code>?do=atom</code> regardless of this option.<br /></li>
<li><code>ARCHIVE_ORG (false)</code> : For each link, display a link to an archived version on archive.org<br /></li>
<li><code>ENABLE_RSS_PERMALINKS (true)</code>: choose whether the RSS item title link points directly to the link, or to the entry on Shaarli (permalink). <code>true</code> is the original Shaarli bahevior (point directly to the link)</li>
<li><code>ENABLE_RSS_PERMALINKS (true)</code>: choose whether the RSS item title link points directly to the link, or to the entry on Shaarli (permalink). <code>true</code> is the original Shaarli bahevior (point directly to the link)<br /></li>
<li><code>HIDE_PUBLIC_LINKS (false)</code>: setting this to true hides all links, even public ones, for non-logged in users.</li>
</ul>
<h3 id="changing-theme">Changing theme</h3>
<ul>
@ -177,14 +199,14 @@
<li><a href="https://github.com/shaarli/Shaarli/wiki/Download-CSS-styles-for-shaarlis-listed-in-an-opml-file">Download CSS styles for shaarlis listed in an opml file</a></li>
</ul>
<h3 id="changing-template">Changing template</h3>
<p>| 💥 | This feature is currently being worked on and will be improved in the next releases. Experimental. |<br />|---------|---------|</p>
<p>| WARNING | This feature is currently being worked on and will be improved in the next releases. Experimental. |<br />|---------|---------|</p>
<ul>
<li>Find the template you'd like to install. See the list of available templates (TODO). Find it's git clone URL or download the zip archive for the template.<br /></li>
<li>In your Shaarli <code>tpl/</code> directory, run <code>git clone https://url/of/my-template/</code> or unpack the zip archive. There should now be a <code>my-template/</code> directory under the <code>tpl/</code> dir, containing directly all the template files.<br /></li>
<li>Edit <code>data/options.php</code> to have Shaarli use this template. Eg.</li>
</ul>
<p><code>$GLOBALS['config']['RAINTPL_TPL'] = 'tpl/my-template/' ;</code></p>
<p>You can find a list of compatible templates in <a href="#Related-software">Related Software</a></p>
<p>You can find a list of compatible templates in <a href="#related-software">Related Software</a></p>
<h1 id="backup">Backup</h1>
<p>You have two ways of backing up your database:</p>
<ul>
@ -248,7 +270,14 @@ SetEnv PHP_VER 5</code></pre>
<ul>
<li><a href="Example-patch---add-new-via-field-for-links">Example patch: add a new &quot;via&quot; field for links</a><br /></li>
<li><a href="Copy-a-Shaarli-installation-over-SSH-SCP,-serve-it-locally-with-php-cli">Copy a Shaarli installation over SSH SCP, serve it locally with php cli</a><br /></li>
<li>To display the array representing the data saved in datastore.php, use the following snippet (TODO where is it gone?)</li>
<li><p>To display the array representing the data saved in datastore.php, use the following snippet</p>
<pre><code>$data = &quot;tZNdb9MwFIb... &lt;Commented content inside datastore.php&gt;&quot;;
$out = unserialize(gzinflate(base64_decode($data)));
echo &quot;&lt;pre&gt;&quot;; // Pretty printing is love, pretty printing is life
print_r($out);
echo &quot;&lt;/pre&gt;&quot;;
exit;</code></pre>
<p>This will output the internal representation of the datastore, &quot;unobfuscated&quot; (if this can really be considered obfuscation)</p></li>
</ul>
<h3 id="changing-timestamp-for-a-link">Changing timestamp for a link</h3>
<ul>
@ -256,33 +285,39 @@ SetEnv PHP_VER 5</code></pre>
<li>Remove <code>type=&quot;hidden&quot;</code> from this line<br /></li>
<li>A new date/time field becomes available in the edit/new link dialog. You can set the timestamp manually by entering it in the format <code>YYYMMDD_HHMMS</code>.</li>
</ul>
<pre><code>$data = &quot;tZNdb9MwFIb... &lt;Commented content inside datastore.php&gt;&quot;;
$out = unserialize(gzinflate(base64_decode($data)));
echo &quot;&lt;pre&gt;&quot;; // Pretty printing is love, pretty printing is life
print_r($out);
echo &quot;&lt;/pre&gt;&quot;;
exit;</code></pre>
<p>This will output the internal representation of the datastore, &quot;unobfuscated&quot; (if this can really be considered obfuscation)</p>
<h1 id="related-software">Related software</h1>
<p>Unofficial but relatedd work on Shaarli. If you maintain one of these, please get in touch with us to help us find a way to adapt your work to our fork. <strong>TODO</strong> contact repos owners to see if they'd like to standardize their work for the community fork.</p>
<h3 id="server-apps">Server apps</h3>
<ul>
<li><a href="https://github.com/nodiscc/shaarchiver">shaarchiver</a> - Archive your Shaarli bookmarks and their content<br /></li>
<li><a href="http://sebsauvage.net/links/?ZAyDzg">Shaarli for Android</a> - Android application that adds Shaarli as a sharing provider<br /></li>
<li><a href="https://play.google.com/store/apps/details?id=com.dimtion.shaarlier">Shaarlier for Android</a> - Android application to simply add links directly into your Shaarli<br /></li>
<li><a href="https://github.com/mknexen/shaarli-river">shaarli-river</a> - an aggregator for shaarlis with many features<br /></li>
<li><a href="https://github.com/DMeloni/shaarlo">Shaarlo</a> - an aggregator for shaarlis with many features (<a href="http://shaarli.fr/">Demo</a>)<br /></li>
<li><a href="https://github.com/kalvn/shaarli-blocks">kalvn/shaarli-blocks</a> - A template/theme for Shaarli<br /></li>
<li><a href="https://github.com/kalvn/Shaarli-Material">kalvn/Shaarli-Material</a> -<br />A theme (template) based on Google's Material Design for Shaarli, the superfast delicious clone.<br /></li>
<li><a href="https://github.com/Vinm/Blue-theme-for-Shaarli">Vinm/Blue-theme-for Shaarli</a> - A template/theme for Shaarli (<a href="https://github.com/Vinm/Blue-theme-for-Shaarli/issues/2">unmaintained</a>, compatibility unknown)<br /></li>
<li><a href="https://github.com/vivienhaese/shaarlitheme">vivienhaese/shaarlitheme</a> - A Shaarli fork meant to be run in an openshift instance<br /></li>
<li><a href="https://github.com/jcsaaddupuy/tt-rss-shaarli">tt-rss-shaarli</a> - <a href="http://tt-rss.org/">TinyTiny RSS</a> plugin that adds support for sharing articles with Shaarli<br /></li>
<li><a href="https://github.com/dhoko/ShaarliTemplate">dhoko/ShaarliTemplate</a> - A template/theme for Shaarli<br /></li>
<li><a href="https://github.com/mknexen/shaarli-api">mknexen/shaarli-api</a> - a REST API for Shaarli<br /></li>
<li><a href="https://github.com/alexisju/albinomouse-template">Albinomouse</a> - A full template for Shaarli<br /></li>
<li><a href="https://github.com/mknexen/shaarli-river">shaarli-river</a> - An aggregator for shaarlis with many features<br /></li>
<li><a href="https://github.com/DMeloni/shaarlo">Shaarlo</a> - An aggregator for shaarlis with many features (a very popular running instance among french shaarliers: <a href="http://shaarli.fr/">shaarli.fr</a>)<br /></li>
<li><a href="https://github.com/BoboTiG/shaarlimages">Shaarlimages</a> - An image-oriented aggregator for Shaarlis<br /></li>
<li><a href="https://github.com/AkibaTech/Shaarli---SuperHero-Theme">Shaarli Superhero Theme</a> - A template/theme for Shaarli<br /></li>
<li><a href="https://github.com/misterair/limonade">Limonade</a> - A fork of Shaarli with a new template<br /></li>
<li><a href="https://github.com/ahmet2mir/octopress-shaarli">octopress-shaarli</a> - octoprress plugin to retrieve SHaarli links on the sidebara<br /></li>
<li><a href="https://github.com/mknexen/shaarli-api">mknexen/shaarli-api</a> - A REST API for Shaarli</li>
</ul>
<h3 id="android-apps">Android apps</h3>
<ul>
<li><a href="http://sebsauvage.net/links/?ZAyDzg">Shaarli for Android</a> - Android application that adds Shaarli as a sharing provider<br /></li>
<li><a href="https://github.com/dimtion/Shaarlier">Shaarlier for Android</a> - Android application to simply add links directly into your Shaarli</li>
</ul>
<h3 id="themes-templates">Themes &amp; templates</h3>
<ul>
<li><a href="https://github.com/AkibaTech/Shaarli---SuperHero-Theme">AkibaTech/Shaarli Superhero Theme</a> - A template/theme for Shaarli<br /></li>
<li><a href="https://github.com/alexisju/albinomouse-template">alexisju/albinomouse-template</a> - A full template for Shaarli<br /></li>
<li><a href="https://github.com/dhoko/ShaarliTemplate">dhoko/ShaarliTemplate</a> - A template/theme for Shaarli<br /></li>
<li><a href="https://github.com/kalvn/shaarli-blocks">kalvn/shaarli-blocks</a> - A template/theme for Shaarli<br /></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.<br /></li>
<li><a href="https://github.com/misterair/limonade">misterair/Limonade</a> - A fork of (legacy) Shaarli with a new template<br /></li>
<li><a href="https://github.com/Vinm/Blue-theme-for-Shaarli">Vinm/Blue-theme-for Shaarli</a> - A template/theme for Shaarli (<a href="https://github.com/Vinm/Blue-theme-for-Shaarli/issues/2">unmaintained</a>, compatibility unknown)<br /></li>
<li><a href="https://github.com/vivienhaese/shaarlitheme">vivienhaese/shaarlitheme</a> - A Shaarli fork meant to be run in an openshift instance</li>
</ul>
<h3 id="integrate-shaarli-with-other-platforms">Integrate Shaarli with other platforms</h3>
<ul>
<li><a href="https://github.com/jcsaaddupuy/tt-rss-shaarli">tt-rss-shaarli</a> - <a href="http://tt-rss.org/">TinyTiny RSS</a> plugin that adds support for sharing articles with Shaarli<br /></li>
<li><a href="https://github.com/ahmet2mir/octopress-shaarli">octopress-shaarli</a> - octoprress plugin to retrieve SHaarli links on the sidebara</li>
</ul>
<h3 id="alternative-to-shaarli">Alternative to Shaarli</h3>
<ul>
<li><a href="https://github.com/bookieio/bookie">Bookie</a> - Another self-hostable, Free bookmark sharing software, written in Python<br /></li>
<li><a href="https://github.com/plainmade/unmark">Unmark</a> - An open source to do app for bookmarks (<a href="https://unmark.it/">Homepage</a>)</li>
</ul>
@ -333,36 +368,48 @@ exit;</code></pre>
<h3 id="directory-structure">Directory structure</h3>
<p>Here is the directory structure of Shaarli and the purpose of the different files:</p>
<pre><code> index.php : Main program.
application/ : Shaarli classes
├── LinkDB.php
└── Utils.php
tests/ : Shaarli unitary &amp; functional tests
├── LinkDBTest.php
├── utils # utilities to ease testing
│ └── ReferenceLinkDB.php
└── UtilsTest.php
COPYING : Shaarli license.
inc/ : Includes (libraries, CSS…)
shaarli.css : Shaarli stylesheet.
jquery.min.js : jQuery javascript library.
jquery-ui.min.js : jQuery-UI javascript library.
jquery-MIT-LICENSE.txt: jQuery license.
jquery.lazyload.min.js: LazyLoad javascript library.
rain.tpl.class.php : RainTPL templating library.
├── awesomplete.*: tags autocompletion library
├── blazy.*: picture wall lazy image loading library
├── shaarli.css, reset.css : Shaarli stylesheet.
├── qr.* : qr code generation library
└──rain.tpl.class.php : RainTPL templating library.
tpl/ : RainTPL templates for Shaarli. They are used to build the pages.
images/ : Images and icons used in Shaarli.
data/ : Directory where data is stored (bookmark database, configuration, logs, banlist…)
config.php : Shaarli configuration (login, password, timezone, title…)
datastore.php : Your link database (compressed).
ipban.php : IP address ban system data.
lastupdatecheck.txt : Update check timestamp file (used to check every 24 hours if a new version of Shaarli is available).
log.txt : login/IPban log.
├── config.php : Shaarli configuration (login, password, timezone, title…)
├── datastore.php : Your link database (compressed).
├── ipban.php : IP address ban system data.
├── lastupdatecheck.txt : Update check timestamp file (used to check every 24 hours if a new version of Shaarli is available).
└──log.txt : login/IPban log.
cache/ : Directory containing the thumbnails cache. This directory is automatically created. You can erase it anytime you want.
tmp/ : Temporary directory for compiled RainTPL templates. This directory is automatically created. You can erase it anytime you want.</code></pre>
<h3 id="development">Development</h3>
<ul>
<li><a href="https://github.com/shaarli/Shaarli/tree/master/CONTRIBUTING.md">Contributing to Shaarli</a><br /></li>
<li><a href="Running-unit-tests">Running unit tests</a><br /></li>
<li>Patches should try to stick to the <a href="http://www.php-fig.org/psr/">PHP Standard Recommendations</a> (PSR), especially:<br /></li>
<li><a href="http://www.php-fig.org/psr/psr-1/">PSR-1</a> - Basic Coding Standard<br /></li>
<li><a href="http://www.php-fig.org/psr/psr-2/">PSR-2</a> - Coding Style Guide</li>
</ul>
<h3 id="why-not-use-a-real-database-files-are-slow">Why not use a real database ? Files are slow !</h3>
<p>Does browsing <a href="http://sebsauvage.net/links/">this page</a> feel slow ? Try browsing older pages, too.</p>
<p>It's not slow at all, is it ? And don't forget the database contains more than 16000 links, and it's on a shared host, with 32000 visitors/day for my website alone. And it's still damn fast. Why ?</p>
<p>The data file is only 3.7 Mb. It's read 99% of the time, and is probably already in the operation system disk cache. So generating a page involves no I/O at all most of the time.</p>
<h1 id="wiki---todo">Wiki - TODO</h1>
<ul>
<li>Translate (new page can be called Home.fr, Home.es ...) and linked from Home<br /></li>
<li>translate (new page can be called Home.fr, Home.es ... and linked from Home)<br /></li>
<li>add more screenshots<br /></li>
<li>add developer documentation (storage architecture, classes and functions, security handling, ...)<br /></li>
<li>Contact related projects<br /></li>
<li>Add a Table of Contents to the wiki (can be added to the sidebar)</li>
<li>add developer documentation (storage architecture, classes and functions, security handling, ...)</li>
</ul>
<p>...</p>
</body>
</html>

125
doc/Home.md
View file

@ -2,9 +2,7 @@
Welcome to the [Shaarli](https://github.com/shaarli/Shaarli/) wiki! Here you can find some info on how to use, configure, tweak and solve problems with your Shaarli. For general info, read the [README](https://github.com/shaarli/Shaarli/blob/master/README.md).
If you have any questions or ideas, please join the [chat](https://gitter.im/shaarli/Shaarli) (also reachable via [IRC](https://irc.gitter.im/)), post them in our [general discussion](https://github.com/shaarli/Shaarli/issues/44) or read the current [issues](https://github.com/shaarli/Shaarli/issues). If you've found a bug, please create a [new issue](https://github.com/shaarli/Shaarli/issues/new).
If you'd like a feature added, see if it fits in the list of [Ideas for Plugins](Ideas-for-plugins) and update the corresponding bug report.
If you have any questions or ideas, please join the [chat](https://gitter.im/shaarli/Shaarli) (also reachable via [IRC](https://irc.gitter.im/)), post them in our [general discussion](https://github.com/shaarli/Shaarli/issues/44) or read the current [issues](https://github.com/shaarli/Shaarli/issues). If you've found a bug, please create a [new issue](https://github.com/shaarli/Shaarli/issues/new). If you would like a feature added to Shaarli, check the issues labeled [`feature`](https://github.com/shaarli/Shaarli/labels/feature), [`enhancement`](https://github.com/shaarli/Shaarli/labels/enhancement), and [`plugin`](https://github.com/shaarli/Shaarli/labels/plugin).
_Note: This documentation is available online at https://github.com/shaarli/Shaarli/wiki, and locally in the `doc/` directory of your Shaarli installation._
@ -14,7 +12,9 @@ _Note: This documentation is available online at https://github.com/shaarli/Shaa
- [Basic Usage](#basic-usage)
- [Add the sharing button (_bookmarklet_) to your browser](#add-the-sharing-button-_bookmarklet_-to-your-browser)
- [Add Shaarli as a sharing service to Firefox](#add-shaarli-as-a-sharing-service-to-firefox)
- [Share links using the _bookmarklet_](#share-links-using-the-_bookmarklet_)
- [Sharing links using Firefox share](#sharing-links-using-firefox-share)
- [Other usage examples](#other-usage-examples)
- [Using Shaarli as a blog, notepad, pastebin...](#using-shaarli-as-a-blog-notepad-pastebin)
- [RSS Feeds or Picture Wall for a specific search/tag](#rss-feeds-or-picture-wall-for-a-specific-searchtag)
@ -40,6 +40,11 @@ _Note: This documentation is available online at https://github.com/shaarli/Shaa
- [Various hacks](#various-hacks)
- [Changing timestamp for a link](#changing-timestamp-for-a-link)
- [Related software](#related-software)
- [Server apps](#server-apps)
- [Android apps](#android-apps)
- [Themes & templates](#themes--templates)
- [Integrate Shaarli with other platforms](#integrate-shaarli-with-other-platforms)
- [Alternative to Shaarli](#alternative-to-shaarli)
- [Other links](#other-links)
- [FAQ](#faq)
- [Why did you create Shaarli ?](#why-did-you-create-shaarli-)
@ -47,6 +52,7 @@ _Note: This documentation is available online at https://github.com/shaarli/Shaa
- [What does Shaarli mean ?](#what-does-shaarli-mean-)
- [Technical details](#technical-details)
- [Directory structure](#directory-structure)
- [Development](#development)
- [Why not use a real database ? Files are slow !](#why-not-use-a-real-database--files-are-slow-)
- [Wiki - TODO](#wiki---todo)
@ -68,6 +74,14 @@ _This bookmarklet button in compatible with Firefox, Opera, Chrome and Safari. U
![](images/bookmarklet.png)
### Add Shaarli as a sharing service to Firefox
* Open your Shaarli and `Login`
* Click the `Tools` button in the top bar
* Click the `✚Add to Firefox social` button and accept the activation.
### Share links using the _bookmarklet_
* When you are visiting a webpage you would like to share with Shaarli, click the _bookmarklet_ you just added.
@ -78,6 +92,11 @@ _This bookmarklet button in compatible with Firefox, Opera, Chrome and Safari. U
* Click `Save`.**Voila! Your link is now shared.**
### Sharing links using Firefox share
* Add the sharing service as described above
* When you are visiting a webpage you would like to share with Shaarli, click the Firefox _Share_ button [[images/firefoxshare.png]]
* You can edit your link before and after saving, just like the bookmarklet above.
# Other usage examples
@ -116,7 +135,7 @@ It is possible to filter RSS/ATOM feeds and Picture Wall on a Shaarli to **only
* The same method **also works for a full-text search** (_Search_ box) **and for the Picture Wall** (want to only see pictures about `nature`?)
* You can also build the URL manually: `https://my.shaarli.domain/?do=rss&searchtags=nature`, `https://my.shaarli.domain/links/?do=picwall&searchterm=poney`
![](rss-filter-1.png) ![](rss-filter-2.png)
![](images/rss-filter-1.png) ![](images/rss-filter-2.png)
# Configuration
@ -141,10 +160,10 @@ To change the configuration, create the file `data/options.php`, example:
* `BAN_AFTER (4)` : An IP address will be banned after this many failed login attempts.
* `BAN_DURATION (1800)` : Duration of ban (in seconds). (1800 seconds = 30 minutes)
* `OPEN_SHAARLI (false)` : If you set this option to true, anyone will be able to add/modify/delete/import/exports links without having to login.
* `HIDE_TIMESTAMPS (false)` : If you set this option to true, the date/time of each link will not be displayed (including in RSS Feed).
* `HIDE_TIMESTAMPS (false)` : If you set this option to true, the date/time of each link will not be displayed (including in RSS Feed).#related-software
* `ENABLE_THUMBNAILS (true)` : Enable/disable thumbnails.
* `RAINTPL_TMP (tmp/)` : Raintpl cache directory (keep the trailing slash!)
* `RAINTPL_TPL (tpl/) : Raintpl template directory (keep the trailing slash!). Edit this option if you want to change the rendering template (page structure) used by Shaarli. See [Changing template](#changing-template)
* `RAINTPL_TPL (tpl/)` : Raintpl template directory (keep the trailing slash!). Edit this option if you want to change the rendering template (page structure) used by Shaarli. See [Changing template](#changing-template)
* `CACHEDIR ('cache')` : Directory where the thumbnails are stored.
* `ENABLE_LOCALCACHE (true)` : If you have a limited quota on your webspace, you can set this option to false: Shaarli will not generate thumbnails which need to be cached locally (vimeo, flickr, etc.). Thumbnails will still be visible for the services which do not use the local cache (youtube.com, imgur.com, dailymotion.com, imageshack.us)
* `UPDATECHECK_FILENAME ($GLOBALS['config']['DATADIR'].'/lastupdatecheck.txt')` : name of the file used to store available shaarli version.
@ -153,6 +172,7 @@ To change the configuration, create the file `data/options.php`, example:
* `SHOW_ATOM (false)` : Show an `ATOM Feed` button next to the `Subscribe` (RSS) button. ATOM feeds are available at the address `?do=atom` regardless of this option.
* `ARCHIVE_ORG (false)` : For each link, display a link to an archived version on archive.org
* `ENABLE_RSS_PERMALINKS (true)`: choose whether the RSS item title link points directly to the link, or to the entry on Shaarli (permalink). `true` is the original Shaarli bahevior (point directly to the link)
* `HIDE_PUBLIC_LINKS (false)`: setting this to true hides all links, even public ones, for non-logged in users.
### Changing theme
@ -165,7 +185,7 @@ See also:
### Changing template
| 💥 | This feature is currently being worked on and will be improved in the next releases. Experimental. |
| 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 (TODO). Find it's git clone URL or download the zip archive for the template.
@ -174,7 +194,7 @@ See also:
`$GLOBALS['config']['RAINTPL_TPL'] = 'tpl/my-template/' ;`
You can find a list of compatible templates in [Related Software](#Related-software)
You can find a list of compatible templates in [Related Software](#related-software)
# Backup
@ -267,13 +287,7 @@ Download [publisher.php](https://pubsubhubbub.googlecode.com/git/publisher_clien
* [Example patch: add a new "via" field for links](Example-patch---add-new-via-field-for-links)
* [Copy a Shaarli installation over SSH SCP, serve it locally with php cli](Copy-a-Shaarli-installation-over-SSH-SCP,-serve-it-locally-with-php-cli)
* To display the array representing the data saved in datastore.php, use the following snippet (TODO where is it gone?)
### Changing timestamp for a link
* Look for `<input type="hidden" name="lf_linkdate" value="{$link.linkdate}">` in `tpl/editlink.tpl` (line 14)
* Remove `type="hidden"` from this line
* A new date/time field becomes available in the edit/new link dialog. You can set the timestamp manually by entering it in the format `YYYMMDD_HHMMS`.
* To display the array representing the data saved in datastore.php, use the following snippet
```
$data = "tZNdb9MwFIb... <Commented content inside datastore.php>";
$out = unserialize(gzinflate(base64_decode($data)));
@ -284,28 +298,40 @@ exit;
```
This will output the internal representation of the datastore, "unobfuscated" (if this can really be considered obfuscation)
### Changing timestamp for a link
* Look for `<input type="hidden" name="lf_linkdate" value="{$link.linkdate}">` in `tpl/editlink.tpl` (line 14)
* Remove `type="hidden"` from this line
* A new date/time field becomes available in the edit/new link dialog. You can set the timestamp manually by entering it in the format `YYYMMDD_HHMMS`.
# Related software
Unofficial but relatedd work on Shaarli. If you maintain one of these, please get in touch with us to help us find a way to adapt your work to our fork. **TODO** contact repos owners to see if they'd like to standardize their work for the community fork.
### Server apps
* [shaarchiver](https://github.com/nodiscc/shaarchiver) - Archive your Shaarli bookmarks and their content
* [shaarli-river](https://github.com/mknexen/shaarli-river) - An aggregator for shaarlis with many features
* [Shaarlo](https://github.com/DMeloni/shaarlo) - An aggregator for shaarlis with many features (a very popular running instance among french shaarliers: [shaarli.fr](http://shaarli.fr/))
* [Shaarlimages](https://github.com/BoboTiG/shaarlimages) - An image-oriented aggregator for Shaarlis
* [mknexen/shaarli-api](https://github.com/mknexen/shaarli-api) - A REST API for Shaarli
### Android apps
* [Shaarli for Android](http://sebsauvage.net/links/?ZAyDzg) - Android application that adds Shaarli as a sharing provider
* [Shaarlier for Android](https://play.google.com/store/apps/details?id=com.dimtion.shaarlier) - Android application to simply add links directly into your Shaarli
* [shaarli-river](https://github.com/mknexen/shaarli-river) - an aggregator for shaarlis with many features
* [Shaarlo](https://github.com/DMeloni/shaarlo) - an aggregator for shaarlis with many features ([Demo](http://shaarli.fr/))
* [Shaarlier for Android](https://github.com/dimtion/Shaarlier) - Android application to simply add links directly into your Shaarli
### Themes & templates
* [AkibaTech/Shaarli Superhero Theme](https://github.com/AkibaTech/Shaarli---SuperHero-Theme) - A template/theme for Shaarli
* [alexisju/albinomouse-template](https://github.com/alexisju/albinomouse-template) - A full template for Shaarli
* [dhoko/ShaarliTemplate](https://github.com/dhoko/ShaarliTemplate) - A template/theme for Shaarli
* [kalvn/shaarli-blocks](https://github.com/kalvn/shaarli-blocks) - A template/theme for Shaarli
* [kalvn/Shaarli-Material](https://github.com/kalvn/Shaarli-Material) -
A theme (template) based on Google's Material Design for Shaarli, the superfast delicious clone.
* [kalvn/Shaarli-Material](https://github.com/kalvn/Shaarli-Material) - A theme (template) based on Google's Material Design for Shaarli, the superfast delicious clone.
* [misterair/Limonade](https://github.com/misterair/limonade) - A fork of (legacy) Shaarli with a new template
* [Vinm/Blue-theme-for Shaarli](https://github.com/Vinm/Blue-theme-for-Shaarli) - A template/theme for Shaarli ([unmaintained](https://github.com/Vinm/Blue-theme-for-Shaarli/issues/2), compatibility unknown)
* [vivienhaese/shaarlitheme](https://github.com/vivienhaese/shaarlitheme) - A Shaarli fork meant to be run in an openshift instance
### Integrate Shaarli with other platforms
* [tt-rss-shaarli](https://github.com/jcsaaddupuy/tt-rss-shaarli) - [TinyTiny RSS](http://tt-rss.org/) plugin that adds support for sharing articles with Shaarli
* [dhoko/ShaarliTemplate](https://github.com/dhoko/ShaarliTemplate) - A template/theme for Shaarli
* [mknexen/shaarli-api](https://github.com/mknexen/shaarli-api) - a REST API for Shaarli
* [Albinomouse](https://github.com/alexisju/albinomouse-template) - A full template for Shaarli
* [Shaarlimages](https://github.com/BoboTiG/shaarlimages) - An image-oriented aggregator for Shaarlis
* [Shaarli Superhero Theme](https://github.com/AkibaTech/Shaarli---SuperHero-Theme) - A template/theme for Shaarli
* [Limonade](https://github.com/misterair/limonade) - A fork of Shaarli with a new template
* [octopress-shaarli](https://github.com/ahmet2mir/octopress-shaarli) - octoprress plugin to retrieve SHaarli links on the sidebara
### Alternative to Shaarli
* [Bookie](https://github.com/bookieio/bookie) - Another self-hostable, Free bookmark sharing software, written in Python
* [Unmark](https://github.com/plainmade/unmark) - An open source to do app for bookmarks ([Homepage](https://unmark.it/))
@ -374,26 +400,41 @@ Here is the directory structure of Shaarli and the purpose of the different file
```
index.php : Main program.
application/ : Shaarli classes
├── LinkDB.php
└── Utils.php
tests/ : Shaarli unitary & functional tests
├── LinkDBTest.php
├── utils # utilities to ease testing
│ └── ReferenceLinkDB.php
└── UtilsTest.php
COPYING : Shaarli license.
inc/ : Includes (libraries, CSS…)
shaarli.css : Shaarli stylesheet.
jquery.min.js : jQuery javascript library.
jquery-ui.min.js : jQuery-UI javascript library.
jquery-MIT-LICENSE.txt: jQuery license.
jquery.lazyload.min.js: LazyLoad javascript library.
rain.tpl.class.php : RainTPL templating library.
├── awesomplete.*: tags autocompletion library
├── blazy.*: picture wall lazy image loading library
├── shaarli.css, reset.css : Shaarli stylesheet.
├── qr.* : qr code generation library
└──rain.tpl.class.php : RainTPL templating library.
tpl/ : RainTPL templates for Shaarli. They are used to build the pages.
images/ : Images and icons used in Shaarli.
data/ : Directory where data is stored (bookmark database, configuration, logs, banlist…)
config.php : Shaarli configuration (login, password, timezone, title…)
datastore.php : Your link database (compressed).
ipban.php : IP address ban system data.
lastupdatecheck.txt : Update check timestamp file (used to check every 24 hours if a new version of Shaarli is available).
log.txt : login/IPban log.
├── config.php : Shaarli configuration (login, password, timezone, title…)
├── datastore.php : Your link database (compressed).
├── ipban.php : IP address ban system data.
├── lastupdatecheck.txt : Update check timestamp file (used to check every 24 hours if a new version of Shaarli is available).
└──log.txt : login/IPban log.
cache/ : Directory containing the thumbnails cache. This directory is automatically created. You can erase it anytime you want.
tmp/ : Temporary directory for compiled RainTPL templates. This directory is automatically created. You can erase it anytime you want.
```
### Development
* [Contributing to Shaarli](https://github.com/shaarli/Shaarli/tree/master/CONTRIBUTING.md)
* [Running unit tests](Running-unit-tests)
* Patches should try to stick to the [PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), especially:
* [PSR-1](http://www.php-fig.org/psr/psr-1/) - Basic Coding Standard
* [PSR-2](http://www.php-fig.org/psr/psr-2/) - Coding Style Guide
### Why not use a real database ? Files are slow !
Does browsing [this page](http://sebsauvage.net/links/) feel slow ? Try browsing older pages, too.
@ -403,10 +444,6 @@ It's not slow at all, is it ? And don't forget the database contains more than 1
The data file is only 3.7 Mb. It's read 99% of the time, and is probably already in the operation system disk cache. So generating a page involves no I/O at all most of the time.
# Wiki - TODO
* Translate (new page can be called Home.fr, Home.es ...) and linked from Home
* translate (new page can be called Home.fr, Home.es ... and linked from Home)
* add more screenshots
* add developer documentation (storage architecture, classes and functions, security handling, ...)
* Contact related projects
* Add a Table of Contents to the wiki (can be added to the sidebar)
...
* add developer documentation (storage architecture, classes and functions, security handling, ...)

26
doc/Ideas-for-plugins.html
View file

@ -1,26 +0,0 @@
<!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></title>
<style type="text/css">code{white-space: pre;}</style>
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link rel="stylesheet" href="github-markdown.css">
</head>
<body>
<p>Please list here ideas for potential plugins. Do not include lengthy discussion about why/how the plugin should work, but link instead to an issue where this would have been discussed.<br />By listing these ideas here, we can keep the issues list a bit more clean, and have a centralized place where people wanting to contribute can find potential enhancement ideas.<br />Also have a look at <a href="https://github.com/shaarli/Shaarli/issues/14">https://github.com/shaarli/Shaarli/issues/14</a> for other suggestions.</p>
<ul>
<li><a href="https://github.com/shaarli/Shaarli/issues/101">Mozilla Social API integration</a><br /></li>
<li><a href="https://github.com/shaarli/Shaarli/issues/58">File sharing/Upload service integration</a><br /></li>
<li><a href="https://github.com/sebsauvage/Shaarli/pull/70">Publish to social media services (twitter, facebook, ...)</a><br /></li>
<li><a href="https://github.com/sebsauvage/Shaarli/issues/170">Comment system</a><br /></li>
<li><a href="https://github.com/sebsauvage/Shaarli/pull/144">Syntax highlighting support</a><br /></li>
<li><a href="https://github.com/sebsauvage/Shaarli/issues/81">Piwik tracking code integration</a><br /></li>
<li><a href="https://github.com/sebsauvage/Shaarli/issues/75">Pingback support</a></li>
</ul>
</body>
</html>

11
doc/Ideas-for-plugins.md
View file

@ -1,11 +0,0 @@
Please list here ideas for potential plugins. Do not include lengthy discussion about why/how the plugin should work, but link instead to an issue where this would have been discussed.
By listing these ideas here, we can keep the issues list a bit more clean, and have a centralized place where people wanting to contribute can find potential enhancement ideas.
Also have a look at https://github.com/shaarli/Shaarli/issues/14 for other suggestions.
* [Mozilla Social API integration](https://github.com/shaarli/Shaarli/issues/101)
* [File sharing/Upload service integration](https://github.com/shaarli/Shaarli/issues/58)
* [Publish to social media services (twitter, facebook, ...)](https://github.com/sebsauvage/Shaarli/pull/70)
* [Comment system](https://github.com/sebsauvage/Shaarli/issues/170)
* [Syntax highlighting support](https://github.com/sebsauvage/Shaarli/pull/144)
* [Piwik tracking code integration](https://github.com/sebsauvage/Shaarli/issues/81)
* [Pingback support](https://github.com/sebsauvage/Shaarli/issues/75)

143
doc/Running-unit-tests.html Normal file
View file

@ -0,0 +1,143 @@
<!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></title>
<style type="text/css">code{white-space: pre;}</style>
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<style type="text/css">
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; }
code > span.dt { color: #902000; }
code > span.dv { color: #40a070; }
code > span.bn { color: #40a070; }
code > span.fl { color: #40a070; }
code > span.ch { color: #4070a0; }
code > span.st { color: #4070a0; }
code > span.co { color: #60a0b0; font-style: italic; }
code > span.ot { color: #007020; }
code > span.al { color: #ff0000; font-weight: bold; }
code > span.fu { color: #06287e; }
code > span.er { color: #ff0000; font-weight: bold; }
</style>
<link rel="stylesheet" href="github-markdown.css">
</head>
<body>
<h3 id="setup-your-environment-for-tests">Setup your environment for tests</h3>
<p>The framework used is <a href="https://phpunit.de/">PHPUnit</a>; it can be installed with <a href="https://getcomposer.org/">Composer</a>, which is a dependency management tool.</p>
<p>Regarding Composer, you can either use:</p>
<ul>
<li>a system-wide version, e.g. installed through your distro's package manager<br /></li>
<li>a local version, downloadable <a href="https://getcomposer.org/download/">here</a></li>
</ul>
<h4 id="sample-usage">Sample usage</h4>
<pre class="sourceCode bash"><code class="sourceCode bash"><span class="co"># system-wide version</span>
$ <span class="kw">composer</span> install
$ <span class="kw">composer</span> update
<span class="co"># local version</span>
$ <span class="kw">php</span> composer.phar self-update
$ <span class="kw">php</span> composer.phar install
$ <span class="kw">php</span> composer.phar update</code></pre>
<h4 id="install-shaarli-dev-dependencies">Install Shaarli dev dependencies</h4>
<pre class="sourceCode bash"><code class="sourceCode bash">$ <span class="kw">cd</span> /path/to/shaarli
$ <span class="kw">composer</span> update</code></pre>
<h4 id="install-and-enable-xdebug-to-generate-phpunit-coverage-reports">Install and enable Xdebug to generate PHPUnit coverage reports</h4>
<p>For Debian-based distros:</p>
<pre class="sourceCode bash"><code class="sourceCode bash">$ <span class="kw">aptitude</span> install php5-xdebug</code></pre>
<p>For ArchLinux:</p>
<pre class="sourceCode bash"><code class="sourceCode bash">$ <span class="kw">pacman</span> -S xdebug</code></pre>
<p>Then add the following line to <code>/etc/php/php.ini</code>:</p>
<pre class="sourceCode ini"><code class="sourceCode ini"><span class="dt">zend_extension</span><span class="ot">=</span><span class="st">xdebug.so</span></code></pre>
<h4 id="run-unit-tests">Run unit tests</h4>
<p>Successful test suite:</p>
<pre class="sourceCode bash"><code class="sourceCode bash">$ <span class="kw">make</span> test
<span class="kw">-------</span>
<span class="kw">PHPUNIT</span>
<span class="kw">-------</span>
<span class="kw">PHPUnit</span> 4.6.9 by Sebastian Bergmann and contributors.
<span class="kw">Configuration</span> read from /home/virtualtam/public_html/shaarli/phpunit.xml
<span class="kw">....................................</span>
<span class="kw">Time</span>: 759 ms, Memory: 8.25Mb
<span class="kw">OK</span> (36 tests, 65 assertions)</code></pre>
<p>Test suite with failures and errors:</p>
<pre class="sourceCode bash"><code class="sourceCode bash">$ <span class="kw">make</span> test
<span class="kw">-------</span>
<span class="kw">PHPUNIT</span>
<span class="kw">-------</span>
<span class="kw">PHPUnit</span> 4.6.9 by Sebastian Bergmann and contributors.
<span class="kw">Configuration</span> read from /home/virtualtam/public_html/shaarli/phpunit.xml
<span class="kw">E..FF...............................</span>
<span class="kw">Time</span>: 802 ms, Memory: 8.25Mb
<span class="kw">There</span> was 1 error:
<span class="kw">1</span>) <span class="kw">LinkDBTest</span>::testConstructLoggedIn
<span class="kw">Missing</span> argument 2 for LinkDB::__construct(), <span class="kw">called</span> in /home/virtualtam/public_html/shaarli/tests/Link\
<span class="kw">DBTest.php</span> on line 79 and defined
<span class="kw">/home/virtualtam/public_html/shaarli/application</span>/LinkDB.php:<span class="kw">58</span>
<span class="kw">/home/virtualtam/public_html/shaarli/tests</span>/LinkDBTest.php:<span class="kw">79</span>
<span class="kw">--</span>
<span class="kw">There</span> were 2 failures:
<span class="kw">1</span>) <span class="kw">LinkDBTest</span>::testCheckDBNew
<span class="kw">Failed</span> asserting that two strings are equal.
<span class="kw">---</span> Expected
<span class="kw">+++</span> Actual
<span class="kw">@@</span> @@
<span class="kw">-</span><span class="st">&#39;e3edea8ea7bb50be4bcb404df53fbb4546a7156e&#39;</span>
<span class="kw">+</span><span class="st">&#39;85eab0c610d4f68025f6ed6e6b6b5fabd4b55834&#39;</span>
<span class="kw">/home/virtualtam/public_html/shaarli/tests</span>/LinkDBTest.php:<span class="kw">121</span>
<span class="kw">2</span>) <span class="kw">LinkDBTest</span>::testCheckDBLoad
<span class="kw">Failed</span> asserting that two strings are equal.
<span class="kw">---</span> Expected
<span class="kw">+++</span> Actual
<span class="kw">@@</span> @@
<span class="kw">-</span><span class="st">&#39;e3edea8ea7bb50be4bcb404df53fbb4546a7156e&#39;</span>
<span class="kw">+</span><span class="st">&#39;85eab0c610d4f68025f6ed6e6b6b5fabd4b55834&#39;</span>
<span class="kw">/home/virtualtam/public_html/shaarli/tests</span>/LinkDBTest.php:<span class="kw">133</span>
<span class="kw">FAILURES</span>!
<span class="kw">Tests</span>: 36, Assertions: 63, Errors: 1, Failures: 2.</code></pre>
<h4 id="test-results-and-coverage">Test results and coverage</h4>
<p>By default, PHPUnit will run all suitable tests found under the <code>tests</code> directory.</p>
<p>Each test has 3 possible outcomes:</p>
<ul>
<li><code>.</code> - success<br /></li>
<li><code>F</code> - failure: the test was run but its results are invalid<br /></li>
<li>the code does not behave as expected<br /></li>
<li>dependencies to external elements: globals, session, cache...<br /></li>
<li><code>E</code> - error: something went wrong and the tested code has crashed<br /></li>
<li>typos in the code, or in the test code<br /></li>
<li>dependencies to missing external elements</li>
</ul>
<p>If Xdebug has been installed and activated, two coverage reports will be generated:</p>
<ul>
<li>a summary in the console<br /></li>
<li>a detailed HTML report with metrics for tested code<br /></li>
<li>to open it in a web browser: <code>firefox coverage/index.html &amp;</code></li>
</ul>
</body>
</html>

127
doc/Running-unit-tests.md Normal file
View file

@ -0,0 +1,127 @@
### Setup your environment for tests
The framework used is [PHPUnit](https://phpunit.de/); it can be installed with [Composer](https://getcomposer.org/), which is a dependency management tool.
Regarding Composer, you can either use:
* a system-wide version, e.g. installed through your distro's package manager
* a local version, downloadable [here](https://getcomposer.org/download/)
#### Sample usage
```bash
# system-wide version
$ composer install
$ composer update
# local version
$ php composer.phar self-update
$ php composer.phar install
$ php composer.phar update
```
#### Install Shaarli dev dependencies
```bash
$ cd /path/to/shaarli
$ composer update
```
#### Install and enable Xdebug to generate PHPUnit coverage reports
For Debian-based distros:
```bash
$ aptitude install php5-xdebug
```
For ArchLinux:
```bash
$ pacman -S xdebug
```
Then add the following line to `/etc/php/php.ini`:
```ini
zend_extension=xdebug.so
```
#### Run unit tests
Successful test suite:
```bash
$ make test
-------
PHPUNIT
-------
PHPUnit 4.6.9 by Sebastian Bergmann and contributors.
Configuration read from /home/virtualtam/public_html/shaarli/phpunit.xml
....................................
Time: 759 ms, Memory: 8.25Mb
OK (36 tests, 65 assertions)
```
Test suite with failures and errors:
```bash
$ make test
-------
PHPUNIT
-------
PHPUnit 4.6.9 by Sebastian Bergmann and contributors.
Configuration read from /home/virtualtam/public_html/shaarli/phpunit.xml
E..FF...............................
Time: 802 ms, Memory: 8.25Mb
There was 1 error:
1) LinkDBTest::testConstructLoggedIn
Missing argument 2 for LinkDB::__construct(), called in /home/virtualtam/public_html/shaarli/tests/Link\
DBTest.php on line 79 and defined
/home/virtualtam/public_html/shaarli/application/LinkDB.php:58
/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:79
--
There were 2 failures:
1) LinkDBTest::testCheckDBNew
Failed asserting that two strings are equal.
--- Expected
+++ Actual
@@ @@
-'e3edea8ea7bb50be4bcb404df53fbb4546a7156e'
+'85eab0c610d4f68025f6ed6e6b6b5fabd4b55834'
/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:121
2) LinkDBTest::testCheckDBLoad
Failed asserting that two strings are equal.
--- Expected
+++ Actual
@@ @@
-'e3edea8ea7bb50be4bcb404df53fbb4546a7156e'
+'85eab0c610d4f68025f6ed6e6b6b5fabd4b55834'
/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:133
FAILURES!
Tests: 36, Assertions: 63, Errors: 1, Failures: 2.
```
#### Test results and coverage
By default, PHPUnit will run all suitable tests found under the `tests` directory.
Each test has 3 possible outcomes:
* `.` - success
* `F` - failure: the test was run but its results are invalid
* the code does not behave as expected
* dependencies to external elements: globals, session, cache...
* `E` - error: something went wrong and the tested code has crashed
* typos in the code, or in the test code
* dependencies to missing external elements
If Xdebug has been installed and activated, two coverage reports will be generated:
* a summary in the console
* a detailed HTML report with metrics for tested code
* to open it in a web browser: `firefox coverage/index.html &`

70
doc/_Sidebar.html
View file

@ -1,70 +0,0 @@
<!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></title>
<style type="text/css">code{white-space: pre;}</style>
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link rel="stylesheet" href="github-markdown.css">
</head>
<body>
<ul>
<li><p><a href="#basic-usage">Basic Usage</a></p>
<ul>
<li><a href="#add-the-sharing-button-_bookmarklet_-to-your-browser">Add the sharing button (<em>bookmarklet</em>) to your browser</a><br /></li>
<li><a href="#share-links-using-the-_bookmarklet_">Share links using the <em>bookmarklet</em></a><br /></li>
</ul></li>
<li><p><a href="#other-usage-examples">Other usage examples</a></p>
<ul>
<li><a href="#using-shaarli-as-a-blog-notepad-pastebin">Using Shaarli as a blog, notepad, pastebin...</a><br /></li>
<li><a href="#rss-feeds-or-picture-wall-for-a-specific-searchtag">RSS Feeds or Picture Wall for a specific search/tag</a><br /></li>
</ul></li>
<li><p><a href="#configuration">Configuration</a></p>
<ul>
<li><a href="#main-dataoptionsphp-file">Main data/options.php file</a><br /></li>
<li><a href="#changing-theme">Changing theme</a><br /></li>
</ul></li>
<li><a href="#backup">Backup</a><br /></li>
<li><p><a href="#login-bruteforce-protection">Login bruteforce protection</a></p>
<ul>
<li><a href="#list-of-all-login-attempts">List of all login attempts</a><br /></li>
</ul></li>
<li><p><a href="#troubleshooting">Troubleshooting</a></p>
<ul>
<li><a href="#i-forgot-my-password-">I forgot my password !</a><br /></li>
<li><a href="#exporting-from-diigo">Exporting from Diigo</a><br /></li>
<li><a href="#importing-from-semanticscuttle">Importing from SemanticScuttle</a><br /></li>
<li><a href="#importing-from-mister-wong">Importing from Mister Wong</a><br /></li>
<li><a href="#hosting-problems">Hosting problems</a><br /></li>
<li><a href="#dates-are-not-properly-formatted">Dates are not properly formatted</a><br /></li>
<li><a href="#problems-on-centos-servers">Problems on CentOS servers</a><br /></li>
<li><a href="#my-session-expires--i-cant-stay-logged-in">My session expires ! I can't stay logged in</a><br /></li>
<li><a href="#sessions-do-not-seem-to-work-correctly-on-your-server"><code>Sessions do not seem to work correctly on your server</code></a><br /></li>
<li><a href="#pubsubhubbub-support">pubsubhubbub support</a><br /></li>
</ul></li>
<li><p><a href="#notes">Notes</a></p>
<ul>
<li><a href="#various-hacks">Various hacks</a><br /></li>
<li><a href="#changing-timestamp-for-a-link">Changing timestamp for a link</a><br /></li>
</ul></li>
<li><a href="#related-software">Related software</a><br /></li>
<li><a href="#other-links">Other links</a><br /></li>
<li><p><a href="#faq">FAQ</a></p>
<ul>
<li><a href="#why-did-you-create-shaarli-">Why did you create Shaarli ?</a><br /></li>
<li><a href="#why-use-shaarli-and-not-deliciousdiigo-">Why use Shaarli and not Delicious/Diigo ?</a><br /></li>
<li><a href="#what-does-shaarli-mean-">What does Shaarli mean ?</a><br /></li>
</ul></li>
<li><p><a href="#technical-details">Technical details</a></p>
<ul>
<li><a href="#directory-structure">Directory structure</a><br /></li>
<li><a href="#why-not-use-a-real-database--files-are-slow-">Why not use a real database ? Files are slow !</a><br /></li>
</ul></li>
<li><p><a href="#wiki---todo">Wiki - TODO</a></p></li>
</ul>
</body>
</html>

37
doc/_Sidebar.md
View file

@ -1,37 +0,0 @@
- [Basic Usage](#basic-usage)
- [Add the sharing button (_bookmarklet_) to your browser](#add-the-sharing-button-_bookmarklet_-to-your-browser)
- [Share links using the _bookmarklet_](#share-links-using-the-_bookmarklet_)
- [Other usage examples](#other-usage-examples)
- [Using Shaarli as a blog, notepad, pastebin...](#using-shaarli-as-a-blog-notepad-pastebin)
- [RSS Feeds or Picture Wall for a specific search/tag](#rss-feeds-or-picture-wall-for-a-specific-searchtag)
- [Configuration](#configuration)
- [Main data/options.php file](#main-dataoptionsphp-file)
- [Changing theme](#changing-theme)
- [Backup](#backup)
- [Login bruteforce protection](#login-bruteforce-protection)
- [List of all login attempts](#list-of-all-login-attempts)
- [Troubleshooting](#troubleshooting)
- [I forgot my password !](#i-forgot-my-password-)
- [Exporting from Diigo](#exporting-from-diigo)
- [Importing from SemanticScuttle](#importing-from-semanticscuttle)
- [Importing from Mister Wong](#importing-from-mister-wong)
- [Hosting problems](#hosting-problems)
- [Dates are not properly formatted](#dates-are-not-properly-formatted)
- [Problems on CentOS servers](#problems-on-centos-servers)
- [My session expires ! I can't stay logged in](#my-session-expires--i-cant-stay-logged-in)
- [`Sessions do not seem to work correctly on your server`](#sessions-do-not-seem-to-work-correctly-on-your-server)
- [pubsubhubbub support](#pubsubhubbub-support)
- [Notes](#notes)
- [Various hacks](#various-hacks)
- [Changing timestamp for a link](#changing-timestamp-for-a-link)
- [Related software](#related-software)
- [Other links](#other-links)
- [FAQ](#faq)
- [Why did you create Shaarli ?](#why-did-you-create-shaarli-)
- [Why use Shaarli and not Delicious/Diigo ?](#why-use-shaarli-and-not-deliciousdiigo-)
- [What does Shaarli mean ?](#what-does-shaarli-mean-)
- [Technical details](#technical-details)
- [Directory structure](#directory-structure)
- [Why not use a real database ? Files are slow !](#why-not-use-a-real-database--files-are-slow-)
- [Wiki - TODO](#wiki---todo)

BIN
doc/images/firefoxshare.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 757 B