From da9b0e3e807f05831c00b2f02a16b76eafbb6743 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Fri, 26 Jun 2015 21:56:43 +0200 Subject: [doc] sync doc with latest wiki, build HTML --- doc/Home.html | 137 ++++++++++++++++++++++++++++-------------- doc/Home.md | 125 ++++++++++++++++++++++++-------------- doc/Ideas-for-plugins.html | 26 -------- doc/Ideas-for-plugins.md | 11 ---- doc/Running-unit-tests.html | 143 ++++++++++++++++++++++++++++++++++++++++++++ doc/Running-unit-tests.md | 127 +++++++++++++++++++++++++++++++++++++++ doc/_Sidebar.html | 70 ---------------------- doc/_Sidebar.md | 37 ------------ doc/images/firefoxshare.png | Bin 0 -> 757 bytes 9 files changed, 443 insertions(+), 233 deletions(-) delete mode 100644 doc/Ideas-for-plugins.html delete mode 100644 doc/Ideas-for-plugins.md create mode 100644 doc/Running-unit-tests.html create mode 100644 doc/Running-unit-tests.md delete mode 100644 doc/_Sidebar.html delete mode 100644 doc/_Sidebar.md create mode 100644 doc/images/firefoxshare.png (limited to 'doc') diff --git a/doc/Home.html b/doc/Home.html index e4d117f1..2cb54c86 100644 --- a/doc/Home.html +++ b/doc/Home.html @@ -14,8 +14,7 @@

Shaarli wiki

Welcome to the 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.

If you have any questions or ideas, please join the chat (also reachable via IRC), post them in our general discussion or read the current issues. If you've found a bug, please create a new issue.

If you'd like a feature added, see if it fits in the list of Ideas for Plugins and update the corresponding bug report.

If you have any questions or ideas, please join the chat (also reachable via IRC), post them in our general discussion or read the current issues. If you've found a bug, please create a new issue. If you would like a feature added to Shaarli, check the issues labeled feature, enhancement, and plugin.

Note: This documentation is available online at https://github.com/shaarli/Shaarli/wiki, and locally in the doc/ directory of your Shaarli installation.

@@ -25,7 +24,9 @@

Basic Usage

Add the sharing button (bookmarklet) to your browser
Add Shaarli as a sharing service to Firefox
Share links using the bookmarklet
Sharing links using Firefox share

Other usage examples

Various hacks
Changing timestamp for a link

Related software

Server apps
Android apps
Themes & templates
Integrate Shaarli with other platforms
Alternative to Shaarli

Other usage examples

Shaarli can be used:

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

Configuration

Main data/options.php file

To change the configuration, create the file data/options.php, example:

@@ -153,10 +174,10 @@

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

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

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.

@@ -164,7 +185,8 @@

ENABLE_UPDATECHECK: Determines whether Shaarli check for new releases at https://github.com/shaarli/Shaarli

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

Download CSS styles for shaarlis listed in an opml file

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.
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/options.php to have Shaarli use this template. Eg.

$GLOBALS['config']['RAINTPL_TPL'] = 'tpl/my-template/' ;

You can find a list of compatible templates in Related Software

Backup

You have two ways of backing up your database:

Example patch: add a new "via" field for links
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?)

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)));
+echo "<pre>"; // Pretty printing is love, pretty printing is life
+print_r($out);
+echo "</pre>";
+exit;

This will output the internal representation of the datastore, "unobfuscated" (if this can really be considered obfuscation)

Changing timestamp for a link

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.

$data = "tZNdb9MwFIb... <Commented content inside datastore.php>";
-$out = unserialize(gzinflate(base64_decode($data)));
-echo "<pre>"; // Pretty printing is love, pretty printing is life
-print_r($out);
-echo "</pre>";
-exit;

This will output the internal representation of the datastore, "unobfuscated" (if this can really be considered obfuscation)

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 - Archive your Shaarli bookmarks and their content
shaarli-river - An aggregator for shaarlis with many features
Shaarlo - An aggregator for shaarlis with many features (a very popular running instance among french shaarliers: shaarli.fr)
Shaarlimages - An image-oriented aggregator for Shaarlis
mknexen/shaarli-api - A REST API for Shaarli

Android apps

Shaarli for Android - Android application that adds Shaarli as a sharing provider
Shaarlier for Android - Android application to simply add links directly into your Shaarli
shaarli-river - an aggregator for shaarlis with many features
Shaarlo - an aggregator for shaarlis with many features (Demo)
Shaarlier for Android - Android application to simply add links directly into your Shaarli

Themes & templates

AkibaTech/Shaarli Superhero Theme - A template/theme for Shaarli
alexisju/albinomouse-template - A full template for Shaarli
dhoko/ShaarliTemplate - A template/theme for Shaarli
kalvn/shaarli-blocks - A template/theme for Shaarli
kalvn/Shaarli-Material -
A theme (template) based on Google's Material Design for Shaarli, the superfast delicious clone.
kalvn/Shaarli-Material - A theme (template) based on Google's Material Design for Shaarli, the superfast delicious clone.
misterair/Limonade - A fork of (legacy) Shaarli with a new template
Vinm/Blue-theme-for Shaarli - A template/theme for Shaarli (unmaintained, compatibility unknown)
vivienhaese/shaarlitheme - A Shaarli fork meant to be run in an openshift instance
vivienhaese/shaarlitheme - A Shaarli fork meant to be run in an openshift instance

