"; // Pretty printing is love, pretty printing is life +print_r($out); +echo ""; +exit; +``` +This will output the internal representation of the datastore, "unobfuscated" (if this can really be considered obfuscation). + +### Changing the 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`. diff --git a/doc/Development.html b/doc/Development.html new file mode 100644 index 00000000..1e33eff4 --- /dev/null +++ b/doc/Development.html @@ -0,0 +1,102 @@ + + + + + + +
Development
+Guidelines
+Please have a look at the following pages:
+-
+
- Contributing to Shaarli +
- Static analysis - patches should try to stick to the PHP Standard Recommendations (PSR), especially: + +
- Unit tests +
- GnuPG signature for tags/releases +
Continuous integration tools
+Local development
+A Makefile is available to perform project-related operations:
-
+
- Documentation - generate a local HTML copy of the GitHub wiki +
- Static analysis - check that the code is compliant to PHP conventions +
- Unit tests - ensure there are no regressions introduced by new commits +
Automatic builds
+Travis CI is a Continuous Integration build server, that runs a build:
+-
+
- each time a commit is merged to the mainline (
masterbranch)
+ - each time a Pull Request is submitted or updated +
A build is composed of several jobs: one for each supported PHP version (see Server requirements).
+Each build job:
+-
+
- updates Composer +
- installs 3rd-party test dependencies with Composer +
- runs Unit tests +
After all jobs have finished, Travis returns the results to GitHub:
+-
+
- a status icon represents the result for the
masterbranch:
+ - Pull Requests are updated with the Travis result
+
-
+
- Green: all tests have passed +
- Red: some tests failed +
- Orange: tests are pending +
+
](https://travis-ci.org/shaarli/Shaarli).html)
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/ # static assets and 3rd party libraries
+ ├── 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/ # data storage: 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
+ └──log.txt # login/IPban log.
+ cache/ # 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.Download CSS styles for shaarlis listed in an opml file
-Example php script:
-<!---- ?php -->
-<!---- Copyright (c) 2014 Nicolas Delsaux (https://github.com/Riduidel) -->
-<!---- License: zlib (http://www.gzip.org/zlib/zlib_license.html) -->
-
-/**
- * Source: https://github.com/Riduidel
- * Download css styles for shaarlis listed in an opml file
- */
-define("SHAARLI_RSS_OPML", "https://www.ecirtam.net/shaarlirss/custom/people.opml");
-
-define("THEMES_TEMP_FOLDER", "new_themes");
-
-if(!file_exists(THEMES_TEMP_FOLDER)) {
- mkdir(THEMES_TEMP_FOLDER);
-}
-
-function siteUrl($pathInSite) {
- $indexPos = strpos($pathInSite, "index.php");
- if(!$indexPos) {
- return $pathInSite;
- } else {
- return substr($pathInSite, 0, $indexPos);
- }
-}
-
-function createShaarliHashFromOPMLL($opmlFile) {
- $result = array();
- $opml = file_get_contents($opmlFile);
- $opmlXml = simplexml_load_string($opml);
- $outlineElements = $opmlXml->xpath("body/outline");
- foreach($outlineElements as $site) {
- $siteUrl = siteUrl((string) $site['htmlUrl']);
- $result[$siteUrl]=((string) $site['text']);
- }
- return $result;
-}
-
-function getSiteFolder($url) {
- $domain = parse_url($url, PHP_URL_HOST);
- return THEMES_TEMP_FOLDER."/".str_replace(".", "_", $domain);
-}
-
-function get_http_response_code($theURL) {
- $headers = get_headers($theURL);
- return substr($headers[0], 9, 3);
-}
-
-/**
- * This makes the code PHP-5 only (particularly the call to "get_headers")
- */
-function copyUserStyleFrom($url, $name, $knownStyles) {
- $userStyle = $url."inc/user.css";
- if(in_array($url, $knownStyles)) {
- // TODO add log message
- } else {
- $statusCode = get_http_response_code($userStyle);
- if(intval($statusCode)<300) {
- $styleSheet = file_get_contents($userStyle);
- $siteFolder = getSiteFolder($url);
- if(!file_exists($siteFolder)) {
- mkdir($siteFolder);
- }
- if(!file_exists($siteFolder.'/user.css')) {
- // Copy stylesheet
- file_put_contents($siteFolder.'/user.css', $styleSheet);
- }
- if(!file_exists($siteFolder.'/README.md')) {
- // Then write a readme.md file
- file_put_contents($siteFolder.'/README.md',
- "User style from ".$name."\n"
- ."============================="
- ."\n\n"
- ."This stylesheet was downloaded from ".$userStyle." on ".date(DATE_RFC822)
- );
- }
- if(!file_exists($siteFolder.'/config.ini')) {
- // Write a config file containing useful informations
- file_put_contents($siteFolder.'/config.ini',
- "site_url=".$url."\n"
- ."site_name=".$name."\n"
- );
- }
- if(!file_exists($siteFolder.'/home.png')) {
- // And finally copy generated thumbnail
- $homeThumb = $siteFolder.'/home.png';
- file_put_contents($siteFolder.'/home.png', file_get_contents(getThumbnailUrl($url)));
- }
- echo 'Theme have been downloaded from <a href="'.$url.'">'.$url.'</a> into '.$siteFolder
- .'. It looks like <img src="'.$homeThumb.'"><br/>';
- }
- }
-}
-
-function getThumbnailUrl($url) {
- return 'http://api.webthumbnail.org/?url='.$url;
-}
-
-function copyUserStylesFrom($urlToNames, $knownStyles) {
- foreach($urlToNames as $url => $name) {
- copyUserStyleFrom($url, $name, $knownStyles);
- }
-}
-
-/**
- * Reading directory list, courtesy of http://www.laughing-buddha.net/php/dirlist/
- * @param directory the directory we want to list files of
- * @return a simple array containing the list of absolute file paths. Notice that current file (".") and parent one("..")
- * are not listed here
- */
-function getDirectoryList ($directory) {
- $realPath = realpath($directory);
- // create an array to hold directory list
- $results = array();
- // create a handler for the directory
- $handler = opendir($directory);
- // open directory and walk through the filenames
- while ($file = readdir($handler)) {
- // if file isn't this directory or its parent, add it to the results
- if ($file != "." && $file != "..") {
- $results[] = realpath($realPath . "/" . $file);
- }
- }
- // tidy up: close the handler
- closedir($handler);
- // done!
- return $results;
-}
-
-/**
- * Start in themes folder and look in all subfolders for config.ini files.
- * These config.ini files allow us not to download styles again and again
- */
-function findKnownStyles() {
- $result = array();
- $subFolders = getDirectoryList("themes");
- foreach($subFolders as $folder) {
- $configFile = $folder."/config.ini";
- if(file_exists($configFile)) {
- $iniParameters = parse_ini_file($configFile);
- array_push($result, $iniParameters['site_url']);
- }
- }
- return $result;
-}
-
-$knownStyles = findKnownStyles();
-copyUserStylesFrom(createShaarliHashFromOPMLL(SHAARLI_RSS_OPML), $knownStyles);
-
-<!--- ? ---->Download CSS styles from an OPML list
+Download CSS styles for shaarlis listed in an opml file
+Example php script:
+<!---- ?php -->
+<!---- Copyright (c) 2014 Nicolas Delsaux (https://github.com/Riduidel) -->
+<!---- License: zlib (http://www.gzip.org/zlib/zlib_license.html) -->
+
+/**
+ * Source: https://github.com/Riduidel
+ * Download css styles for shaarlis listed in an opml file
+ */
+define("SHAARLI_RSS_OPML", "https://www.ecirtam.net/shaarlirss/custom/people.opml");
+
+define("THEMES_TEMP_FOLDER", "new_themes");
+
+if(!file_exists(THEMES_TEMP_FOLDER)) {
+ mkdir(THEMES_TEMP_FOLDER);
+}
+
+function siteUrl($pathInSite) {
+ $indexPos = strpos($pathInSite, "index.php");
+ if(!$indexPos) {
+ return $pathInSite;
+ } else {
+ return substr($pathInSite, 0, $indexPos);
+ }
+}
+
+function createShaarliHashFromOPMLL($opmlFile) {
+ $result = array();
+ $opml = file_get_contents($opmlFile);
+ $opmlXml = simplexml_load_string($opml);
+ $outlineElements = $opmlXml->xpath("body/outline");
+ foreach($outlineElements as $site) {
+ $siteUrl = siteUrl((string) $site['htmlUrl']);[](.html)
+ $result[$siteUrl]=((string) $site['text']);[](.html)
+ }
+ return $result;
+}
+
+function getSiteFolder($url) {
+ $domain = parse_url($url, PHP_URL_HOST);
+ return THEMES_TEMP_FOLDER."/".str_replace(".", "_", $domain);
+}
+
+function get_http_response_code($theURL) {
+ $headers = get_headers($theURL);
+ return substr($headers[0], 9, 3);[](.html)
+}
+
+/**
+ * This makes the code PHP-5 only (particularly the call to "get_headers")
+ */
+function copyUserStyleFrom($url, $name, $knownStyles) {
+ $userStyle = $url."inc/user.css";
+ if(in_array($url, $knownStyles)) {
+ // TODO add log message
+ } else {
+ $statusCode = get_http_response_code($userStyle);
+ if(intval($statusCode)<300) {
+ $styleSheet = file_get_contents($userStyle);
+ $siteFolder = getSiteFolder($url);
+ if(!file_exists($siteFolder)) {
+ mkdir($siteFolder);
+ }
+ if(!file_exists($siteFolder.'/user.css')) {
+ // Copy stylesheet
+ file_put_contents($siteFolder.'/user.css', $styleSheet);
+ }
+ if(!file_exists($siteFolder.'/README.md')) {
+ // Then write a readme.md file
+ file_put_contents($siteFolder.'/README.md',
+ "User style from ".$name."\n"
+ ."============================="
+ ."\n\n"
+ ."This stylesheet was downloaded from ".$userStyle." on ".date(DATE_RFC822)
+ );
+ }
+ if(!file_exists($siteFolder.'/config.ini')) {
+ // Write a config file containing useful informations
+ file_put_contents($siteFolder.'/config.ini',
+ "site_url=".$url."\n"
+ ."site_name=".$name."\n"
+ );
+ }
+ if(!file_exists($siteFolder.'/home.png')) {
+ // And finally copy generated thumbnail
+ $homeThumb = $siteFolder.'/home.png';
+ file_put_contents($siteFolder.'/home.png', file_get_contents(getThumbnailUrl($url)));
+ }
+ echo 'Theme have been downloaded from <a href="'.$url.'">'.$url.'</a> into '.$siteFolder
+ .'. It looks like <img src="'.$homeThumb.'"><br/>';
+ }
+ }
+}
+
+function getThumbnailUrl($url) {
+ return 'http://api.webthumbnail.org/?url='.$url;
+}
+
+function copyUserStylesFrom($urlToNames, $knownStyles) {
+ foreach($urlToNames as $url => $name) {
+ copyUserStyleFrom($url, $name, $knownStyles);
+ }
+}
+
+/**
+ * Reading directory list, courtesy of http://www.laughing-buddha.net/php/dirlist/
+ * @param directory the directory we want to list files of
+ * @return a simple array containing the list of absolute file paths. Notice that current file (".") and parent one("..")
+ * are not listed here
+ */
+function getDirectoryList ($directory) {
+ $realPath = realpath($directory);
+ // create an array to hold directory list
+ $results = array();
+ // create a handler for the directory
+ $handler = opendir($directory);
+ // open directory and walk through the filenames
+ while ($file = readdir($handler)) {
+ // if file isn't this directory or its parent, add it to the results
+ if ($file != "." && $file != "..") {
+ $results[ = realpath($realPath . "/" . $file);](-=-realpath($realPath-.-"/"-.-$file);.html)
+ }
+ }
+ // tidy up: close the handler
+ closedir($handler);
+ // done!
+ return $results;
+}
+
+/**
+ * Start in themes folder and look in all subfolders for config.ini files.
+ * These config.ini files allow us not to download styles again and again
+ */
+function findKnownStyles() {
+ $result = array();
+ $subFolders = getDirectoryList("themes");
+ foreach($subFolders as $folder) {
+ $configFile = $folder."/config.ini";
+ if(file_exists($configFile)) {
+ $iniParameters = parse_ini_file($configFile);
+ array_push($result, $iniParameters['site_url']);[](.html)
+ }
+ }
+ return $result;
+}
+
+$knownStyles = findKnownStyles();
+copyUserStylesFrom(createShaarliHashFromOPMLL(SHAARLI_RSS_OPML), $knownStyles);
+
+<!--- ? ---->Tags
+ Origine
- {if condition="($link_is_new && $GLOBALS['privateLinkByDefault']==true) || $link.private == true"} + {if condition="($link_is_new && $GLOBALS['privateLinkByDefault']==true) || $link.private == true"}[](.html)
diff --git a/tpl/linklist.html b/tpl/linklist.html @@ -181,9 +182,9 @@ index ddc38cb..0a8475f 100644
{if="$value.description"}
{$value.description}
{/if}
+ {if condition="isset($value.via) && !empty($value.via)"}{/if}
- {if="!$GLOBALS['config']['HIDE_TIMESTAMPS'] || isLoggedIn()"}
+ {if="!$GLOBALS['config'['HIDE_TIMESTAMPS'] || isLoggedIn()"}]('HIDE_TIMESTAMPS']-||-isLoggedIn()"}.html)
{$value.localdate|htmlspecialchars} - permalink -
{else}
--
2.1.1
-```
\ No newline at end of file
+```
diff --git a/doc/FAQ.html b/doc/FAQ.html
new file mode 100644
index 00000000..0ebd1bcf
--- /dev/null
+++ b/doc/FAQ.html
@@ -0,0 +1,97 @@
+
+
+
+
+
+
+ FAQ
+Why did you create Shaarli ?
+I was a StumbleUpon user. Then I got fed up with they big toolbar. I switched to delicious, which was lighter, faster and more beautiful. Until Yahoo bought it. Then the export API broke all the time, delicious became slow and was ditched by Yahoo. I switched to Diigo, which is not bad, but does too much. And Diigo is sslllooooowww and their Firefox extension a bit buggy. And… oh… their Firefox addon sends to Diigo every single URL you visit (Don't believe me ? Use Tamper Data and open any page).
+Enough is enough. Saving simple links should not be a complicated heavy thing. I ditched them all and wrote my own: Shaarli. It's simple, but it does the job and does it well. And my data is not hosted on a foreign server, but on my server.
+Why use Shaarli and not Delicious/Diigo ?
+With Shaarli:
+-
+
- The data is yours: It's hosted on your server. +
- Never fear of having your data locked-in. +
- Never fear to have your data sold to third party. +
- Your private links are not hosted on a third party server. +
- You are not tracked by browser addons (like Diigo does) +
- You can change the look and feel of the pages if you want. +
- You can change the behaviour of the program. +
- It's magnitude faster than most bookmarking services. +
What does Shaarli mean?
+Shaarli is for shaaring your links.
+My Shaarli is broken!
+First of all, ensure that both the web server and Shaarli are correctly configured, and that your installation is supported.
+If everything looks right but the issue(s) remain(s), please:
+-
+
- take a look at the troubleshooting section +
- come chat with us on Gitter, we'll be happy to help ;-) +
- browse active issues and Pull Requests
+
-
+
- if you find one that is related to the issue, feel free to comment and provide additional details (host/Shaarli setup) +
- else, open a new issue, and provide information about the problem:
+
-
+
- what happens? - display glitches, invalid data, security flaws... +
- what is your configuration? - OS, server version, activated extensions, web browser... +
- is it reproducible? +
+
+
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.
+ + diff --git a/doc/FAQ.md b/doc/FAQ.md new file mode 100644 index 00000000..4c69763f --- /dev/null +++ b/doc/FAQ.md @@ -0,0 +1,44 @@ +#FAQ +### Why did you create Shaarli ? + +I was a StumbleUpon user. Then I got fed up with they big toolbar. I switched to delicious, which was lighter, faster and more beautiful. Until Yahoo bought it. Then the export API broke all the time, delicious became slow and was ditched by Yahoo. I switched to Diigo, which is not bad, but does too much. And Diigo is sslllooooowww and their Firefox extension a bit buggy. And… oh… **their Firefox addon sends to Diigo every single URL you visit** (Don't believe me ? Use [Tamper Data](https://addons.mozilla.org/en-US/firefox/addon/tamper-data/) and open any page).[](.html) + +Enough is enough. Saving simple links should not be a complicated heavy thing. I ditched them all and wrote my own: Shaarli. It's simple, but it does the job and does it well. And my data is not hosted on a foreign server, but on my server. + +### Why use Shaarli and not Delicious/Diigo ? + +With Shaarli: + +* The data is yours: It's hosted on your server. +* Never fear of having your data locked-in. +* Never fear to have your data sold to third party. +* Your private links are not hosted on a third party server. +* You are not tracked by browser addons (like Diigo does) +* You can change the look and feel of the pages if you want. +* You can change the behaviour of the program. +* It's magnitude faster than most bookmarking services. + +### What does Shaarli mean? + +Shaarli is for shaaring your links. + +### My Shaarli is broken! +First of all, ensure that both the [web server](Server-configuration) and [Shaarli](Shaarli-configuration) are correctly configured, and that your installation is [supported](Server-requirements).[](.html) + +If everything looks right but the issue(s) remain(s), please: +- take a look at the [troubleshooting](Troubleshooting) section[](.html) +- come [chat with us](https://gitter.im/shaarli/Shaarli) on Gitter, we'll be happy to help ;-)[](.html) +- browse active [issues](https://github.com/shaarli/Shaarli/issues) and [Pull Requests](https://github.com/shaarli/Shaarli/pulls)[](.html) + - if you find one that is related to the issue, feel free to comment and provide additional details (host/Shaarli setup) + - else, [open a new issue](https://github.com/shaarli/Shaarli/issues/new), and provide information about the problem:[](.html) + - _what happens?_ - display glitches, invalid data, security flaws... + - _what is your configuration?_ - OS, server version, activated extensions, web browser... + - _is it reproducible?_ + +### Why not use a real database? Files are slow! + +Does browsing [this page](http://sebsauvage.net/links/) feel slow? Try browsing older pages, too.[](.html) + +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. diff --git a/doc/Firefox-share.html b/doc/Firefox-share.html new file mode 100644 index 00000000..198afe23 --- /dev/null +++ b/doc/Firefox-share.html @@ -0,0 +1,72 @@ + + + + + + +Firefox share
+Add Shaarli as a sharing service to Firefox
+-
+
- Open your Shaarli and
Login
+ - Click the
Toolsbutton in the top bar
+ - Click the
✚Add to Firefox socialbutton and accept the activation.
+
Sharing links using Firefox share
+-
+
- Add the sharing service as described above +
- When you are visiting a webpage you would like to share with Shaarli, click the Firefox Share button images/firefoxshare.png +
- You can edit your link before and after saving, just like the bookmarklet above. +
| | Your Shaarli instance must be hosted on an HTTPS (SSL/TLS secure connection) enabled server for Firefox Share to work. Firefox Share will not work over plain HTTP connections. |
|------|-------------------------------------------------------------------------------|
GnuPG signature
+Introduction
+PGP and GPG
+Gnu Privacy Guard (GnuPG) is an Open Source implementation of the Pretty Good [](.html)
Privacy (OpenPGP) specification. Its main purposes are digital authentication,
signature and encryption.
It is often used by the FLOSS community to verify:
+-
+
- Linux package signatures: Debian SecureApt, ArchLinux Master [](.html)
Keys
+ - SCM releases & maintainer identity +
Trust
+To quote Phil Pennock (the author of the SKS key server - http://sks.spodhuis.org/):
+++You MUST understand that presence of data in the keyserver (pools) in no way connotes trust. Anyone can generate a key, with any name or email address, and upload it. All security and trust comes from evaluating security at the “object level”, via PGP Web-Of-Trust signatures. This keyserver makes it possible to retrieve keys, looking them up via various indices, but the collection of keys in this public pool is KNOWN to contain malicious and fraudulent keys. It is the common expectation of server operators that users understand this and use software which, like all known common OpenPGP implementations, evaluates trust accordingly. This expectation is so common that it is not normally explicitly stated.
+
Trust can be gained by having your key signed by other people (and signing their key back, too :) ), for instance during key signing parties, see:
+ +Generate a GPG key
+See Generating a GPG key for Git tagging.
+gpg - provide identity information
+$ gpg --gen-key
+
+gpg (GnuPG) 2.1.6; Copyright (C) 2015 Free Software Foundation, Inc.
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+
+Note: Use "gpg2 --full-gen-key" for a full featured key generation dialog.
+
+GnuPG needs to construct a user ID to identify your key.
+
+Real name: Marvin the Paranoid Android
+Email address: marvin@h2g2.net
+You selected this USER-ID:
+ "Marvin the Paranoid Android <marvin@h2g2.net>"
+
+Change (N)ame, (E)mail, or (O)kay/(Q)uit? o
+We need to generate a lot of random bytes. It is a good idea to perform
+some other action (type on the keyboard, move the mouse, utilize the
+disks) during the prime generation; this gives the random number
+generator a better chance to gain enough entropy.gpg - entropy interlude
+At this point, you will:
+-
+
- be prompted for a secure password to protect your key (the input method will depend on your Desktop Environment and configuration) +
- be asked to use your machine's input devices (mouse, keyboard, etc.) to generate random entropy; this step may take some time +
gpg - key creation confirmation
+gpg: key A9D53A3E marked as ultimately trusted
+public and secret key created and signed.
+
+gpg: checking the trustdb
+gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
+gpg: depth: 0 valid: 2 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 2u
+pub rsa2048/A9D53A3E 2015-07-31
+ Key fingerprint = AF2A 5381 E54B 2FD2 14C4 A9A3 0E35 ACA4 A9D5 3A3E
+uid [ultimate] Marvin the Paranoid Android <marvin@h2g2.net>[](.html)
+sub rsa2048/8C0EACF1 2015-07-31gpg - submit your public key to a PGP server (Optional)
+$ gpg --keyserver pgp.mit.edu --send-keys A9D53A3E
+gpg: sending key A9D53A3E to hkp server pgp.mit.eduCreate and push a GPG-signed tag
+See Git - Maintaining a project - Tagging your [](.html)
releases.
Prerequisites
+This guide assumes that you have:
+-
+
- a GPG key matching your GitHub authentication credentials
+
-
+
- i.e., the email address identified by the GPG key is the same as the one in your
~/.gitconfig
+
+ - i.e., the email address identified by the GPG key is the same as the one in your
- a GitHub fork of Shaarli +
- a local clone of your Shaarli fork, with the following remotes:
+
-
+
originpointing to your GitHub fork
+upstreampointing to the main Shaarli repository
+
+ - maintainer permissions on the main Shaarli repository (to push the signed tag) +
Bump Shaarli's version
+$ cd /path/to/shaarli
+
+# create a new branch
+$ git fetch upstream
+$ git checkout upstream/master -b v0.5.0
+
+# bump the version number
+$ vim index.php shaarli_version.php
+
+# commit the changes
+$ git add index.php shaarli_version.php
+$ git commit -s -m "Bump version to v0.5.0"
+
+# push the commit on your GitHub fork
+$ git push origin v0.5.0Create and merge a Pull Request
+This one is pretty straightforward ;-)
+Create and push a signed tag
+# update your local copy
+$ git checkout master
+$ git fetch upstream
+$ git pull upstream master
+
+# create a signed tag
+$ git tag -s -m "Release v0.5.0" v0.5.0
+
+# push it to "upstream"
+$ git push --tags upstreamVerify a signed tag
+v0.5.0 is the first GPG-signed tag pushed on the Community Shaarli.
Let's have a look at its signature!
+$ cd /path/to/shaarli
+$ git fetch upstream
+
+# get the SHA1 reference of the tag
+$ git show-ref tags/v0.5.0
+f7762cf803f03f5caf4b8078359a63783d0090c1 refs/tags/v0.5.0
+
+# verify the tag signature information
+$ git verify-tag f7762cf803f03f5caf4b8078359a63783d0090c1
+gpg: Signature made Thu 30 Jul 2015 11:46:34 CEST using RSA key ID 4100DF6F
+gpg: Good signature from "VirtualTam <virtualtam@flibidi.net>" [ultimate][](.html)-
-
- - -
- - -
- - -
- Backup
-
-
-
-
- I forgot my password !
- I'm locked out - Login bruteforce protection
- List of all login attempts
- Exporting from Diigo
- Importing from SemanticScuttle
- Importing from Mister Wong
- Hosting problems
- Dates are not properly formatted
- Problems on CentOS servers
- My session expires ! I can't stay logged in
Sessions do not seem to work correctly on your server
-- pubsubhubbub support
- - I forgot my password !
- - -
- - -
- Other links
- - -
- - -
- -
-
Basic Usage
-Add the sharing button (bookmarklet) to your browser
--
-
- Open your Shaarli and
Login
- - Click the
Toolsbutton in the top bar
- - Drag the
✚Shaare linkbutton, and drop it to your browser's bookmarks bar.
-
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.
-
Add Shaarli as a sharing service to Firefox
--
-
- Open your Shaarli and
Login
- - Click the
Toolsbutton in the top bar
- - Click the
✚Add to Firefox socialbutton 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.
- A window opens.
- You can freely edit title, description, tags... to find it later using the text search or tag filtering.
- You will be able to edit this link later using the
edit button.
- - You can also check the “Private” box so that the link is saved but only visible to you.
- Click
Save.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
-Shaarli can be used:
--
-
- to share, comment and save interesting links and news
- to bookmark useful/frequent personal links (as private links) and share them between computers
- as a minimal blog/microblog/writing platform (no character limit)
- as a read-it-later list (for example items tagged
readlater)
- - to draft and save articles/ideas
- to keep code snippets
- to keep notes and documentation
- as a shared clipboard between machines
- as a todo list
- to store playlists (e.g. with the
musicorvideotags)
- - to keep extracts/comments from webpages that may disappear
- to keep track of ongoing discussions (for example items tagged
discussion)
- - to feed RSS aggregators (planets) with specific tags
- to feed other social networks, blogs... using RSS feeds and external services (dlvr.it, ifttt.com ...) -
Using Shaarli as a blog, notepad, pastebin...
--
-
- Go to your Shaarli setup and log in
- Click the
Add Linkbutton
- - To share text only, do not enter any URL in the corresponding input field and click
Add Link
- - Pick a title and enter your article, or note, in the description field; add a few tags; optionally check
Privatethen clickSave
- - Voilà! Your article is now published (privately if you selected that option) and accessible using its permalink. -
RSS Feeds or Picture Wall for a specific search/tag
-It is possible to filter RSS/ATOM feeds and Picture Wall on a Shaarli to only display results of a specific search, or for a specific tag. For example, if you want to subscribe only to links tagged photography:
-
-
- Go to the desired Shaarli instance.
- Search for the
photographytag in the Filter by tag box. Links taggedphotographyare displayed.
- - Click on the
RSS Feedbutton.
- - You are presented with an RSS feed showing only these links. Subscribe to it to receive only updates with this tag.
- 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:
<?php
- $GLOBALS['config']['LINKS_PER_PAGE'] = 30;
- $GLOBALS['config']['HIDE_TIMESTAMPS'] = true;
- $GLOBALS['config']['ENABLE_THUMBNAILS'] = false;
- ?>Do not edit config options in index.php! Your changes would be lost when you upgrade. The following parameters are available (parameters (default value)):
--
-
DATADIR ('data'): This is the name of the subdirectory where Shaarli stores is data file. You can change it for better security.
-CONFIG_FILE ($GLOBALS['config']['DATADIR'].'/config.php'): Name of file which is used to store login/password.
-DATASTORE ($GLOBALS['config']['DATADIR'].'/datastore.php'): Name of file which contains the link database.
-LINKS_PER_PAGE (20): Default number of links per page displayed.
-IPBANS_FILENAME ($GLOBALS['config']['DATADIR'].'/ipbans.php'): Name of file which records login attempts and IP bans.
-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).#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
-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.
-UPDATECHECK_INTERVAL (86400): Delay between new Shaarli version check. 86400 seconds = 24 hours. Note that if you do not login for a week, Shaarli will not check for new version for a week.
-ENABLE_UPDATECHECK: Determines whether Shaarli check for new releases at https://github.com/shaarli/Shaarli
-SHOW_ATOM (false): Show anATOM Feedbutton next to theSubscribe(RSS) button. ATOM feeds are available at the address?do=atomregardless 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).trueis 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
--
-
- Shaarli's apparence can be modified by editing CSS rules in
inc/user.css. This file allows to override rules defined in the maininc/shaarli.css(only add changed rules), or define a whole new theme.
- - Do not edit
inc/shaarli.css! Your changes would be overriden when updating Shaarli.
- - Some themes are available at https://github.com/shaarli/shaarli-themes. -
See also:
- -Changing template
-| 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, rungit clone https://url/of/my-template/or unpack the zip archive. There should now be amy-template/directory under thetpl/dir, containing directly all the template files.
- - Edit
data/options.phpto 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:
--
-
- Backup the file
data/datastore.php(by FTP or SSH). Restore by putting the file back in place.
- - Example command:
rsync -avzP my.server.com:/var/www/shaarli/data/datastore.php datastore-$(date +%Y-%m-%d_%H%M).php
- - Export your links as HTML (Menu
Tools>Export). Restore by using theImportfeature.
- - This can be done using the shaarchiver tool. Example command:
./export-bookmarks.py --url=https://my.server.com/shaarli --username=myusername --password=mysupersecretpassword --download-dir=./ --type=all
-
Troubleshooting
-I forgot my password !
-Delete the file data/config.php and display the page again. You will be asked for a new login/password.
-I'm locked out - Login bruteforce protection
-Login form is protected against brute force attacks: 4 failed logins will ban the IP address from login for 30 minutes. Banned IPs can still browse links.
-To remove the current IP bans, delete the file data/ipbans.php
List of all login attempts
-The file data/log.txt shows all logins (successful or failed) and bans/lifted bans.
Search for failed in this file to look for unauthorized login attempts.
Exporting from Diigo
-If you export your bookmark from Diigo, make sure you use the Delicious export, not the Netscape export. (Their Netscape export is broken, and they don't seem to be interested in fixing it.)
-Importing from SemanticScuttle
-To correctly import the tags from a SemanticScuttle HTML export, edit the HTML file before importing and replace all occurences of tags= (lowercase) to TAGS= (uppercase).
Importing from Mister Wong
-See this issue for import tweaks.
-Hosting problems
--
-
- On free.fr : Please note that free uses php 5.1 and thus you will not have autocomplete in tag editing. Don't forget to create a
sessionsdirectory at the root of your webspace. Change the file extension to.php5or create a.htaccessfile in the directory where Shaarli is located containing:
-
php 1
-SetEnv PHP_VER 5-
-
- If you have an error such as:
Parse error: syntax error, unexpected '=', expecting '(' in /links/index.php on line xxx, it means that your host is using php4, not php5. Shaarli requires php 5.1. Try changing the file extension to.php5
- - On 1and1 : If you add the link from the page (and not from the bookmarklet), Shaarli will no be able to get the title of the page. You will have to enter it manually. (Because they have disabled the ability to download a file through HTTP).
- If you have the error
Warning: file_get_contents() [function.file-get-contents]: URL file-access is disabled in the server configuration in /…/index.php on line xxx, it means that your host has disabled the ability to fetch a file by HTTP in the php config (Typically in 1and1 hosting). Bad host. Change host. Or comment the following lines:
-
//list($status,$headers,$data) = getHTTP($url,4); // Short timeout to keep the application responsive.
-// FIXME: Decode charset according to charset specified in either 1) HTTP response headers or 2) <head> in html
-//if (strpos($status,'200 OK')) $title=html_extract_title($data);-
-
- On hosts which forbid outgoing HTTP requests (such as free.fr), some thumbnails will not work.
- On lost-oasis, RSS doesn't work correctly, because of this message at the begining of the RSS/ATOM feed :
<? // tout ce qui est charge ici (generalement des includes et require) est charge en permanence. ?>. To fix this, remove this message fromphp-include/prepend.php
-
Dates are not properly formatted
-Shaarli tries to sniff the language of the browser (using HTTP_ACCEPT_LANGUAGE headers) and choose a date format accordingly. But Shaarli can only use the date formats (and more generaly speaking, the locales) provided by the webserver. So even if you have a browser in French, you may end up with dates in US format (it's the case on sebsauvage.net :-( )
-Problems on CentOS servers
-On CentOS/RedHat derivatives, you may need to install the php-mbstring package.
My session expires ! I can't stay logged in
-This can be caused by several things:
--
-
- Your php installation may not have a proper directory setup for session files. (eg. on Free.fr you need to create a
sessiondirectory on the root of your website.) You may need to create the session directory of set it up.
- - Most hosts regularly clean the temporary and session directories. Your host may be cleaning those directories too aggressively (eg.OVH hosts), forcing an expire of the session. You may want to set the session directory in your web root. (eg. Create the
sessionssubdirectory and addini_set('session.save_path', $_SERVER['DOCUMENT_ROOT'].'/../sessions');. Make sure this directory is not browsable !)
- - If your IP address changes during surfing, Shaarli will force expire your session for security reasons (to prevent session cookie hijacking). This can happen when surfing from WiFi or 3G (you may have switched WiFi/3G access point), or in some corporate/university proxies which use load balancing (and may have proxies with several external IP addresses).
- Some browser addons may interfer with HTTP headers (ipfuck/ipflood/GreaseMonkey…). Try disabling those.
- You may be using OperaTurbo or OperaMini, which use their own proxies which may change from time to time.
- If you have another application on the same webserver where Shaarli is installed, these application may forcefully expire php sessions. -
Sessions do not seem to work correctly on your server
-Follow the instructions in the error message. Make sure you are accessing shaarli via a direct IP address or a proper hostname. If you have no dots in the hostname (e.g. localhost or http://my-webserver/shaarli/), some browsers will not store cookies at all (this respects the HTTP cookie specification).
pubsubhubbub support
-Download publisher.php at the root of your Shaarli installation and set $GLOBALS['config']['PUBSUBHUB_URL'] in your config.php
Notes
-Various hacks
--
-
- 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
-
-$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
--
-
- Look for
<input type="hidden" name="lf_linkdate" value="{$link.linkdate}">intpl/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 - 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 -
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.
- 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 -
Integrate Shaarli with other platforms
--
-
- tt-rss-shaarli - TinyTiny RSS plugin that adds support for sharing articles with Shaarli
- 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) -
Other links
--
-
- Liens en vrac de sebsauvage - the original Shaarli
- A large list of Shaarlis
- A list of working Shaarli aggregators
- A list of some known Shaarlis
- Adieu Delicious, Diigo et StumbleUpon. Salut Shaarli ! - sebsauvage.net (fr) 16/09/2011 - the original post about Shaarli
- Original ideas/fixme/TODO page
- Original discussion page (fr)
- Original revisions history
- Shaarli.fr/my - Unofficial, unsupported (old fork) hosted Shaarlis provider, courtesy of DMeloni
- Shaarli Communauty - Another unofficial Shaarli hoster (unsupported, old fork), hoster unknown -
FAQ
-Why did you create Shaarli ?
-I was a StumbleUpon user. Then I got fed up with they big toolbar. I switched to delicious, which was lighter, faster and more beautiful. Until Yahoo bought it. Then the export API broke all the time, delicious became slow and was ditched by Yahoo. I switched to Diigo, which is not bad, but does too much. And Diigo is sslllooooowww and their Firefox extension a bit buggy. And… oh… their Firefox addon sends to Diigo every single URL you visit (Don't believe me ? Use Tamper Data and open any page).
-Enough is enough. Saving simple links should not be a complicated heavy thing. I ditched them all and wrote my own: Shaarli. It's simple, but it does the job and does it well. And my data is not hosted on a foreign server, but on my server.
-Why use Shaarli and not Delicious/Diigo ?
-With Shaarli:
--
-
- The data is yours: It's hosted on your server.
- Never fear of having your data locked-in.
- Never fear to have your data sold to third party.
- Your private links are not hosted on a third party server.
- You are not tracked by browser addons (like Diigo does)
- You can change the look and feel of the pages if you want.
- You can change the behaviour of the program.
- It's magnitude faster than most bookmarking services. -
What does Shaarli mean ?
-Shaarli is for shaaring your links.
-Technical details
--
-
- Application is protected against XSRF (Cross-site requests forgery): Forms which act on data (save,delete…) contain a token generated by the server. Any posted form which does not contain a valid token is rejected. Any token can only be used once. Token are attached to the session and cannot be reused in another session.
- Sessions automatically expires after 60 minutes. Sessions are protected against highjacking: The sessionID cannot be used from a different IP address.
- An .htaccess file protects the data file.
Link database is an associative array which is serialized, compressed (with deflate), base64-encoded and saved as a comment in a .php file. Thus even if the server does not support htaccess files, the data file will still not be readable by URL. The database looks like this:
-<?php /* zP1ZjxxJtiYIvvevEPJ2lDOaLrZv7o... -...ka7gaco/Z+TFXM2i7BlfMf8qxpaSSYfKlvqv/x8= */ ?>
-- The password is salted, hashed and stored in the data subdirectory, in a php file, and protected by htaccess. Even if the webserver does not support htaccess, the hash is not readable by URL. Even if the .php file is stolen, the password cannot deduced from the hash. The salt prevents rainbow-tables attacks.
- Shaarli relies on
HTTP_REFERERfor some functions (like redirects and clicking on tags). If you have disabled or masqueradedHTTP_REFERERin your browser, some features of Shaarli may not work
- magic_quotesis a horrible option of php which is often activated on servers. No serious developer should rely on this horror to secure their code against SQL injections. You should disable it (and Shaarli expects this option to be disabled). Nevertheless, I have added code to cope with magic_quotes on, so you should not be bothered even on crappy hosts.
-Small hashes are used to make a link to an entry in Shaarli. They are unique. In fact, the date of the items (eg.20110923_150523) is hashed with CRC32, then converted to base64 and some characters are replaced. They are always 6 characters longs and use only A-Z a-z 0-9 - _ and @.
-
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…)
- ├── 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.
- 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)
- add more screenshots
- add developer documentation (storage architecture, classes and functions, security handling, ...) -
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 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.