Integrate Shaarli with other platforms

tt-rss-shaarli - TinyTiny RSS plugin that adds support for sharing articles with Shaarli
dhoko/ShaarliTemplate - A template/theme for Shaarli
mknexen/shaarli-api - a REST API for Shaarli
Albinomouse - A full template for Shaarli
Shaarlimages - An image-oriented aggregator for Shaarlis
Shaarli Superhero Theme - A template/theme for Shaarli
Limonade - A fork of Shaarli with a new template
octopress-shaarli - octoprress plugin to retrieve SHaarli links on the sidebara
octopress-shaarli - octoprress plugin to retrieve SHaarli links on the sidebara

Alternative to Shaarli

Bookie - Another self-hostable, Free bookmark sharing software, written in Python
Unmark - An open source to do app for bookmarks (Homepage)

Directory structure

Here is the directory structure of Shaarli and the purpose of the different files:

    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
Running unit tests
Patches should try to stick to the PHP Standard Recommendations (PSR), especially:
PSR-1 - Basic Coding Standard
PSR-2 - Coding Style Guide

Why not use a real database ? Files are slow !

Does browsing this page feel slow ? Try browsing older pages, too.

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 ?

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, ...)

...

"; $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 `` 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) - -... \ No newline at end of file + * add developer documentation (storage architecture, classes and functions, security handling, ...) \ No newline at end of file diff --git a/doc/Ideas-for-plugins.html b/doc/Ideas-for-plugins.html deleted file mode 100644 index 8ca3572c..00000000 --- a/doc/Ideas-for-plugins.html +++ /dev/null @@ -1,26 +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.

- - diff --git a/doc/Ideas-for-plugins.md b/doc/Ideas-for-plugins.md deleted file mode 100644 index 9c3ffb07..00000000 --- a/doc/Ideas-for-plugins.md +++ /dev/null @@ -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) \ No newline at end of file diff --git a/doc/Running-unit-tests.html b/doc/Running-unit-tests.html new file mode 100644 index 00000000..43423bc7 --- /dev/null +++ b/doc/Running-unit-tests.html @@ -0,0 +1,143 @@ + + + + + + + + + + + + + +

Setup your environment for tests

The framework used is PHPUnit; it can be installed with Composer, 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

Sample usage

# 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

$ cd /path/to/shaarli
+$ composer update

Install and enable Xdebug to generate PHPUnit coverage reports

For Debian-based distros:

$ aptitude install php5-xdebug

For ArchLinux:

$ pacman -S xdebug

Then add the following line to /etc/php/php.ini:

zend_extension=xdebug.so

Run unit tests

Successful test suite:

$ 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:

$ 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 &

+ + diff --git a/doc/Running-unit-tests.md b/doc/Running-unit-tests.md new file mode 100644 index 00000000..94e99591 --- /dev/null +++ b/doc/Running-unit-tests.md @@ -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 &` \ No newline at end of file diff --git a/doc/_Sidebar.html b/doc/_Sidebar.html deleted file mode 100644 index b9e2ed39..00000000 --- a/doc/_Sidebar.html +++ /dev/null @@ -1,70 +0,0 @@ - - - - - - - - - - - - -

Basic Usage
-
- Add the sharing button (bookmarklet) to your browser
- Share links using the bookmarklet
Other usage examples
-
- Using Shaarli as a blog, notepad, pastebin...
- RSS Feeds or Picture Wall for a specific search/tag
Configuration
-
- Main data/options.php file
- Changing theme
Backup
Login bruteforce protection
-
- List of all login attempts
Troubleshooting
-
Notes
-
- Various hacks
- Changing timestamp for a link
Related software
Other links
FAQ
-
Technical details
-
- Directory structure
- Why not use a real database ? Files are slow !
Wiki - TODO

- - diff --git a/doc/_Sidebar.md b/doc/_Sidebar.md deleted file mode 100644 index dbe145f1..00000000 --- a/doc/_Sidebar.md +++ /dev/null @@ -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) \ No newline at end of file diff --git a/doc/images/firefoxshare.png b/doc/images/firefoxshare.png new file mode 100644 index 00000000..98c2fdd3 Binary files /dev/null and b/doc/images/firefoxshare.png differ -- cgit v1.2.3

Shaarli wiki

Add Shaarli as a sharing service to Firefox

Share links using the bookmarklet

Sharing links using Firefox share

Other usage examples

Configuration

Main data/options.php file

Changing theme

Changing template

Backup

Changing timestamp for a link

Related software

Server apps

Android apps

Themes & templates

Integrate Shaarli with other platforms

Alternative to Shaarli

Directory structure

Development

Why not use a real database ? Files are slow !

Wiki - TODO

Setup your environment for tests

Sample usage

Install Shaarli dev dependencies

Install and enable Xdebug to generate PHPUnit coverage reports

Run unit tests

Test results and coverage