Missing js file in myShaarly plugin

Remove Doc, now link to official documentation page

.dev/.eslintrc.js

@@ -0,0 +1,12 @@
+module.exports = {
+  "extends": "airbnb-base",
+  "env": {
+    "browser": true,
+  },
+  "rules": {
+    "no-param-reassign": 0, // manipulate DOM style properties
+    "no-restricted-globals": 0, // currently Shaarli uses alert/confirm, could be be improved later
+    "no-alert": 0, // currently Shaarli uses alert/confirm, could be be improved later
+    "no-cond-assign": [2, "except-parens"], // assignment in while loops is readable and avoid assignment duplication
+  }
+};

.dev/.stylelintrc.js

@@ -0,0 +1,15 @@
+module.exports = {
+  extends: 'stylelint-config-standard',
+  plugins: [
+    "stylelint-scss"
+  ],
+  rules: {
+    "indentation": [2],
+    "number-leading-zero": null,
+    // Replace CSS @ with SASS ones
+    "at-rule-no-unknown": null,
+    "scss/at-rule-no-unknown": true,
+    // not compatible with SASS apparently
+    "no-descending-specificity": null
+  },
+}

.docker/.htaccess

@@ -0,0 +1,13 @@
+<IfModule version_module>
+  <IfVersion >= 2.4>
+     Require all denied
+  </IfVersion>
+  <IfVersion < 2.4>
+     Allow from none
+     Deny from all
+  </IfVersion>
+</IfModule>
+
+<IfModule !version_module>
+    Require all denied
+</IfModule>

.docker/nginx.conf

@@ -0,0 +1,60 @@
+user nginx nginx;
+daemon off;
+worker_processes 4;
+pid /var/run/nginx.pid;
+
+events {
+    worker_connections  768;
+}
+
+http {
+    include            mime.types;
+    default_type       application/octet-stream;
+    keepalive_timeout  20;
+
+    client_max_body_size 10m;
+
+    index index.html index.php;
+
+    server {
+        listen      80;
+        listen      [::]:80;
+        root        /var/www/shaarli;
+
+        access_log  /var/log/nginx/shaarli.access.log;
+        error_log   /var/log/nginx/shaarli.error.log;
+
+        location ~* \.(?:ico|css|js|gif|jpe?g|png|ttf|oet|woff2?)$ {
+            # cache static assets
+            expires    max;
+            add_header Pragma public;
+            add_header Cache-Control "public, must-revalidate, proxy-revalidate";
+        }
+
+        location = /favicon.ico {
+            # serve the Shaarli favicon from its custom location
+            alias /var/www/shaarli/images/favicon.ico;
+        }
+
+        location /doc/html/ {
+            default_type "text/html";
+            try_files $uri $uri/ $uri.html =404;
+        }
+
+        location / {
+            # Slim - rewrite URLs & do NOT serve static files through this location
+            try_files _ /index.php$is_args$args;
+        }
+
+        location ~ index\.php$ {
+            # Slim - split URL path into (script_filename, path_info)
+            try_files $uri =404;
+            fastcgi_split_path_info ^(index.php)(/.+)$;
+
+            # filter and proxy PHP requests to PHP-FPM
+            fastcgi_pass   unix:/var/run/php-fpm.sock;
+            fastcgi_index  index.php;
+            include        fastcgi.conf;
+        }
+    }
+}

.docker/php-fpm.conf

@@ -0,0 +1,16 @@
+[global]
+daemonize = no
+
+[www]
+user = nginx
+group = nginx
+listen.owner = nginx
+listen.group = nginx
+catch_workers_output = yes
+listen = /var/run/php-fpm.sock
+pm = dynamic
+pm.max_children = 20
+pm.start_servers = 1
+pm.min_spare_servers = 1
+pm.max_spare_servers = 3
+pm.max_requests = 2048

.docker/services.d/.s6-svscan/finish

@@ -0,0 +1,2 @@
+#!/bin/sh
+/bin/true

.docker/services.d/nginx/run

@@ -0,0 +1,2 @@
+#!/bin/execlineb -P
+nginx

.docker/services.d/php-fpm/run

@@ -0,0 +1,2 @@
+#!/bin/execlineb -P
+php-fpm8 -F

.dockerignore

@@ -0,0 +1,64 @@
+# Docker-ignore
+.dev
+.git
+.github
+.gitattributes
+.gitignore
+tests
+
+# Docker related resources are not needed inside the container
+.dockerignore
+Dockerfile
+Dockerfile.armhf
+
+# Docker Compose resources
+docker-compose.yml
+
+# Shaarli runtime resources
+cache/*
+data/*
+pagecache/*
+tmp/*
+
+# Shaarli's docs are created during the build
+doc/html/
+
+# Eclipse project files
+.settings
+.buildpath
+.project
+
+# Raintpl generated pages
+*.rtpl.php
+
+# 3rd-party dependencies
+vendor/
+
+# Release archives
+*.tar.gz
+*.zip
+inc/languages/*/LC_MESSAGES/shaarli.mo
+
+# Development and test resources
+coverage
+doxygen
+sandbox
+phpmd.html
+
+# User plugin configuration
+plugins/*/config.php
+
+# 3rd party themes
+tpl/*
+!tpl/default
+!tpl/vintage
+
+# Front end
+node_modules
+tpl/default/js
+tpl/default/css
+tpl/default/fonts
+tpl/default/img
+tpl/vintage/js
+tpl/vintage/css
+tpl/vintage/img

.editorconfig

@@ -0,0 +1,23 @@
+# EditorConfig: http://EditorConfig.org
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{htaccess,html,scss,js,json,xml,yml}]
+indent_size = 2
+
+[*.php]
+max_line_length = 120
+
+[Dockerfile]
+max_line_length = 80
+
+[Makefile]
+indent_style = tab

.gitattributes

@@ -0,0 +1,47 @@
+# Set default behavior
+*       text=auto eol=lf
+
+# Ensure sources are processed
+*.conf  text
+*.css   text
+*.html  text diff=html
+*.js    text
+*.md    text
+*.php   text diff=php
+Dockerfile      text
+
+# Do not alter images nor minified scripts nor fonts
+*.ico           binary
+*.jpg           binary
+*.png           binary
+*.svg           binary
+*.otf           binary
+*.eot           binary
+*.woff          binary
+*.woff2         binary
+*.ttf           binary
+*.min.css       binary
+*.min.js        binary
+*.mo            binary
+
+# Exclude from Git archives
+.editorconfig     export-ignore
+.dev              export-ignore
+.gitattributes    export-ignore
+.github           export-ignore
+.gitignore        export-ignore
+.travis.yml       export-ignore
+doc/**/*.json     export-ignore
+doc/**/*.md       export-ignore
+.docker/          export-ignore
+.dockerignore     export-ignore
+docker-compose.*  export-ignore
+Dockerfile*       export-ignore
+Doxyfile          export-ignore
+Makefile          export-ignore
+node_modules/     export-ignore
+doc/conf.py       export-ignore
+doc/requirements.txt export-ignore
+doc/html/.doctrees/  export-ignore
+phpunit.xml       export-ignore
+tests/            export-ignore

.github/mailmap

@@ -0,0 +1,22 @@
+ArthurHoaro <arthur@hoa.ro> <arthur.hoareau@wizacha.com>
+ArthurHoaro <arthur@hoa.ro> Arthur
+Florian Eula <eula.florian@gmail.com> feula
+Florian Eula <eula.florian@gmail.com> <mr.pikzen@gmail.com>
+Immánuel Fodor <immanuelfactor+github@gmail.com>
+Immánuel Fodor <immanuelfactor+github@gmail.com> Immánuel! <21174107+immanuelfodor@users.noreply.github.com>
+kalvn <kalvnthereal@gmail.com> <kalvn@users.noreply.github.com>
+kalvn <kalvnthereal@gmail.com> <kalvn@pm.me>
+Neros <contact@neros.fr> <NerosTie@users.noreply.github.com>
+Nicolas Danelon <hi@nicolasmd.com.ar> nicolasm
+Nicolas Danelon <hi@nicolasmd.com.ar> <nda@3818.com.ar>
+Nicolas Danelon <hi@nicolasmd.com.ar> <nicolasdanelon@gmail.com>
+Nicolas Danelon <hi@nicolasmd.com.ar> <nicolasdanelon@users.noreply.github.com>
+Sébastien Sauvage <sebsauvage@sebsauvage.net>
+Sébastien NOBILI <code@pipoprods.org> <s-code-github@pipoprods.org>
+Timo Van Neerden <fire@lehollandaisvolant.net>
+Timo Van Neerden <fire@lehollandaisvolant.net> lehollandaisvolant <levoltigeurhollandais@gmail.com>
+VirtualTam <virtualtam@flibidi.net> <tamisier.aurelien@gmail.com>
+VirtualTam <virtualtam@flibidi.net> <virtualtam+github@flibidi.net>
+VirtualTam <virtualtam@flibidi.net> <virtualtam@flibidi.org>
+Willi Eggeling <thewilli@gmail.com> <mail@wje-online.de>
+Willi Eggeling <thewilli@gmail.com> <thewilli@users.noreply.github.com>

.github/workflows/ci.yml

@@ -0,0 +1,106 @@
+name: Shaarli CI
+on: [push, pull_request]
+jobs:
+  php:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        php-versions: ['7.4', '8.0', '8.1', '8.2']
+    name: PHP ${{ matrix.php-versions }}
+    steps:
+      - name: Set locales
+        run: |
+          sudo locale-gen de_DE.utf8 && \
+          sudo locale-gen en_US.utf8 && \
+          sudo locale-gen fr_FR.utf8 && \
+          sudo dpkg-reconfigure --frontend=noninteractive locales
+
+      - name: Install Gettext
+        run: sudo apt-get install gettext
+
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php-versions }}
+          extensions: gd, xml, curl, mbstring, intl, gettext
+          tools: composer:v2
+
+      - name: Check PHP version
+        run: php -v
+
+      - name: Setup Composer from PHP version + update
+        run: composer config --unset platform && composer config platform.php ${{ matrix.php-versions }}
+
+      - name: Update dependencies for PHP 8.x
+        if: ${{ matrix.php-versions == '8.0' || matrix.php-versions == '8.1' }}
+        run: |
+          composer update && \
+          composer remove --dev phpunit/phpunit && \
+          composer require --dev phpunit/php-text-template ^2.0 && \
+          composer require --dev phpunit/phpunit ^9.0
+
+      - name: Update dependencies for PHP 7.x
+        if: ${{ matrix.php-versions != '8.0' && matrix.php-versions != '8.1' }}
+        run: composer update
+
+      - name: Clean up
+        run: make clean
+
+      - name: Check permissions
+        run: make check_permissions
+
+      - name: Run PHPCS
+        run: make code_sniffer
+
+      - name: Run tests
+        run: make all_tests
+
+  node:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '14.x'
+
+      - name: Yarn install
+        run: yarnpkg install
+
+      - name: Verify successful frontend builds
+        run: yarnpkg run build
+
+      - name: JS static analysis
+        run: make eslint
+
+      - name: Linter for SASS syntax
+        run: make sasslint
+
+  python:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.8
+
+      - name: Build documentation
+        run: make htmldoc
+
+  trivy-repo:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Run trivy scanner on repository (non-blocking)
+        run: make test_trivy_repo TRIVY_EXIT_CODE=0

.github/workflows/docker-latest.yml

@@ -0,0 +1,45 @@
+name: Build/push Docker image (master/latest)
+on:
+  push:
+    branches: [ master ]
+jobs:
+  docker-build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v2
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v2
+
+      - name: Login to DockerHub
+        uses: docker/login-action@v2
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v2
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Set shaarli version to the latest commit hash
+        run: sed -i "s/dev/$(git rev-parse --short HEAD)/" shaarli_version.php
+
+      - name: Build and push
+        id: docker_build
+        uses: docker/build-push-action@v4
+        with:
+          context: .
+          push: true
+          platforms: linux/amd64,linux/arm64,linux/arm/v7
+          tags: |
+            ${{ secrets.DOCKER_IMAGE }}:latest
+            ghcr.io/${{ secrets.DOCKER_IMAGE }}:latest
+      - name: Image digest
+        run: echo ${{ steps.docker_build.outputs.digest }}
+      - name: Run trivy scanner on latest docker image
+        run: make test_trivy_docker TRIVY_TARGET_DOCKER_IMAGE=ghcr.io/${{ secrets.DOCKER_IMAGE }}:latest

.github/workflows/docker-pr.yml

@@ -0,0 +1,21 @@
+name: Build Docker image (Pull Request)
+on:
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  docker-build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v1
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v1
+      - name: Build Docker image
+        id: docker_build
+        uses: docker/build-push-action@v2
+        with:
+          push: false
+          tags: shaarli/shaarli:pr-${{ github.event.number }}
+      - name: Image digest
+        run: echo ${{ steps.docker_build.outputs.digest }}

.github/workflows/docker-tags.yml

@@ -0,0 +1,43 @@
+name: Build/push Docker image (tags/releases)
+on:
+  push:
+    tags:
+      - "v*.*.*"
+    branches:
+      - "v*.*"
+      - release
+jobs:
+  docker-build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Get the tag name
+        run: echo "REF=${GITHUB_REF##*/}" >> $GITHUB_ENV
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v2
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v2
+
+      - name: Login to DockerHub
+        uses: docker/login-action@v2
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      -
+        name: Login to GitHub Container Registry
+        uses: docker/login-action@v2
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push
+        id: docker_build
+        uses: docker/build-push-action@v3
+        with:
+          push: true
+          platforms: linux/amd64,linux/arm/v7
+          tags: |
+            ${{ secrets.DOCKER_IMAGE }}:${{ env.REF }}
+            ghcr.io/${{ secrets.DOCKER_IMAGE }}:${{ env.REF }}
+      - name: Image digest
+        run: echo ${{ steps.docker_build.outputs.digest }}

.gitignore

@@ -1,4 +1,4 @@
-# Ignore data/, tmp/, cache/ and pagecache/
+# Shaarli runtime resources
 data
 tmp
 cache
@@ -8,3 +8,66 @@ pagecache
 .settings
 .buildpath
 .project
+
+# Raintpl generated pages
+*.rtpl.php
+
+# 3rd-party dependencies
+vendor/
+
+# Release archives
+*.tar.gz
+*.zip
+inc/languages/*/LC_MESSAGES/shaarli.mo
+
+# Development and test resources
+coverage
+sandbox
+phpmd.html
+phpdoc.xml
+.phpunit.result.cache
+trivy
+
+# User plugin configuration
+plugins/*
+!addlink_toolbar
+!archiveorg
+!default_colors
+!demo_plugin
+!isso
+!myShaarli
+!piwik
+!playvideos
+!pubsubhubbub
+!qrcode
+!wallabag
+plugins/*/config.php
+plugins/default_colors/default_colors.css
+
+# HTML documentation
+doc/html/
+doc/phpdoc/
+
+# 3rd party themes
+tpl/*
+!tpl/default
+!tpl/vintage
+!tpl/myShaarli
+
+contact.php
+formStyle.css
+
+# Front end
+node_modules
+tpl/default/js
+tpl/default/css
+tpl/default/fonts
+tpl/default/img
+tpl/vintage/js
+tpl/vintage/css
+tpl/vintage/img
+
+.composer.lock
+
+# Documented scripts
+generate_templates.php

.htaccess

@@ -0,0 +1,37 @@
+# Disable directory listing
+Options -Indexes
+
+RewriteEngine On
+
+# Prevent accessing subdirectories not managed by SCM
+RewriteRule ^(.git|doxygen|vendor) - [F]
+
+# Forward the "Authorization" HTTP header
+# fixes JWT token not correctly forwarded on some Apache/FastCGI setups
+RewriteCond %{HTTP:Authorization} ^(.*)
+RewriteRule .* - [e=HTTP_AUTHORIZATION:%1]
+# Alternative (if the 2 lines above don't work)
+# SetEnvIf Authorization .+ HTTP_AUTHORIZATION=$0
+
+# Slim URL Redirection
+# Ionos Hosting needs RewriteBase /
+# RewriteBase /
+RewriteCond %{REQUEST_FILENAME} !-f
+RewriteCond %{REQUEST_FILENAME} !-d
+RewriteRule ^ index.php [QSA,L]
+
+<LimitExcept GET POST PUT DELETE PATCH OPTIONS>
+  <IfModule version_module>
+    <IfVersion >= 2.4>
+       Require all denied
+    </IfVersion>
+    <IfVersion < 2.4>
+       Allow from none
+       Deny from all
+    </IfVersion>
+  </IfModule>
+
+  <IfModule !version_module>
+    Require all denied
+  </IfModule>
+</LimitExcept>

.readthedocs.yml

@@ -0,0 +1,23 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: doc/conf.py
+  builder: html
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  commands:
+    - pip install sphinx==7.1.0 furo==2023.7.26 myst-parser sphinx-design
+    - sphinx-build -b html -c doc/ doc/md/ _readthedocs/html/
+
+python:
+  install:
+    - requirements: doc/requirements.txt

AUTHORS

@@ -0,0 +1,123 @@
+  1216	ArthurHoaro <arthur@hoa.ro>
+   456	nodiscc <nodiscc@gmail.com>
+   405	VirtualTam <virtualtam@flibidi.net>
+    56	Sébastien Sauvage <sebsauvage@sebsauvage.net>
+    27	dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
+    19	Keith Carangelo <mail@kcaran.com>
+    16	Luce Carević <lcarevic@access42.net>
+    15	Florian Eula <eula.florian@gmail.com>
+    14	Emilien Klein <emilien@klein.st>
+    12	Nicolas Danelon <hi@nicolasmd.com.ar>
+     9	Lucas Cimon <lucas.cimon@gmail.com>
+     9	Willi Eggeling <thewilli@gmail.com>
+     8	Christophe HENRY <christophe.henry@sbgodin.fr>
+     6	Immánuel Fodor <immanuelfactor+github@gmail.com>
+     6	YFdyh000 <yfdyh000@gmail.com>
+     6	kalvn <kalvnthereal@gmail.com>
+     6	B. van Berkum <dev@dotmpe.com>
+     6	Immánuel Fodor <immanuelfactor+github@gmail.com>
+     6	YFdyh000 <yfdyh000@gmail.com>
+     6	kalvn <kalvnthereal@gmail.com>
+     6	llune <llune@users.noreply.github.com>
+     5	Mark Schmitz <kramred@gmail.com>
+     5	Sébastien NOBILI <code@pipoprods.org>
+     4	Alexandre Alapetite <alexandre@alapetite.fr>
+     4	yude <yudesleepy@gmail.com>
+     4	David Sferruzza <david.sferruzza@gmail.com>
+     4	yude <yudesleepy@gmail.com>
+     3	Agurato <mail.vmonot@gmail.com>
+     3	Christoph Stoettner <christoph.stoettner@stoeps.de>
+     3	Olivier <bourreauolivier@gmail.com>
+     3	Teromene <teromene@teromene.fr>
+     3	yudete <yu@yude.moe>
+     2	Alexander Railean <alexandr.railean@arculus.de>
+     2	Alexandre G.-Raymond <alex@ndre.gr>
+     2	Chris Kuethe <chris.kuethe@gmail.com>
+     2	Doug Breaux <25640850+dougbreaux@users.noreply.github.com>
+     2	Felix Bartels <felix@host-consultants.de>
+     2	Ganesh Kandu <kanduganesh@gmail.com>
+     2	Gregory <gregory@nosheep.fr>
+     2	Guillaume Virlet <github@virlet.org>
+     2	Knah Tsaeb <Knah-Tsaeb@knah-tsaeb.org>
+     2	Mathieu Chabanon <git@matchab.fr>
+     2	Miloš Jovanović <mjovanovic@gmail.com>
+     2	Neros <contact@neros.fr>
+     2	Qwerty <champlywood@free.fr>
+     2	Sebastien Wains <sebw@users.noreply.github.com>
+     2	Stephen Muth <smuth4@gmail.com>
+     2	Timo Van Neerden <fire@lehollandaisvolant.net>
+     2	flow.gunso <flow.gunso@gmail.com>
+     2	julienCXX <software@chmodplusx.eu>
+     2	Knah Tsaeb <Knah-Tsaeb@knah-tsaeb.org>
+     2	philipp-r <philipp-r@users.noreply.github.com>
+     2	pips <pips@e5150.fr>
+     2	prog-it <pash.vld@gmail.com>
+     2	trailjeep <trailjeep@gmail.com>
+     1	leyrer <gitlab@leyrer.priv.at>
+     1	locness3 <37651007+locness3@users.noreply.github.com>
+     1	owen bell <66233223+xfnw@users.noreply.github.com>
+     1	philipp <philipp@philipp.PC.Ubuntu>
+     1	rfolo9li <50079896+rfolo9li@users.noreply.github.com>
+     1	sprak3000 <sprak3000+github@gmail.com>
+     1	yudejp <i@yude.jp>
+     1	Rajat Hans <rajathans9@gmail.com>
+     1	Adrien le Maire <adrien@alemaire.be>
+     1	Ajabep <ajabep@users.noreply.github.com>
+     1	Alexis J <alexis@effingo.be>
+     1	Alistair Young <avatar@arkane-systems.net>
+     1	Amadeous <amadeous@users.noreply.github.com>
+     1	Angristan <angristan@users.noreply.github.com>
+     1	Bish Erbas <42714627+bisherbas@users.noreply.github.com>
+     1	BoboTiG <bobotig@gmail.com>
+     1	Brendan M. Sleight <bms.git@barwap.com>
+     1	Bronco <bronco@warriordudimanche.net>
+     1	Buster One <37770318+buster-one@users.noreply.github.com>
+     1	D Low <daniellowtw@gmail.com>
+     1	Daniel Jakots <vigdis@chown.me>
+     1	David <dajare@gmail.com>
+     1	David Foucher <dev@tyjak.net>
+     1	Denis Renning <denis@devtty.de>
+     1	Dennis Verspuij <dennisverspuij@users.noreply.github.com>
+     1	Dimtion <zizou.xena@gmail.com>
+     1	Fanch <fanch-github@qth.fr>
+     1	Felix Kästner <github.com-fpunktk@fpunktk.de>
+     1	Florian Voigt <flvoigt@me.com>
+     1	Franck Kerbiriou <FranckKe@users.noreply.github.com>
+     1	Gary Marigliano <gmarigliano93@gmail.com>
+     1	Hazhar Galeh <78073762+hazhargaleh@users.noreply.github.com>
+     1	Hg <dev@indigo.re>
+     1	Jens Kubieziel <github@kubieziel.de>
+     1	Jonathan Amiez <jonathan.amiez@gmail.com>
+     1	Jonathan Druart <jonathan.druart@gmail.com>
+     1	Julien Pivotto <roidelapluie@inuits.eu>
+     1	Kevin Canévet <kevin@streamroot.io>
+     1	Kevin Masson <kevin.masson@methodinthemadness.eu>
+     1	Knah Tsaeb <knah-tsaeb@knah-tsaeb.org>
+     1	Lionel Martin <renarddesmers@gmail.com>
+     1	Loïc Carr <zizou.xena@gmail.com>
+     1	Mark Gerarts <mark.gerarts@gmail.com>
+     1	Marsup <marsup@gmail.com>
+     1	Nicolas Friedli <nicolas@theologique.ch>
+     1	Nicolas Le Gaillart <nicolas@legaillart.fr>
+     1	Paul van den Burg <github@paulvandenburg.nl>
+     1	Rajat Hans <rajathans9@gmail.com>
+     1	Sbgodin <Sbgodin@users.noreply.github.com>
+     1	ToM <tom@leloop.org>
+     1	TsT <tst2005@gmail.com>
+     1	agentcobra <agentcobra@free.fr>
+     1	aguy <aguytech@users.noreply.github.com>
+     1	bschwede <bschwede@users.noreply.github.com>
+     1	bschwede <gummibando@gmx.net>
+     1	clach04 <clach04@gmail.com>
+     1	dimtion <zizou.xena@gmail.com>
+     1	durcheinandr <jochen@durcheinandr.de>
+     1	heimpogo <hypertexthome@googlemail.com>
+     1	jalr <mail@jalr.de>
+     1	lapineige <lapineige@users.noreply.github.com>
+     1	leyrer <gitlab@leyrer.priv.at>
+     1	locness3 <37651007+locness3@users.noreply.github.com>
+     1	owen bell <66233223+xfnw@users.noreply.github.com>
+     1	philipp <philipp@philipp.PC.Ubuntu>
+     1	rfolo9li <50079896+rfolo9li@users.noreply.github.com>
+     1	sprak3000 <sprak3000+github@gmail.com>
+     1	yudejp <i@yude.jp>

CONTRIBUTING.md

@@ -0,0 +1,78 @@
+## Contributing to Shaarli (community repository)
+
+### Bugs and feature requests
+**Reporting bugs, feature requests: issues management**
+
+You can look through existing bugs/requests and help reporting them [here](https://github.com/shaarli/Shaarli/issues).
+
+Constructive input/experience reports/helping other users is welcome.
+
+The general guideline of the fork is to keep Shaarli simple (project and code maintenance, and features-wise), while providing customization capabilities (plugin system, making more settings configurable).
+
+Check the [milestones](https://github.com/shaarli/Shaarli/milestones) to see what issues have priority.
+
+ * The issues list should preferably contain **only tasks that can be actioned immediately**. Anyone should be able to open the issues list, pick one and start working on it immediately.
+ * If you have a clear idea of a **feature you expect, or have a specific bug/defect to report**, [search the issues list, both open and closed](https://github.com/shaarli/Shaarli/issues?q=is%3Aissue) to check if it has been discussed, and comment on the appropriate issue. If you can't find one, please open a [new issue](https://github.com/shaarli/Shaarli/issues/new)
+ * **General discussions** fit in #44 so that we don't follow a slope where users and contributors have to track 90 "maybe" items in the bug tracker. Separate issues about clear, separate steps can be opened after discussion.
+ * You can also join instant discussion at https://gitter.im/shaarli/Shaarli, or via IRC as described [here](https://github.com/shaarli/Shaarli/issues/44#issuecomment-77745105)
+ 
+### Documentation
+
+The [official documentation](http://shaarli.readthedocs.io/en/rtfd/) is generated from [Markdown](https://daringfireball.net/projects/markdown/syntax) documents in the `doc/md/` directory. HTML documentation is generated using [Mkdocs](http://www.mkdocs.org/). [Read the Docs](https://readthedocs.org/) provides hosting for the online documentation. 
+
+To edit the documentation, please edit the appropriate `doc/md/*.md` files (and optionally `make htmlpages` to preview changes to HTML files). Then submit your changes as a Pull Request. Have a look at the MkDocs documentation and configuration file `mkdocs.yml` if you need to add/remove/rename/reorder pages.
+
+### Translations
+Currently Shaarli has no translation/internationalization/localization system available and is single-language. You can help by proposing an i18n system (issue https://github.com/shaarli/Shaarli/issues/121)
+
+### Beta testing
+You can help testing Shaarli releases by immediately upgrading your installation after a [new version has been releases](https://github.com/shaarli/Shaarli/releases).
+
+All current development happens in [Pull Requests](https://github.com/shaarli/Shaarli/pulls). You can test proposed patches by cloning the Shaarli repo, adding the Pull Request branch and `git checkout` to it. You can also merge multiple Pull Requests to a testing branch.
+
+```bash
+git clone https://github.com/shaarli/Shaarli
+git remote add pull-request-25 owner/cool-new-feature
+git remote add pull-request-26 anotherowner/bugfix
+git remote update
+git checkout -b testing
+git merge cool-new-feature
+git merge bugfix
+```
+Or see [Checkout Github Pull Requests locally](https://gist.github.com/piscisaureus/3342247)
+
+Please report any problem you might find.
+
+
+### Contributing code
+
+#### Adding your own changes
+
+ * Pick or open an issue
+ * Fork the Shaarli repository on github
+ * `git clone`  your fork
+ * starting from branch ` master`, switch to a new branch (eg. `git checkout -b my-awesome-feature`)
+ * edit the required files (from the Github web interface or your text editor)
+ * add and commit your changes with a meaningful commit message (eg `Cool new feature, fixes issue #1001`)
+ * run unit tests against your patched version, see [Running unit tests](https://shaarli.readthedocs.io/en/master/Unit-tests/#run-unit-tests)
+ * Open your fork in the Github web interface and click the "Compare and Pull Request" button, enter required info and submit your Pull Request.
+
+All changes you will do on the `my-awesome-feature`  in the future will be added to your Pull Request. Don't work directly on the master branch, don't do unrelated work on your  `my-awesome-feature` branch.
+
+#### Contributing to an existing Pull Request
+
+TODO
+
+#### Useful links
+If you are not familiar with Git or Github, here are a few links to set you on track:
+
+ * https://try.github.io/ - 10 minutes Github workflow interactive tutorial
+ * http://ndpsoftware.com/git-cheatsheet.html - A Git cheatsheet
+ * http://www.wei-wang.com/ExplainGitWithD3 - Helps you understand some basic Git concepts visually
+ * https://www.atlassian.com/git/tutorial - Git tutorials
+ * https://www.atlassian.com/git/workflows - Git workflows
+ * http://git-scm.com/book - The official Git book, multiple languages
+ * http://www.vogella.com/tutorials/Git/article.html - Git tutorials
+ * http://think-like-a-git.net/resources.html - Guide to Git
+ * http://gitready.com/ - medium to advanced Git docs/tips/blog/articles
+ * https://github.com/btford/participating-in-open-source - Participating in Open Source

COPYING

@@ -1,6 +1,59 @@
-Shaarli is distributed under the zlib/libpng License:
+Files: *
+License: zlib/libpng
+Copyright: (c) 2011-2015 Sébastien SAUVAGE <sebsauvage@sebsauvage.net>
+           (c) 2011-2018 The Shaarli Community, see AUTHORS
 
-Copyright (c) 2011 Sébastien SAUVAGE (sebsauvage.net)
+Files: assets/vintage/css/reset.css
+License: BSD (http://opensource.org/licenses/BSD-3-Clause)
+Copyright: (c) 2010, Yahoo! Inc.
+
+Files: assets/vintage/img/calendar.png
+       assets/vintage/img/edit_icon.png
+       assets/vintage/img/feed-icon-14x14.png
+       assets/vintage/img/private.png
+       assets/vintage/img/private_16x16.png
+       assets/vintage/img/private_16x16_active.png
+       assets/vintage/img/tag_blue.png
+License: CC-BY (http://creativecommons.org/licenses/by/3.0/)
+Copyright: (c) 2014 Yusuke Kamiyamane
+Source: http://p.yusukekamiyamane.com/
+
+Files: assets/vintage/img/delete_icon.png
+License: CC-BY (http://creativecommons.org/licenses/by/3.0/)
+Copyright: (c) 2014 Designmodo
+Source: http://designmodo.com/linecons-free/
+
+Files: assets/vintage/img/floral_left.png
+       assets/vintage/img/floral_right.png
+       assets/vintage/img/squiggle.png
+       assets/vintage/img/squiggle_closing.png
+Licence: Public Domain
+Source: https://openclipart.org/people/j4p4n/j4p4n_ornimental_bookend_-_left.svg
+
+Files: assets/vintage/img/Paper_texture_v5_by_bashcorpo_w1000.jpg
+Licence: Public Domain
+Source: http://bashcorpo.deviantart.com/art/Grungy-paper-texture-v-5-22966998
+
+Files: assets/vintage/img/logo.png
+       assets/vintage/img/logo.png
+License: zlib/libpng
+Copyright: (c) 2011-2014 idleman idleman@idleman.fr
+
+Files: assets/default/img/sad_star.png
+License: MIT License (http://opensource.org/licenses/MIT)
+Copyright: (C) 2015 kalvn - https://github.com/kalvn/Shaarli-Material
+
+Files: inc/rain.tpl.class.php
+License: LGPL-3+ (https://www.gnu.org/licenses/lgpl-3.0.txt)
+Copyright: 2011-2012, Federico Ulfo <rainelemental@gmail.com>
+           2011-2012, The Rain Team <hello@raintm.com>
+
+Files: plugins/wallabag/wallabag.png
+License: MIT License (http://opensource.org/licenses/MIT)
+Copyright: (C) 2015 Nicolas Lœuillet - https://github.com/wallabag/wallabag
+
+----------------------------------------------------
+ZLIB/LIBPNG LICENSE
 
 This software is provided 'as-is', without any express or implied warranty.
 In no event will the authors be held liable for any damages arising from
@@ -19,3 +72,721 @@ freely, subject to the following restrictions:
      not be misrepresented as being the original software.
 
   3. This notice may not be removed or altered from any source distribution.
+
+----------------------------------------------------
+GPLv3 LICENSE
+
+GNU GENERAL PUBLIC LICENSE
+
+Version 3, 29 June 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+
+Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
+Preamble
+
+The GNU General Public License is a free, copyleft license for software and other kinds of works.
+
+The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change all versions of a program--to make sure it remains free software for all its users. We, the Free Software Foundation, use the GNU General Public License for most of our software; it applies also to any other work released this way by its authors. You can apply it to your programs, too.
+
+When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things.
+
+To protect your rights, we need to prevent others from denying you these rights or asking you to surrender the rights. Therefore, you have certain responsibilities if you distribute copies of the software, or if you modify it: responsibilities to respect the freedom of others.
+
+For example, if you distribute copies of such a program, whether gratis or for a fee, you must pass on to the recipients the same freedoms that you received. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.
+
+Developers that use the GNU GPL protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License giving you legal permission to copy, distribute and/or modify it.
+
+For the developers' and authors' protection, the GPL clearly explains that there is no warranty for this free software. For both users' and authors' sake, the GPL requires that modified versions be marked as changed, so that their problems will not be attributed erroneously to authors of previous versions.
+
+Some devices are designed to deny users access to install or run modified versions of the software inside them, although the manufacturer can do so. This is fundamentally incompatible with the aim of protecting users' freedom to change the software. The systematic pattern of such abuse occurs in the area of products for individuals to use, which is precisely where it is most unacceptable. Therefore, we have designed this version of the GPL to prohibit the practice for those products. If such problems arise substantially in other domains, we stand ready to extend this provision to those domains in future versions of the GPL, as needed to protect the freedom of users.
+
+Finally, every program is threatened constantly by software patents. States should not allow patents to restrict development and use of software on general-purpose computers, but in those that do, we wish to avoid the special danger that patents applied to a free program could make it effectively proprietary. To prevent this, the GPL assures that patents cannot be used to render the program non-free.
+
+The precise terms and conditions for copying, distribution and modification follow.
+TERMS AND CONDITIONS
+0. Definitions.
+
+“This License” refers to version 3 of the GNU General Public License.
+
+“Copyright” also means copyright-like laws that apply to other kinds of works, such as semiconductor masks.
+
+“The Program” refers to any copyrightable work licensed under this License. Each licensee is addressed as “you”. “Licensees” and “recipients” may be individuals or organizations.
+
+To “modify” a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a “modified version” of the earlier work or a work “based on” the earlier work.
+
+A “covered work” means either the unmodified Program or a work based on the Program.
+
+To “propagate” a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well.
+
+To “convey” a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying.
+
+An interactive user interface displays “Appropriate Legal Notices” to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion.
+1. Source Code.
+
+The “source code” for a work means the preferred form of the work for making modifications to it. “Object code” means any non-source form of a work.
+
+A “Standard Interface” means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language.
+
+The “System Libraries” of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A “Major Component”, in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it.
+
+The “Corresponding Source” for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work's System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work.
+
+The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source.
+
+The Corresponding Source for a work in source code form is that same work.
+2. Basic Permissions.
+
+All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law.
+
+You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you.
+
+Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary.
+3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures.
+
+When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work's users, your or third parties' legal rights to forbid circumvention of technological measures.
+4. Conveying Verbatim Copies.
+
+You may convey verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program.
+
+You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee.
+5. Conveying Modified Source Versions.
+
+You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified it, and giving a relevant date.
+    b) The work must carry prominent notices stating that it is released under this License and any conditions added under section 7. This requirement modifies the requirement in section 4 to “keep intact all notices”.
+    c) You must license the entire work, as a whole, under this License to anyone who comes into possession of a copy. This License will therefore apply, along with any applicable section 7 additional terms, to the whole of the work, and all its parts, regardless of how they are packaged. This License gives no permission to license the work in any other way, but it does not invalidate such permission if you have separately received it.
+    d) If the work has interactive user interfaces, each must display Appropriate Legal Notices; however, if the Program has interactive interfaces that do not display Appropriate Legal Notices, your work need not make them do so.
+
+A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an “aggregate” if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation's users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate.
+6. Conveying Non-Source Forms.
+
+You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software interchange.
+    b) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by a written offer, valid for at least three years and valid for as long as you offer spare parts or customer support for that product model, to give anyone who possesses the object code either (1) a copy of the Corresponding Source for all the software in the product that is covered by this License, on a durable physical medium customarily used for software interchange, for a price no more than your reasonable cost of physically performing this conveying of source, or (2) access to copy the Corresponding Source from a network server at no charge.
+    c) Convey individual copies of the object code with a copy of the written offer to provide the Corresponding Source. This alternative is allowed only occasionally and noncommercially, and only if you received the object code with such an offer, in accord with subsection 6b.
+    d) Convey the object code by offering access from a designated place (gratis or for a charge), and offer equivalent access to the Corresponding Source in the same way through the same place at no further charge. You need not require recipients to copy the Corresponding Source along with the object code. If the place to copy the object code is a network server, the Corresponding Source may be on a different server (operated by you or a third party) that supports equivalent copying facilities, provided you maintain clear directions next to the object code saying where to find the Corresponding Source. Regardless of what server hosts the Corresponding Source, you remain obligated to ensure that it is available for as long as needed to satisfy these requirements.
+    e) Convey the object code using peer-to-peer transmission, provided you inform other peers where the object code and Corresponding Source of the work are being offered to the general public at no charge under subsection 6d.
+
+A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work.
+
+A “User Product” is either (1) a “consumer product”, which means any tangible personal property which is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a particular product received by a particular user, “normally used” refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product.
+
+“Installation Information” for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made.
+
+If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM).
+
+The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network.
+
+Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying.
+7. Additional Terms.
+
+“Additional permissions” are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions.
+
+When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission.
+
+Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the terms of sections 15 and 16 of this License; or
+    b) Requiring preservation of specified reasonable legal notices or author attributions in that material or in the Appropriate Legal Notices displayed by works containing it; or
+    c) Prohibiting misrepresentation of the origin of that material, or requiring that modified versions of such material be marked in reasonable ways as different from the original version; or
+    d) Limiting the use for publicity purposes of names of licensors or authors of the material; or
+    e) Declining to grant rights under trademark law for use of some trade names, trademarks, or service marks; or
+    f) Requiring indemnification of licensors and authors of that material by anyone who conveys the material (or modified versions of it) with contractual assumptions of liability to the recipient, for any liability that these contractual assumptions directly impose on those licensors and authors.
+
+All other non-permissive additional terms are considered “further restrictions” within the meaning of section 10. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license document contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or conveying.
+
+If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms.
+
+Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way.
+8. Termination.
+
+You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11).
+
+However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
+
+Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10.
+9. Acceptance Not Required for Having Copies.
+
+You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so.
+10. Automatic Licensing of Downstream Recipients.
+
+Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License.
+
+An “entity transaction” is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party's predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts.
+
+You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it.
+11. Patents.
+
+A “contributor” is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor's “contributor version”.
+
+A contributor's “essential patent claims” are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, “control” includes the right to grant patent sublicenses in a manner consistent with the requirements of this License.
+
+Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor's essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version.
+
+In the following three paragraphs, a “patent license” is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To “grant” such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party.
+
+If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the patent license to downstream recipients. “Knowingly relying” means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient's use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid.
+
+If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it.
+
+A patent license is “discriminatory” if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007.
+
+Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law.
+12. No Surrender of Others' Freedom.
+
+If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program.
+13. Use with the GNU Affero General Public License.
+
+Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU Affero General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the special requirements of the GNU Affero General Public License, section 13, concerning interaction through a network will apply to the combination as such.
+14. Revised Versions of this License.
+
+The Free Software Foundation may publish revised and/or new versions of the GNU General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU General Public License “or any later version” applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU General Public License, you may choose any version ever published by the Free Software Foundation.
+
+If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Program.
+
+Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version.
+15. Disclaimer of Warranty.
+
+THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+16. Limitation of Liability.
+
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+17. Interpretation of Sections 15 and 16.
+
+If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee.
+
+----------------------------------------------------
+MIT LICENSE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+----------------------------------------------------
+Creative Commons License (CC-BY 3.0)
+Creative Commons Legal Code
+
+Attribution 3.0 Unported
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS LICENSE DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE INFORMATION PROVIDED, AND DISCLAIMS LIABILITY FOR
+    DAMAGES RESULTING FROM ITS USE.
+
+License
+
+THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE
+COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY
+COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS
+AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED.
+
+BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE
+TO BE BOUND BY THE TERMS OF THIS LICENSE. TO THE EXTENT THIS LICENSE MAY
+BE CONSIDERED TO BE A CONTRACT, THE LICENSOR GRANTS YOU THE RIGHTS
+CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND
+CONDITIONS.
+
+1. Definitions
+
+ a. "Adaptation" means a work based upon the Work, or upon the Work and
+    other pre-existing works, such as a translation, adaptation,
+    derivative work, arrangement of music or other alterations of a
+    literary or artistic work, or phonogram or performance and includes
+    cinematographic adaptations or any other form in which the Work may be
+    recast, transformed, or adapted including in any form recognizably
+    derived from the original, except that a work that constitutes a
+    Collection will not be considered an Adaptation for the purpose of
+    this License. For the avoidance of doubt, where the Work is a musical
+    work, performance or phonogram, the synchronization of the Work in
+    timed-relation with a moving image ("synching") will be considered an
+    Adaptation for the purpose of this License.
+ b. "Collection" means a collection of literary or artistic works, such as
+    encyclopedias and anthologies, or performances, phonograms or
+    broadcasts, or other works or subject matter other than works listed
+    in Section 1(f) below, which, by reason of the selection and
+    arrangement of their contents, constitute intellectual creations, in
+    which the Work is included in its entirety in unmodified form along
+    with one or more other contributions, each constituting separate and
+    independent works in themselves, which together are assembled into a
+    collective whole. A work that constitutes a Collection will not be
+    considered an Adaptation (as defined above) for the purposes of this
+    License.
+ c. "Distribute" means to make available to the public the original and
+    copies of the Work or Adaptation, as appropriate, through sale or
+    other transfer of ownership.
+ d. "Licensor" means the individual, individuals, entity or entities that
+    offer(s) the Work under the terms of this License.
+ e. "Original Author" means, in the case of a literary or artistic work,
+    the individual, individuals, entity or entities who created the Work
+    or if no individual or entity can be identified, the publisher; and in
+    addition (i) in the case of a performance the actors, singers,
+    musicians, dancers, and other persons who act, sing, deliver, declaim,
+    play in, interpret or otherwise perform literary or artistic works or
+    expressions of folklore; (ii) in the case of a phonogram the producer
+    being the person or legal entity who first fixes the sounds of a
+    performance or other sounds; and, (iii) in the case of broadcasts, the
+    organization that transmits the broadcast.
+ f. "Work" means the literary and/or artistic work offered under the terms
+    of this License including without limitation any production in the
+    literary, scientific and artistic domain, whatever may be the mode or
+    form of its expression including digital form, such as a book,
+    pamphlet and other writing; a lecture, address, sermon or other work
+    of the same nature; a dramatic or dramatico-musical work; a
+    choreographic work or entertainment in dumb show; a musical
+    composition with or without words; a cinematographic work to which are
+    assimilated works expressed by a process analogous to cinematography;
+    a work of drawing, painting, architecture, sculpture, engraving or
+    lithography; a photographic work to which are assimilated works
+    expressed by a process analogous to photography; a work of applied
+    art; an illustration, map, plan, sketch or three-dimensional work
+    relative to geography, topography, architecture or science; a
+    performance; a broadcast; a phonogram; a compilation of data to the
+    extent it is protected as a copyrightable work; or a work performed by
+    a variety or circus performer to the extent it is not otherwise
+    considered a literary or artistic work.
+ g. "You" means an individual or entity exercising rights under this
+    License who has not previously violated the terms of this License with
+    respect to the Work, or who has received express permission from the
+    Licensor to exercise rights under this License despite a previous
+    violation.
+ h. "Publicly Perform" means to perform public recitations of the Work and
+    to communicate to the public those public recitations, by any means or
+    process, including by wire or wireless means or public digital
+    performances; to make available to the public Works in such a way that
+    members of the public may access these Works from a place and at a
+    place individually chosen by them; to perform the Work to the public
+    by any means or process and the communication to the public of the
+    performances of the Work, including by public digital performance; to
+    broadcast and rebroadcast the Work by any means including signs,
+    sounds or images.
+ i. "Reproduce" means to make copies of the Work by any means including
+    without limitation by sound or visual recordings and the right of
+    fixation and reproducing fixations of the Work, including storage of a
+    protected performance or phonogram in digital form or other electronic
+    medium.
+
+2. Fair Dealing Rights. Nothing in this License is intended to reduce,
+limit, or restrict any uses free from copyright or rights arising from
+limitations or exceptions that are provided for in connection with the
+copyright protection under copyright law or other applicable laws.
+
+3. License Grant. Subject to the terms and conditions of this License,
+Licensor hereby grants You a worldwide, royalty-free, non-exclusive,
+perpetual (for the duration of the applicable copyright) license to
+exercise the rights in the Work as stated below:
+
+ a. to Reproduce the Work, to incorporate the Work into one or more
+    Collections, and to Reproduce the Work as incorporated in the
+    Collections;
+ b. to create and Reproduce Adaptations provided that any such Adaptation,
+    including any translation in any medium, takes reasonable steps to
+    clearly label, demarcate or otherwise identify that changes were made
+    to the original Work. For example, a translation could be marked "The
+    original work was translated from English to Spanish," or a
+    modification could indicate "The original work has been modified.";
+ c. to Distribute and Publicly Perform the Work including as incorporated
+    in Collections; and,
+ d. to Distribute and Publicly Perform Adaptations.
+ e. For the avoidance of doubt:
+
+     i. Non-waivable Compulsory License Schemes. In those jurisdictions in
+        which the right to collect royalties through any statutory or
+        compulsory licensing scheme cannot be waived, the Licensor
+        reserves the exclusive right to collect such royalties for any
+        exercise by You of the rights granted under this License;
+    ii. Waivable Compulsory License Schemes. In those jurisdictions in
+        which the right to collect royalties through any statutory or
+        compulsory licensing scheme can be waived, the Licensor waives the
+        exclusive right to collect such royalties for any exercise by You
+        of the rights granted under this License; and,
+   iii. Voluntary License Schemes. The Licensor waives the right to
+        collect royalties, whether individually or, in the event that the
+        Licensor is a member of a collecting society that administers
+        voluntary licensing schemes, via that society, from any exercise
+        by You of the rights granted under this License.
+
+The above rights may be exercised in all media and formats whether now
+known or hereafter devised. The above rights include the right to make
+such modifications as are technically necessary to exercise the rights in
+other media and formats. Subject to Section 8(f), all rights not expressly
+granted by Licensor are hereby reserved.
+
+4. Restrictions. The license granted in Section 3 above is expressly made
+subject to and limited by the following restrictions:
+
+ a. You may Distribute or Publicly Perform the Work only under the terms
+    of this License. You must include a copy of, or the Uniform Resource
+    Identifier (URI) for, this License with every copy of the Work You
+    Distribute or Publicly Perform. You may not offer or impose any terms
+    on the Work that restrict the terms of this License or the ability of
+    the recipient of the Work to exercise the rights granted to that
+    recipient under the terms of the License. You may not sublicense the
+    Work. You must keep intact all notices that refer to this License and
+    to the disclaimer of warranties with every copy of the Work You
+    Distribute or Publicly Perform. When You Distribute or Publicly
+    Perform the Work, You may not impose any effective technological
+    measures on the Work that restrict the ability of a recipient of the
+    Work from You to exercise the rights granted to that recipient under
+    the terms of the License. This Section 4(a) applies to the Work as
+    incorporated in a Collection, but this does not require the Collection
+    apart from the Work itself to be made subject to the terms of this
+    License. If You create a Collection, upon notice from any Licensor You
+    must, to the extent practicable, remove from the Collection any credit
+    as required by Section 4(b), as requested. If You create an
+    Adaptation, upon notice from any Licensor You must, to the extent
+    practicable, remove from the Adaptation any credit as required by
+    Section 4(b), as requested.
+ b. If You Distribute, or Publicly Perform the Work or any Adaptations or
+    Collections, You must, unless a request has been made pursuant to
+    Section 4(a), keep intact all copyright notices for the Work and
+    provide, reasonable to the medium or means You are utilizing: (i) the
+    name of the Original Author (or pseudonym, if applicable) if supplied,
+    and/or if the Original Author and/or Licensor designate another party
+    or parties (e.g., a sponsor institute, publishing entity, journal) for
+    attribution ("Attribution Parties") in Licensor's copyright notice,
+    terms of service or by other reasonable means, the name of such party
+    or parties; (ii) the title of the Work if supplied; (iii) to the
+    extent reasonably practicable, the URI, if any, that Licensor
+    specifies to be associated with the Work, unless such URI does not
+    refer to the copyright notice or licensing information for the Work;
+    and (iv) , consistent with Section 3(b), in the case of an Adaptation,
+    a credit identifying the use of the Work in the Adaptation (e.g.,
+    "French translation of the Work by Original Author," or "Screenplay
+    based on original Work by Original Author"). The credit required by
+    this Section 4 (b) may be implemented in any reasonable manner;
+    provided, however, that in the case of a Adaptation or Collection, at
+    a minimum such credit will appear, if a credit for all contributing
+    authors of the Adaptation or Collection appears, then as part of these
+    credits and in a manner at least as prominent as the credits for the
+    other contributing authors. For the avoidance of doubt, You may only
+    use the credit required by this Section for the purpose of attribution
+    in the manner set out above and, by exercising Your rights under this
+    License, You may not implicitly or explicitly assert or imply any
+    connection with, sponsorship or endorsement by the Original Author,
+    Licensor and/or Attribution Parties, as appropriate, of You or Your
+    use of the Work, without the separate, express prior written
+    permission of the Original Author, Licensor and/or Attribution
+    Parties.
+ c. Except as otherwise agreed in writing by the Licensor or as may be
+    otherwise permitted by applicable law, if You Reproduce, Distribute or
+    Publicly Perform the Work either by itself or as part of any
+    Adaptations or Collections, You must not distort, mutilate, modify or
+    take other derogatory action in relation to the Work which would be
+    prejudicial to the Original Author's honor or reputation. Licensor
+    agrees that in those jurisdictions (e.g. Japan), in which any exercise
+    of the right granted in Section 3(b) of this License (the right to
+    make Adaptations) would be deemed to be a distortion, mutilation,
+    modification or other derogatory action prejudicial to the Original
+    Author's honor and reputation, the Licensor will waive or not assert,
+    as appropriate, this Section, to the fullest extent permitted by the
+    applicable national law, to enable You to reasonably exercise Your
+    right under Section 3(b) of this License (right to make Adaptations)
+    but not otherwise.
+
+5. Representations, Warranties and Disclaimer
+
+UNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING, LICENSOR
+OFFERS THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY
+KIND CONCERNING THE WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE,
+INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTIBILITY,
+FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF
+LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS,
+WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION
+OF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY NOT APPLY TO YOU.
+
+6. Limitation on Liability. EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE
+LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR
+ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES
+ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS
+BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+7. Termination
+
+ a. This License and the rights granted hereunder will terminate
+    automatically upon any breach by You of the terms of this License.
+    Individuals or entities who have received Adaptations or Collections
+    from You under this License, however, will not have their licenses
+    terminated provided such individuals or entities remain in full
+    compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will
+    survive any termination of this License.
+ b. Subject to the above terms and conditions, the license granted here is
+    perpetual (for the duration of the applicable copyright in the Work).
+    Notwithstanding the above, Licensor reserves the right to release the
+    Work under different license terms or to stop distributing the Work at
+    any time; provided, however that any such election will not serve to
+    withdraw this License (or any other license that has been, or is
+    required to be, granted under the terms of this License), and this
+    License will continue in full force and effect unless terminated as
+    stated above.
+
+8. Miscellaneous
+
+ a. Each time You Distribute or Publicly Perform the Work or a Collection,
+    the Licensor offers to the recipient a license to the Work on the same
+    terms and conditions as the license granted to You under this License.
+ b. Each time You Distribute or Publicly Perform an Adaptation, Licensor
+    offers to the recipient a license to the original Work on the same
+    terms and conditions as the license granted to You under this License.
+ c. If any provision of this License is invalid or unenforceable under
+    applicable law, it shall not affect the validity or enforceability of
+    the remainder of the terms of this License, and without further action
+    by the parties to this agreement, such provision shall be reformed to
+    the minimum extent necessary to make such provision valid and
+    enforceable.
+ d. No term or provision of this License shall be deemed waived and no
+    breach consented to unless such waiver or consent shall be in writing
+    and signed by the party to be charged with such waiver or consent.
+ e. This License constitutes the entire agreement between the parties with
+    respect to the Work licensed here. There are no understandings,
+    agreements or representations with respect to the Work not specified
+    here. Licensor shall not be bound by any additional provisions that
+    may appear in any communication from You. This License may not be
+    modified without the mutual written agreement of the Licensor and You.
+ f. The rights granted under, and the subject matter referenced, in this
+    License were drafted utilizing the terminology of the Berne Convention
+    for the Protection of Literary and Artistic Works (as amended on
+    September 28, 1979), the Rome Convention of 1961, the WIPO Copyright
+    Treaty of 1996, the WIPO Performances and Phonograms Treaty of 1996
+    and the Universal Copyright Convention (as revised on July 24, 1971).
+    These rights and subject matter take effect in the relevant
+    jurisdiction in which the License terms are sought to be enforced
+    according to the corresponding provisions of the implementation of
+    those treaty provisions in the applicable national law. If the
+    standard suite of rights granted under applicable copyright law
+    includes additional rights not granted under this License, such
+    additional rights are deemed to be included in the License; this
+    License is not intended to restrict the license of any rights under
+    applicable law.
+
+
+Creative Commons Notice
+
+    Creative Commons is not a party to this License, and makes no warranty
+    whatsoever in connection with the Work. Creative Commons will not be
+    liable to You or any party on any legal theory for any damages
+    whatsoever, including without limitation any general, special,
+    incidental or consequential damages arising in connection to this
+    license. Notwithstanding the foregoing two (2) sentences, if Creative
+    Commons has expressly identified itself as the Licensor hereunder, it
+    shall have all rights and obligations of Licensor.
+
+    Except for the limited purpose of indicating to the public that the
+    Work is licensed under the CCPL, Creative Commons does not authorize
+    the use by either party of the trademark "Creative Commons" or any
+    related trademark or logo of Creative Commons without the prior
+    written consent of Creative Commons. Any permitted use will be in
+    compliance with Creative Commons' then-current trademark usage
+    guidelines, as may be published on its website or otherwise made
+    available upon request from time to time. For the avoidance of doubt,
+    this trademark restriction does not form part of this License.
+
+    Creative Commons may be contacted at https://creativecommons.org/.
+
+
+
+----------------------------------------------------
+BSD License
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+------------------------------------------------------
+LGPL License
+
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

Dockerfile

@@ -0,0 +1,74 @@
+# Stage 1:
+# - Copy Shaarli sources
+# - Build documentation
+FROM python:3-alpine as docs
+ADD . /usr/src/app/shaarli
+RUN cd /usr/src/app/shaarli \
+    && apk add --no-cache gcc musl-dev make bash \
+    && make htmldoc
+
+# Stage 2:
+# - Resolve PHP dependencies with Composer
+FROM composer:latest as composer
+COPY --from=docs /usr/src/app/shaarli /app/shaarli
+RUN cd shaarli \
+    && composer --prefer-dist --no-dev install
+
+# Stage 3:
+# - Frontend dependencies
+FROM node:12-alpine as node
+COPY --from=composer /app/shaarli shaarli
+RUN cd shaarli \
+    && yarnpkg install \
+    && yarnpkg run build \
+    && rm -rf node_modules
+
+# Stage 4:
+# - Shaarli image
+FROM alpine:3.16.7
+LABEL maintainer="Shaarli Community"
+
+RUN apk --update --no-cache add \
+        ca-certificates \
+        nginx \
+        php8 \
+        php8-ctype \
+        php8-curl \
+        php8-fpm \
+        php8-gd \
+        php8-gettext \
+        php8-iconv \
+        php8-intl \
+        php8-json \
+        php8-ldap \
+        php8-mbstring \
+        php8-openssl \
+        php8-session \
+        php8-xml \
+        php8-simplexml \
+        php8-zlib \
+        s6
+
+COPY .docker/nginx.conf /etc/nginx/nginx.conf
+COPY .docker/php-fpm.conf /etc/php8/php-fpm.conf
+COPY .docker/services.d /etc/services.d
+
+RUN rm -rf /etc/php8/php-fpm.d/www.conf \
+    && sed -i 's/post_max_size.*/post_max_size = 10M/' /etc/php8/php.ini \
+    && sed -i 's/upload_max_filesize.*/upload_max_filesize = 10M/' /etc/php8/php.ini
+
+
+WORKDIR /var/www
+COPY --from=node /shaarli shaarli
+
+RUN chown -R nginx:nginx . \
+    && ln -sf /dev/stdout /var/log/nginx/shaarli.access.log \
+    && ln -sf /dev/stderr /var/log/nginx/shaarli.error.log
+
+VOLUME /var/www/shaarli/cache
+VOLUME /var/www/shaarli/data
+
+EXPOSE 80
+
+ENTRYPOINT ["/bin/s6-svscan", "/etc/services.d"]
+CMD []

Makefile

@@ -0,0 +1,215 @@
+# The personal, minimalist, super fast, database-free, bookmarking service.
+# Makefile for PHP code analysis & testing, documentation and release generation
+
+BIN = vendor/bin
+
+all: check_permissions test
+
+##
+# Docker test adapter
+#
+# Shaarli sources and vendored libraries are copied from a shared volume
+# to a user-owned directory to enable running tests as a non-root user.
+##
+docker_%:
+	rsync -az /shaarli/ ~/shaarli/
+	cd ~/shaarli && make $*
+
+##
+# PHP_CodeSniffer
+# Detects PHP syntax errors
+# Documentation (usage, output formatting):
+# - http://pear.php.net/manual/en/package.php.php-codesniffer.usage.php
+# - http://pear.php.net/manual/en/package.php.php-codesniffer.reporting.php
+##
+PHPCS := $(BIN)/phpcs
+
+# Use GNU Tar where available
+ifneq (, $(shell which gtar))
+TAR := gtar
+else
+TAR := tar
+endif
+
+code_sniffer:
+	@$(PHPCS)
+
+### - errors by Git author
+code_sniffer_blame:
+	@$(PHPCS) --report-gitblame
+
+### - all errors/warnings
+code_sniffer_full:
+	@$(PHPCS) --report-full --report-width=200
+
+### - errors grouped by kind
+code_sniffer_source:
+	@$(PHPCS) --report-source || exit 0
+
+##
+# Checks source file & script permissions
+##
+check_permissions:
+	@echo "----------------------"
+	@echo "Check file permissions"
+	@echo "----------------------"
+	@for file in `git ls-files | grep -v docker`; do \
+		if [ -x $$file ]; then \
+			errors=true; \
+			echo "$${file} is executable"; \
+		fi \
+	done; [ -z $$errors ] || false
+
+##
+# PHPUnit
+# Runs unitary and functional tests
+# Generates an HTML coverage report if Xdebug is enabled
+#
+# See phpunit.xml for configuration
+# https://phpunit.de/manual/current/en/appendixes.configuration.html
+##
+test: translate
+	@echo "-------"
+	@echo "PHPUNIT"
+	@echo "-------"
+	@mkdir -p sandbox coverage
+	@$(BIN)/phpunit --coverage-php coverage/main.cov --bootstrap tests/bootstrap.php --testsuite unit-tests
+
+locale_test_%:
+	@UT_LOCALE=$*.utf8 \
+		$(BIN)/phpunit \
+		--coverage-php coverage/$(firstword $(subst _, ,$*)).cov \
+		--bootstrap tests/languages/bootstrap.php \
+		--testsuite language-$(firstword $(subst _, ,$*))
+
+all_tests: test locale_test_de_DE locale_test_en_US locale_test_fr_FR
+	@# --The current version is not compatible with PHP 7.2
+	@#$(BIN)/phpcov merge --html coverage coverage
+	@# --text doesn't work with phpunit 4.* (v5 requires PHP 5.6)
+	@#$(BIN)/phpcov merge --text coverage/txt coverage
+
+### download 3rd-party PHP libraries, including dev dependencies
+composer_dependencies_dev: clean
+	composer install --prefer-dist
+
+##
+# Custom release archive generation
+#
+# For each tagged revision, GitHub provides tar and zip archives that correspond
+# to the output of git-archive
+#
+# These targets produce similar archives, featuring 3rd-party dependencies
+# to ease deployment on shared hosting.
+##
+ARCHIVE_VERSION := shaarli-$$(git describe)-full
+ARCHIVE_PREFIX=Shaarli/
+
+release_archive: release_tar release_zip
+
+### download 3rd-party PHP libraries
+composer_dependencies: clean
+	composer install --no-dev --prefer-dist
+	find vendor/ -name ".git" -type d -exec rm -rf {} +
+
+### download 3rd-party frontend libraries
+frontend_dependencies:
+	yarnpkg install
+
+### Build frontend dependencies
+build_frontend: frontend_dependencies
+	yarnpkg run build
+
+### generate a release tarball and include 3rd-party dependencies and translations
+release_tar: composer_dependencies htmldoc translate build_frontend
+	git archive --prefix=$(ARCHIVE_PREFIX) -o $(ARCHIVE_VERSION).tar HEAD
+	$(TAR) rvf $(ARCHIVE_VERSION).tar --transform "s|^vendor|$(ARCHIVE_PREFIX)vendor|" vendor/
+	$(TAR) rvf $(ARCHIVE_VERSION).tar --transform "s|^doc/html|$(ARCHIVE_PREFIX)doc/html|" doc/html/
+	$(TAR) rvf $(ARCHIVE_VERSION).tar --transform "s|^tpl|$(ARCHIVE_PREFIX)tpl|" tpl/
+	gzip $(ARCHIVE_VERSION).tar
+
+### generate a release zip and include 3rd-party dependencies and translations
+release_zip: composer_dependencies htmldoc translate build_frontend
+	git archive --prefix=$(ARCHIVE_PREFIX) -o $(ARCHIVE_VERSION).zip -9 HEAD
+	mkdir -p $(ARCHIVE_PREFIX)/doc
+	mkdir -p $(ARCHIVE_PREFIX)/vendor
+	rsync -a doc/html/ $(ARCHIVE_PREFIX)doc/html/
+	zip -r $(ARCHIVE_VERSION).zip $(ARCHIVE_PREFIX)doc/
+	rsync -a vendor/ $(ARCHIVE_PREFIX)vendor/
+	zip -r $(ARCHIVE_VERSION).zip $(ARCHIVE_PREFIX)vendor/
+	rsync -a tpl/ $(ARCHIVE_PREFIX)tpl/
+	zip -r $(ARCHIVE_VERSION).zip $(ARCHIVE_PREFIX)tpl/
+	rm -rf $(ARCHIVE_PREFIX)
+
+##
+# Targets for repository and documentation maintenance
+##
+
+### remove all unversioned files
+clean:
+	@git clean -df
+	@rm -rf sandbox trivy*
+
+### generate the AUTHORS file from Git commit information
+generate_authors:
+	@cp .github/mailmap .mailmap
+	@git shortlog -sne > AUTHORS
+	@rm .mailmap
+
+### generate phpDocumentor documentation
+phpdoc: clean
+	@docker run --rm -v $(PWD):/data -u `id -u`:`id -g` phpdoc/phpdoc
+
+### generate HTML documentation from Markdown pages with Sphinx
+htmldoc:
+	python3 -m venv venv/
+	bash -c 'source venv/bin/activate; \
+	pip install wheel; \
+	pip install sphinx==7.1.0 furo==2023.7.26 myst-parser sphinx-design; \
+	sphinx-build -b html -c doc/ doc/md/ doc/html/'
+	find doc/html/ -type f -exec chmod a-x '{}' \;
+	rm -r venv
+
+### Generate Shaarli's translation compiled file (.mo)
+translate:
+	@echo "----------------------"
+	@echo "Compile translation files"
+	@echo "----------------------"
+	@for pofile in `find inc/languages/ -name shaarli.po`; do \
+		echo "Compiling $$pofile"; \
+		msgfmt -v "$$pofile" -o "`dirname "$$pofile"`/`basename "$$pofile" .po`.mo"; \
+	done;
+
+### Run ESLint check against Shaarli's JS files
+eslint:
+	@yarnpkg run eslint -c .dev/.eslintrc.js assets/vintage/js/
+	@yarnpkg run eslint -c .dev/.eslintrc.js assets/default/js/
+	@yarnpkg run eslint -c .dev/.eslintrc.js assets/common/js/
+
+### Run CSSLint check against Shaarli's SCSS files
+sasslint:
+	@yarnpkg run stylelint --config .dev/.stylelintrc.js 'assets/default/scss/*.scss'
+
+##
+# Security scans
+##
+
+# trivy version (https://github.com/aquasecurity/trivy/releases)
+TRIVY_VERSION=0.44.0
+# default trivy exit code when vulnerabilities are found
+TRIVY_EXIT_CODE=1
+# default docker image to scan with trivy
+TRIVY_TARGET_DOCKER_IMAGE=ghcr.io/shaarli/shaarli:latest
+
+### download trivy vulneravbility scanner
+download_trivy:
+	wget --quiet --continue -O trivy_$(TRIVY_VERSION)_Linux-64bit.tar.gz https://github.com/aquasecurity/trivy/releases/download/v$(TRIVY_VERSION)/trivy_$(TRIVY_VERSION)_Linux-64bit.tar.gz
+	tar -z -x trivy -f trivy_$(TRIVY_VERSION)_Linux-64bit.tar.gz
+
+### run trivy vulnerability scanner on docker image
+test_trivy_docker: download_trivy
+	./trivy --exit-code $(TRIVY_EXIT_CODE) image $(TRIVY_TARGET_DOCKER_IMAGE)
+
+### run trivy vulnerability scanner on composer/yarn dependency trees
+test_trivy_repo: download_trivy
+	./trivy --exit-code $(TRIVY_EXIT_CODE) fs composer.lock
+	./trivy --exit-code $(TRIVY_EXIT_CODE) fs yarn.lock

README.md

@@ -1,95 +1,31 @@
-![Shaarli logo](http://sebsauvage.net/wiki/lib/exe/fetch.php?media=php:php_shaarli:php_shaarli_logo_inkscape_w600_transp-nq8.png)
+![Shaarli logo](doc/md/images/doc-logo.png)
 
-Shaarli, the personal, minimalist, super-fast, no-database delicious clone.
+The personal, minimalist, super fast, database-free, bookmarking service.
 
-You want to share the links you discover ? Shaarli is a minimalist delicious clone you can install on your own website.
+_Do you want to share the links you discover?_
-It is designed to be personal (single-user), fast and handy.
+_Shaarli is a minimalist link sharing service that you can install on your own server._
+_It is designed to be personal (single-user), fast and handy._
 
+[![](https://img.shields.io/badge/stable-v0.12.2-blue.svg)](https://github.com/shaarli/Shaarli/releases/tag/v0.11.1)
+[![](https://img.shields.io/badge/latest-v0.13.0-blue.svg)](https://github.com/shaarli/Shaarli/releases/tag/v0.12.2)
+[![](https://img.shields.io/badge/master-v0.13.x-blue.svg)](https://github.com/shaarli/Shaarli)
+[![](https://github.com/shaarli/Shaarli/actions/workflows/ci.yml/badge.svg)](https://github.com/shaarli/Shaarli/actions)
+[![Join the chat at https://gitter.im/shaarli/Shaarli](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/shaarli/Shaarli)
+[![Docker repository](https://img.shields.io/docker/pulls/shaarli/shaarli.svg)](https://github.com/shaarli/Shaarli/pkgs/container/shaarli)
 
-Features:
+## Quickstart
 
- * Minimalist design (simple is beautiful)
+- [Documentation](https://shaarli.readthedocs.io)
- * **FAST**
+- [Change log](CHANGELOG.md)
- * Dead-simple installation: Drop the files, open the page. No database required.
+- [Bugs/Feature requests/Discussion](https://github.com/shaarli/Shaarli/issues/)
- * Easy to use: Single button in your browser to bookmark a page
- * Save url, title, description (unlimited size). Classify links with tags (with autocomplete)
- * Tag renaming, merging and deletion.
- * Automatic thumbnails for various services (imgur, imageshack.us, flickr, youtube, vimeo, dailymotion…)
- * Automatic conversion of URLs to clickable links in descriptions. Support for http/ftp/file/apt/magnet protocols.
- * Save links as public or private
- * 1-clic access to your private links/notes
- * Browse links by page, filter by tag or use the full text search engine
- * Permalinks (with QR-Code) for easy reference
- * RSS and ATOM feeds (which can be filtered by tag or text search)
- * Tag cloud
- * Picture wall (which can be filtered by tag or text search)
- * “Links of the day” Newspaper-like digest, browsable by day.
- * “Daily” RSS feed: Get each day a digest of all new links.
- * [PubSubHubbub](https://code.google.com/p/pubsubhubbub/) protocol support
- * Easy backup (Data stored in a single file)
- * Compact storage (1320 links stored in 299 ko)
- * Mobile browsers support
- * Also works with javascript disabled
- * Can import/export Netscape bookmarks (for import/export from/to Firefox, Opera, Chrome, Delicious…)
- * Brute force protected login form
- * Protected against [XSRF](http://en.wikipedia.org/wiki/Cross-site_request_forgery), session cookie hijacking.
- * Automatic removal of annoying FeedBurner/Google FeedProxy parameters in URL (?utm_source…)
- * Shaarli is a bookmarking application, but you can use it for micro-blogging (like Twitter), a pastebin, an online notepad, a snippet repository, etc.
- * You will be automatically notified by a discreet popup if a new version is available
- * Pages are easy to customize (using CSS and simple RainTPL templates)
 
-More information on the project page:
+### Demo
-http://sebsauvage.net/wiki/doku.php?id=php:shaarli
 
-![my Shaarli logo](http://img.knah-tsaeb.org/photos/shaarli/logo_fullsize.png)
+You can use this [public demo instance of Shaarli](https://demo.shaarli.org).
+It runs the latest development version of Shaarli and is updated/reset daily.
 
-myShaarli Features :
+Login: `demo`; Password: `demo`
 
- * Markdown support (web+RSS+Atom)
+### License
- * Define external thumbnailer
- * Add favicon
- * Better configuration page
- * Template support
- * Add extra field for origin of link
- * New default theme
- * Add link to archive.org (qwertygc https://github.com/nodiscc/Shaarli/commit/b113dc8e6bba052883297ab575dd36fd3073805e)
- * myShaali can use Firefox social API (Marsup https://github.com/shaarli/Shaarli/commit/d33c5d4c3b9c70441391a08e8bcb2a8c639a4635)
- * myShaali can post original article to Wallabag (v1/v2)(nodiscc https://github.com/nodiscc/Shaarli/tree/new-plugin-system/tpl/plugins/wallabag)
- * myShaali implement OpenSearch (ArthurHoaro https://github.com/shaarli/Shaarli/issues/176)
- * Few small fix
- * You can upgrade original Shaarli to myShaarli without lost your data
- * You can define url origin of update
- * Change date/time format
 
-More information on the project page:
+Shaarli is [Free Software](http://en.wikipedia.org/wiki/Free_software). See [COPYING](COPYING) for a detail of the contributors and licenses for each individual component.
-https://forge.leslibres.org/Knah-Tsaeb/MyShaarli
-
-
-Requires php 5.1
-
-
-------------------------------------------------------------------------------
-
-Shaarli is distributed under the zlib/libpng License:
-
-Copyright (c) 2011 Sébastien SAUVAGE (sebsauvage.net)
-
-This software is provided 'as-is', without any express or implied warranty.
-In no event will the authors be held liable for any damages arising from
-the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-  1. The origin of this software must not be misrepresented; you must not
-     claim that you wrote the original software. If you use this software
-     in a product, an acknowledgment in the product documentation would
-     be appreciated but is not required.
-
-  2. Altered source versions must be plainly marked as such, and must
-     not be misrepresented as being the original software.
-
-  3. This notice may not be removed or altered from any source distribution.
-
-------------------------------------------------------------------------------

application/.htaccess

@@ -0,0 +1,13 @@
+<IfModule version_module>
+  <IfVersion >= 2.4>
+     Require all denied
+  </IfVersion>
+  <IfVersion < 2.4>
+     Allow from none
+     Deny from all
+  </IfVersion>
+</IfModule>
+
+<IfModule !version_module>
+    Require all denied
+</IfModule>

application/History.php

@@ -0,0 +1,223 @@
+<?php
+
+namespace Shaarli;
+
+use DateTime;
+use Exception;
+use Shaarli\Bookmark\Bookmark;
+use Shaarli\Helper\FileUtils;
+
+/**
+ * Class History
+ *
+ * Handle the history file tracing events in Shaarli.
+ * The history is stored as JSON in a file set by 'resource.history' setting.
+ *
+ * Available data:
+ *   - event: event key
+ *   - datetime: event date, in ISO8601 format.
+ *   - id: event item identifier (currently only link IDs).
+ *
+ * Available event keys:
+ *   - CREATED: new link
+ *   - UPDATED: link updated
+ *   - DELETED: link deleted
+ *   - SETTINGS: the settings have been updated through the UI.
+ *   - IMPORT: bulk bookmarks import
+ *
+ * Note: new events are put at the beginning of the file and history array.
+ */
+class History
+{
+    /**
+     * @var string Action key: a new link has been created.
+     */
+    public const CREATED = 'CREATED';
+
+    /**
+     * @var string Action key: a link has been updated.
+     */
+    public const UPDATED = 'UPDATED';
+
+    /**
+     * @var string Action key: a link has been deleted.
+     */
+    public const DELETED = 'DELETED';
+
+    /**
+     * @var string Action key: settings have been updated.
+     */
+    public const SETTINGS = 'SETTINGS';
+
+    /**
+     * @var string Action key: a bulk import has been processed.
+     */
+    public const IMPORT = 'IMPORT';
+
+    /**
+     * @var string History file path.
+     */
+    protected $historyFilePath;
+
+    /**
+     * @var array History data.
+     */
+    protected $history;
+
+    /**
+     * @var int History retention time in seconds (1 month).
+     */
+    protected $retentionTime = 2678400;
+
+    /**
+     * History constructor.
+     *
+     * @param string $historyFilePath History file path.
+     * @param int    $retentionTime   History content retention time in seconds.
+     *
+     * @throws Exception if something goes wrong.
+     */
+    public function __construct($historyFilePath, $retentionTime = null)
+    {
+        $this->historyFilePath = $historyFilePath;
+        if ($retentionTime !== null) {
+            $this->retentionTime = $retentionTime;
+        }
+    }
+
+    /**
+     * Initialize: read history file.
+     *
+     * Allow lazy loading (don't read the file if it isn't necessary).
+     */
+    protected function initialize()
+    {
+        $this->check();
+        $this->read();
+    }
+
+    /**
+     * Add Event: new link.
+     *
+     * @param Bookmark $link Link data.
+     */
+    public function addLink($link)
+    {
+        $this->addEvent(self::CREATED, $link->getId());
+    }
+
+    /**
+     * Add Event: update existing link.
+     *
+     * @param Bookmark $link Link data.
+     */
+    public function updateLink($link)
+    {
+        $this->addEvent(self::UPDATED, $link->getId());
+    }
+
+    /**
+     * Add Event: delete existing link.
+     *
+     * @param Bookmark $link Link data.
+     */
+    public function deleteLink($link)
+    {
+        $this->addEvent(self::DELETED, $link->getId());
+    }
+
+    /**
+     * Add Event: settings updated.
+     */
+    public function updateSettings()
+    {
+        $this->addEvent(self::SETTINGS);
+    }
+
+    /**
+     * Add Event: bulk import.
+     *
+     * Note: we don't store bookmarks add/update one by one since it can have a huge impact on performances.
+     */
+    public function importLinks()
+    {
+        $this->addEvent(self::IMPORT);
+    }
+
+    /**
+     * Save a new event and write it in the history file.
+     *
+     * @param string $status Event key, should be defined as constant.
+     * @param mixed  $id     Event item identifier (e.g. link ID).
+     */
+    protected function addEvent($status, $id = null)
+    {
+        if ($this->history === null) {
+            $this->initialize();
+        }
+
+        $item = [
+            'event' => $status,
+            'datetime' => new DateTime(),
+            'id' => $id !== null ? $id : '',
+        ];
+        $this->history = array_merge([$item], $this->history);
+        $this->write();
+    }
+
+    /**
+     * Check that the history file is writable.
+     * Create the file if it doesn't exist.
+     *
+     * @throws Exception if it isn't writable.
+     */
+    protected function check()
+    {
+        if (!is_file($this->historyFilePath)) {
+            FileUtils::writeFlatDB($this->historyFilePath, []);
+        }
+
+        if (!is_writable($this->historyFilePath)) {
+            throw new Exception(t('History file isn\'t readable or writable'));
+        }
+    }
+
+    /**
+     * Read JSON history file.
+     */
+    protected function read()
+    {
+        $this->history = FileUtils::readFlatDB($this->historyFilePath, []);
+        if ($this->history === false) {
+            throw new Exception(t('Could not parse history file'));
+        }
+    }
+
+    /**
+     * Write JSON history file and delete old entries.
+     */
+    protected function write()
+    {
+        $comparaison = new DateTime('-' . $this->retentionTime . ' seconds');
+        foreach ($this->history as $key => $value) {
+            if ($value['datetime'] < $comparaison) {
+                unset($this->history[$key]);
+            }
+        }
+        FileUtils::writeFlatDB($this->historyFilePath, array_values($this->history));
+    }
+
+    /**
+     * Get the History.
+     *
+     * @return array
+     */
+    public function getHistory()
+    {
+        if ($this->history === null) {
+            $this->initialize();
+        }
+
+        return $this->history;
+    }
+}

application/Languages.php

@@ -0,0 +1,193 @@
+<?php
+
+namespace Shaarli;
+
+use Gettext\GettextTranslator;
+use Gettext\Translations;
+use Gettext\Translator;
+use Gettext\TranslatorInterface;
+use Shaarli\Config\ConfigManager;
+
+/**
+ * Class Languages
+ *
+ * Load Shaarli translations using 'gettext/gettext'.
+ * This class allows to either use PHP gettext extension, or a PHP implementation of gettext,
+ * with a fixed language, or dynamically using autoLocale().
+ *
+ * Translation files PO/MO files follow gettext standard and must be placed under:
+ *   <translation path>/<language>/LC_MESSAGES/<domain>.[po|mo]
+ *
+ * Pros/cons:
+ *   - gettext extension is faster
+ *   - gettext is very system dependent (PHP extension, the locale must be installed, and web server reloaded)
+ *
+ * Settings:
+ *   - translation.mode:
+ *     - auto: use default setting (PHP implementation)
+ *     - php: use PHP implementation
+ *     - gettext: use gettext wrapper
+ *   - translation.language:
+ *     - auto: use autoLocale() and the language change according to user HTTP headers
+ *     - fixed language: e.g. 'fr'
+ *   - translation.extensions:
+ *     - domain => translation_path: allow plugins and themes to extend the defaut extension
+ *       The domain must be unique, and translation path must be relative, and contains the tree mentioned above.
+ *
+ * @package Shaarli
+ */
+class Languages
+{
+    /**
+     * Core translations domain
+     */
+    public const DEFAULT_DOMAIN = 'shaarli';
+
+    /**
+     * @var TranslatorInterface
+     */
+    protected $translator;
+
+    /**
+     * @var string
+     */
+    protected $language;
+
+    /**
+     * @var ConfigManager
+     */
+    protected $conf;
+
+    /**
+     * Languages constructor.
+     *
+     * @param string        $language lang determined by autoLocale(), can be overridden.
+     * @param ConfigManager $conf     instance.
+     */
+    public function __construct($language, $conf)
+    {
+        $this->conf = $conf;
+        $confLanguage = $this->conf->get('translation.language', 'auto');
+        // Auto mode or invalid parameter, use the detected language.
+        // If the detected language is invalid, it doesn't matter, it will use English.
+        if ($confLanguage === 'auto' || ! $this->isValidLanguage($confLanguage)) {
+            $this->language = substr($language, 0, 5);
+        } else {
+            $this->language = $confLanguage;
+        }
+
+        if (
+            ! extension_loaded('gettext')
+            || in_array($this->conf->get('translation.mode', 'auto'), ['auto', 'php'])
+        ) {
+            $this->initPhpTranslator();
+        } else {
+            $this->initGettextTranslator();
+        }
+
+        // Register default functions (e.g. '__()') to use our Translator
+        $this->translator->register();
+    }
+
+    /**
+     * Initialize the translator using php gettext extension (gettext dependency act as a wrapper).
+     */
+    protected function initGettextTranslator()
+    {
+        $this->translator = new GettextTranslator();
+        $this->translator->setLanguage($this->language);
+        $this->translator->loadDomain(self::DEFAULT_DOMAIN, 'inc/languages');
+
+        // Default extension translation from the current theme
+        $themeTransFolder = rtrim($this->conf->get('raintpl_tpl'), '/') . '/' . $this->conf->get('theme') . '/language';
+        if (is_dir($themeTransFolder)) {
+            $this->translator->loadDomain($this->conf->get('theme'), $themeTransFolder, false);
+        }
+
+        foreach ($this->conf->get('translation.extensions', []) as $domain => $translationPath) {
+            if ($domain !== self::DEFAULT_DOMAIN) {
+                $this->translator->loadDomain($domain, $translationPath, false);
+            }
+        }
+    }
+
+    /**
+     * Initialize the translator using a PHP implementation of gettext.
+     *
+     * Note that if language po file doesn't exist, errors are ignored (e.g. not installed language).
+     */
+    protected function initPhpTranslator()
+    {
+        $this->translator = new Translator();
+        $translations = new Translations();
+        // Core translations
+        try {
+            $translations = $translations->addFromPoFile(
+                'inc/languages/' . $this->language . '/LC_MESSAGES/shaarli.po'
+            );
+            $translations->setDomain('shaarli');
+            $this->translator->loadTranslations($translations);
+        } catch (\InvalidArgumentException $e) {
+        }
+
+        // Default extension translation from the current theme
+        $theme = $this->conf->get('theme');
+        $themeTransFolder = rtrim($this->conf->get('raintpl_tpl'), '/') . '/' . $theme . '/language';
+        if (is_dir($themeTransFolder)) {
+            try {
+                $translations = Translations::fromPoFile(
+                    $themeTransFolder . '/' . $this->language . '/LC_MESSAGES/' . $theme . '.po'
+                );
+                $translations->setDomain($theme);
+                $this->translator->loadTranslations($translations);
+            } catch (\InvalidArgumentException $e) {
+            }
+        }
+
+        // Extension translations (plugins, themes, etc.).
+        foreach ($this->conf->get('translation.extensions', []) as $domain => $translationPath) {
+            if ($domain === self::DEFAULT_DOMAIN) {
+                continue;
+            }
+
+            try {
+                $extension = Translations::fromPoFile(
+                    $translationPath . $this->language . '/LC_MESSAGES/' . $domain . '.po'
+                );
+                $extension->setDomain($domain);
+                $this->translator->loadTranslations($extension);
+            } catch (\InvalidArgumentException $e) {
+            }
+        }
+    }
+
+    /**
+     * Checks if a language string is valid.
+     *
+     * @param string $language e.g. 'fr' or 'en_US'
+     *
+     * @return bool true if valid, false otherwise
+     */
+    protected function isValidLanguage($language)
+    {
+        return preg_match('/^[a-z]{2}(_[A-Z]{2})?/', $language) === 1;
+    }
+
+    /**
+     * Get the list of available languages for Shaarli.
+     *
+     * @return array List of available languages, with their label.
+     */
+    public static function getAvailableLanguages()
+    {
+        return [
+            'auto' => t('Automatic'),
+            'de' => t('German'),
+            'en' => t('English'),
+            'fr' => t('French'),
+            'jp' => t('Japanese'),
+            'ru' => t('Russian'),
+            'zh_CN' => t('Chinese (Simplified)'),
+        ];
+    }
+}

application/Thumbnailer.php

@@ -0,0 +1,131 @@
+<?php
+
+namespace Shaarli;
+
+use Shaarli\Config\ConfigManager;
+use WebThumbnailer\Application\ConfigManager as WTConfigManager;
+use WebThumbnailer\WebThumbnailer;
+
+/**
+ * Class Thumbnailer
+ *
+ * Utility class used to retrieve thumbnails using web-thumbnailer dependency.
+ */
+class Thumbnailer
+{
+    protected const COMMON_MEDIA_DOMAINS = [
+        'imgur.com',
+        'flickr.com',
+        'youtube.com',
+        'wikimedia.org',
+        'redd.it',
+        'gfycat.com',
+        'media.giphy.com',
+        'twitter.com',
+        'twimg.com',
+        'instagram.com',
+        'pinterest.com',
+        'pinterest.fr',
+        'soundcloud.com',
+        'tumblr.com',
+        'deviantart.com',
+    ];
+
+    public const MODE_ALL = 'all';
+    public const MODE_COMMON = 'common';
+    public const MODE_NONE = 'none';
+
+    /**
+     * @var WebThumbnailer instance.
+     */
+    protected $wt;
+
+    /**
+     * @var ConfigManager instance.
+     */
+    protected $conf;
+
+    /**
+     * Thumbnailer constructor.
+     *
+     * @param ConfigManager $conf instance.
+     */
+    public function __construct($conf)
+    {
+        $this->conf = $conf;
+
+        if (! $this->checkRequirements()) {
+            $this->conf->set('thumbnails.mode', Thumbnailer::MODE_NONE);
+            $this->conf->write(true);
+            // TODO: create a proper error handling system able to catch exceptions...
+            die(t(
+                'php-gd extension must be loaded to use thumbnails. '
+                . 'Thumbnails are now disabled. Please reload the page.'
+            ));
+        }
+
+        $this->wt = new WebThumbnailer();
+        WTConfigManager::addFile('inc/web-thumbnailer.json');
+        $this->wt->maxWidth($this->conf->get('thumbnails.width'))
+                 ->maxHeight($this->conf->get('thumbnails.height'))
+                 ->crop(true)
+                 ->debug($this->conf->get('dev.debug', false));
+    }
+
+    /**
+     * Retrieve a thumbnail for given URL
+     *
+     * @param string $url where to look for a thumbnail.
+     *
+     * @return bool|string The thumbnail relative cache file path, or false if none has been found.
+     */
+    public function get($url)
+    {
+        if (
+            $this->conf->get('thumbnails.mode') === self::MODE_COMMON
+            && ! $this->isCommonMediaOrImage($url)
+        ) {
+            return false;
+        }
+
+        try {
+            return $this->wt->thumbnail($url);
+        } catch (\Throwable $e) {
+            // Exceptions are only thrown in debug mode.
+            error_log(get_class($e) . ': ' . $e->getMessage());
+        }
+        return false;
+    }
+
+    /**
+     * We check weather the given URL is from a common media domain,
+     * or if the file extension is an image.
+     *
+     * @param string $url to check
+     *
+     * @return bool true if it's an image or from a common media domain, false otherwise.
+     */
+    public function isCommonMediaOrImage($url)
+    {
+        foreach (self::COMMON_MEDIA_DOMAINS as $domain) {
+            if (strpos($url, $domain) !== false) {
+                return true;
+            }
+        }
+
+        if (endsWith($url, '.jpg') || endsWith($url, '.png') || endsWith($url, '.jpeg')) {
+            return true;
+        }
+
+        return false;
+    }
+
+    /**
+     * Make sure that requirements are match to use thumbnails:
+     *   - php-gd is loaded
+     */
+    protected function checkRequirements()
+    {
+        return extension_loaded('gd');
+    }
+}

application/TimeZone.php

@@ -0,0 +1,92 @@
+<?php
+
+/**
+ * Generates a list of available timezone continents and cities.
+ *
+ * Two distinct array based on available timezones
+ * and the one selected in the settings:
+ *   - (0) continents:
+ *     + list of available continents
+ *     + special key 'selected' containing the value of the selected timezone's continent
+ *   - (1) cities:
+ *     + list of available cities associated with their continent
+ *     + special key 'selected' containing the value of the selected timezone's city (without the continent)
+ *
+ * Example:
+ *   [
+ *     [
+ *       'America',
+ *       'Europe',
+ *       'selected' => 'Europe',
+ *     ],
+ *     [
+ *       ['continent' => 'America', 'city' => 'Toronto'],
+ *       ['continent' => 'Europe', 'city' => 'Paris'],
+ *       'selected' => 'Paris',
+ *     ],
+ *   ];
+ *
+ * Notes:
+ *   - 'UTC/UTC' is mapped to 'UTC' to form a valid option
+ *   - a few timezone cities includes the country/state, such as Argentina/Buenos_Aires
+ *   - these arrays are designed to build timezone selects in template files with any HTML structure
+ *
+ * @param array  $installedTimeZones  List of installed timezones as string
+ * @param string $preselectedTimezone preselected timezone (optional)
+ *
+ * @return array[] continents and cities
+ **/
+function generateTimeZoneData($installedTimeZones, $preselectedTimezone = '')
+{
+    if ($preselectedTimezone == 'UTC') {
+        $pcity = $pcontinent = 'UTC';
+    } else {
+        // Try to split the provided timezone
+        $spos = strpos($preselectedTimezone, '/');
+        $pcontinent = substr($preselectedTimezone, 0, $spos);
+        $pcity = substr($preselectedTimezone, $spos + 1);
+    }
+
+    $continents = [];
+    $cities = [];
+    foreach ($installedTimeZones as $tz) {
+        if ($tz == 'UTC') {
+            $tz = 'UTC/UTC';
+        }
+        $spos = strpos($tz, '/');
+
+        // Ignore invalid timezones
+        if ($spos === false) {
+            continue;
+        }
+
+        $continent = substr($tz, 0, $spos);
+        $city = substr($tz, $spos + 1);
+        $cities[] = ['continent' => $continent, 'city' => $city];
+        $continents[$continent] = true;
+    }
+
+    $continents = array_keys($continents);
+    $continents['selected'] = $pcontinent;
+    $cities['selected'] = $pcity;
+
+    return [$continents, $cities];
+}
+
+/**
+ * Tells if a continent/city pair form a valid timezone
+ *
+ * Note: 'UTC/UTC' is mapped to 'UTC'
+ *
+ * @param string $continent the timezone continent
+ * @param string $city      the timezone city
+ *
+ * @return bool whether continent/city is a valid timezone
+ */
+function isTimeZoneValid($continent, $city)
+{
+    return in_array(
+        $continent . '/' . $city,
+        timezone_identifiers_list()
+    );
+}

application/Utils.php

@@ -0,0 +1,505 @@
+<?php
+
+/**
+ * Shaarli utilities
+ */
+
+/**
+ * Format log using provided data.
+ *
+ * @param string      $message  the message to log
+ * @param string|null $clientIp the client's remote IPv4/IPv6 address
+ *
+ * @return string Formatted message to log
+ */
+function format_log(string $message, string $clientIp = null): string
+{
+    $out = $message;
+
+    if (!empty($clientIp)) {
+        // Note: we keep the first dash to avoid breaking fail2ban configs
+        $out = '- ' . $clientIp . ' - ' . $out;
+    }
+
+    return $out;
+}
+
+/**
+ *  Returns the small hash of a string, using RFC 4648 base64url format
+ *
+ *  Small hashes:
+ *   - are unique (well, as unique as crc32, at last)
+ *   - are always 6 characters long.
+ *   - only use the following characters: a-z A-Z 0-9 - _ @
+ *   - are NOT cryptographically secure (they CAN be forged)
+ *
+ *  In Shaarli, they are used as a tinyurl-like link to individual entries,
+ *  built once with the combination of the date and item ID.
+ *  e.g. smallHash('20111006_131924' . 142) --> eaWxtQ
+ *
+ * @warning before v0.8.1, smallhashes were built only with the date,
+ *          and their value has been preserved.
+ *
+ * @param string $text Create a hash from this text.
+ *
+ * @return string generated small hash.
+ */
+function smallHash($text)
+{
+    $t = rtrim(base64_encode(hash('crc32', $text, true)), '=');
+    return strtr($t, '+/', '-_');
+}
+
+/**
+ * Tells if a string start with a substring
+ *
+ * @param string $haystack Given string.
+ * @param string $needle   String to search at the beginning of $haystack.
+ * @param bool   $case     Case sensitive.
+ *
+ * @return bool True if $haystack starts with $needle.
+ */
+function startsWith($haystack, $needle, $case = true)
+{
+    $needle = $needle ?? '';
+    if ($case) {
+        return (strcmp(substr($haystack, 0, strlen($needle)), $needle) === 0);
+    }
+    return (strcasecmp(substr($haystack, 0, strlen($needle)), $needle) === 0);
+}
+
+/**
+ * Tells if a string ends with a substring
+ *
+ * @param string $haystack Given string.
+ * @param string $needle   String to search at the end of $haystack.
+ * @param bool   $case     Case sensitive.
+ *
+ * @return bool True if $haystack ends with $needle.
+ */
+function endsWith($haystack, $needle, $case = true)
+{
+    if ($case) {
+        return (strcmp(substr($haystack, strlen($haystack) - strlen($needle)), $needle) === 0);
+    }
+    return (strcasecmp(substr($haystack, strlen($haystack) - strlen($needle)), $needle) === 0);
+}
+
+/**
+ * Htmlspecialchars wrapper
+ * Support multidimensional array of strings.
+ *
+ * @param mixed $input Data to escape: a single string or an array of strings.
+ *
+ * @return string|array escaped.
+ */
+function escape($input)
+{
+    if (null === $input) {
+        return null;
+    }
+
+    if (is_bool($input) || is_int($input) || is_float($input) || $input instanceof DateTimeInterface) {
+        return $input;
+    }
+
+    if (is_array($input)) {
+        $out = [];
+        foreach ($input as $key => $value) {
+            $out[escape($key)] = escape($value);
+        }
+        return $out;
+    }
+    return htmlspecialchars($input, ENT_COMPAT, 'UTF-8', false);
+}
+
+/**
+ * Reverse the escape function.
+ *
+ * @param string $str the string to unescape.
+ *
+ * @return string unescaped string.
+ */
+function unescape($str)
+{
+    return htmlspecialchars_decode($str);
+}
+
+/**
+ * Sanitize link before rendering.
+ *
+ * @param array $link Link to escape.
+ */
+function sanitizeLink(&$link)
+{
+    $link['url'] = escape($link['url']); // useful?
+    $link['title'] = escape($link['title']);
+    $link['description'] = escape($link['description']);
+    $link['tags'] = escape($link['tags']);
+}
+
+/**
+ * Checks if a string represents a valid date
+
+ * @param string $format The expected DateTime format of the string
+ * @param string $string A string-formatted date
+ *
+ * @return bool whether the string is a valid date
+ *
+ * @see http://php.net/manual/en/class.datetime.php
+ * @see http://php.net/manual/en/datetime.createfromformat.php
+ */
+function checkDateFormat($format, $string)
+{
+    $date = DateTime::createFromFormat($format, $string);
+    return $date && $date->format($string) == $string;
+}
+
+/**
+ * Generate a header location from HTTP_REFERER.
+ * Make sure the referer is Shaarli itself and prevent redirection loop.
+ *
+ * @param string $referer - HTTP_REFERER.
+ * @param string $host - Server HOST.
+ * @param array $loopTerms - Contains list of term to prevent redirection loop.
+ *
+ * @return string $referer - final referer.
+ */
+function generateLocation($referer, $host, $loopTerms = [])
+{
+    $finalReferer = './?';
+
+    // No referer if it contains any value in $loopCriteria.
+    foreach (array_filter($loopTerms) as $value) {
+        if (strpos($referer, $value) !== false) {
+            return $finalReferer;
+        }
+    }
+
+    // Remove port from HTTP_HOST
+    if ($pos = strpos($host, ':')) {
+        $host = substr($host, 0, $pos);
+    }
+
+    $refererHost = parse_url($referer, PHP_URL_HOST) ?? '';
+    if (!empty($referer) && (strpos($refererHost, $host) !== false || startsWith('?', $refererHost))) {
+        $finalReferer = $referer;
+    }
+
+    return $finalReferer;
+}
+
+/**
+ * Sniff browser language to set the locale automatically.
+ * Note that is may not work on your server if the corresponding locale is not installed.
+ *
+ * @param string $headerLocale Locale send in HTTP headers (e.g. "fr,fr-fr;q=0.8,en;q=0.5,en-us;q=0.3").
+ **/
+function autoLocale($headerLocale)
+{
+    // Default if browser does not send HTTP_ACCEPT_LANGUAGE
+    $locales = ['en_US.UTF-8', 'en_US.utf8', 'en_US'];
+    if (! empty($headerLocale)) {
+        if (preg_match_all('/([a-z]{2,3})[-_]?([a-z]{2})?,?/i', $headerLocale, $matches, PREG_SET_ORDER)) {
+            $attempts = [];
+            foreach ($matches as $match) {
+                $first = [strtolower($match[1]), strtoupper($match[1])];
+                $separators = ['_', '-'];
+                $encodings = ['utf8', 'UTF-8'];
+                if (!empty($match[2])) {
+                    $second = [strtoupper($match[2]), strtolower($match[2])];
+                    $items = [$first, $separators, $second, ['.'], $encodings];
+                } else {
+                    $items = [$first, $separators, $first, ['.'], $encodings];
+                }
+                $attempts = array_merge($attempts, iterator_to_array(cartesian_product_generator($items)));
+            }
+
+            if (! empty($attempts)) {
+                $locales = array_merge(array_map('implode', $attempts), $locales);
+            }
+        }
+    }
+
+    setlocale(LC_ALL, $locales);
+}
+
+/**
+ * Build a Generator object representing the cartesian product from given $items.
+ *
+ * Example:
+ *   [['a'], ['b', 'c']]
+ * will generate:
+ *   [
+ *      ['a', 'b'],
+ *      ['a', 'c'],
+ *   ]
+ *
+ * @param array $items array of array of string
+ *
+ * @return Generator representing the cartesian product of given array.
+ *
+ * @see https://en.wikipedia.org/wiki/Cartesian_product
+ */
+function cartesian_product_generator($items)
+{
+    if (empty($items)) {
+        yield [];
+    }
+    $subArray = array_pop($items);
+    if (empty($subArray)) {
+        return;
+    }
+    foreach (cartesian_product_generator($items) as $item) {
+        foreach ($subArray as $value) {
+            yield $item + [count($item) => $value];
+        }
+    }
+}
+
+/**
+ * Generates a default API secret.
+ *
+ * Note that the random-ish methods used in this function are predictable,
+ * which makes them NOT suitable for crypto.
+ * BUT the random string is salted with the salt and hashed with the username.
+ * It makes the generated API secret secured enough for Shaarli.
+ *
+ * PHP 7 provides random_int(), designed for cryptography.
+ * More info: http://stackoverflow.com/questions/4356289/php-random-string-generator
+
+ * @param string $username Shaarli login username
+ * @param string $salt     Shaarli password hash salt
+ *
+ * @return string|bool Generated API secret, 12 char length.
+ *                     Or false if invalid parameters are provided (which will make the API unusable).
+ */
+function generate_api_secret($username, $salt)
+{
+    if (empty($username) || empty($salt)) {
+        return false;
+    }
+
+    return str_shuffle(substr(hash_hmac('sha512', uniqid($salt), $username), 10, 12));
+}
+
+/**
+ * Trim string, replace sequences of whitespaces by a single space.
+ * PHP equivalent to `normalize-space` XSLT function.
+ *
+ * @param string $string Input string.
+ *
+ * @return mixed Normalized string.
+ */
+function normalize_spaces($string)
+{
+    return preg_replace('/\s{2,}/', ' ', trim($string ?? ''));
+}
+
+/**
+ * Format the date according to the locale.
+ *
+ * Requires php-intl to display international datetimes,
+ * otherwise default format '%c' will be returned.
+ *
+ * @param DateTimeInterface $date to format.
+ * @param bool              $time Displays time if true.
+ * @param bool              $intl Use international format if true.
+ *
+ * @return bool|string Formatted date, or false if the input is invalid.
+ */
+function format_date($date, $time = true, $intl = true)
+{
+    if (! $date instanceof DateTimeInterface) {
+        return false;
+    }
+
+    if (! $intl || ! class_exists('IntlDateFormatter')) {
+        $format = 'F j, Y';
+        if ($time) {
+            $format .= ' h:i:s A \G\M\TP';
+        }
+        return $date->format($format);
+    }
+    $formatter = new IntlDateFormatter(
+        setlocale(LC_TIME, 0),
+        IntlDateFormatter::LONG,
+        $time ? IntlDateFormatter::LONG : IntlDateFormatter::NONE
+    );
+    $formatter->setTimeZone($date->getTimezone());
+
+    return $formatter->format($date);
+}
+
+/**
+ * Format the date month according to the locale.
+ *
+ * @param DateTimeInterface $date to format.
+ *
+ * @return bool|string Formatted date, or false if the input is invalid.
+ */
+function format_month(DateTimeInterface $date)
+{
+    if (! $date instanceof DateTimeInterface) {
+        return false;
+    }
+
+    return strftime('%B', $date->getTimestamp());
+}
+
+
+/**
+ * Check if the input is an integer, no matter its real type.
+ *
+ * PHP is a bit messy regarding this:
+ *   - is_int returns false if the input is a string
+ *   - ctype_digit returns false if the input is an integer or negative
+ *
+ * @param mixed $input value
+ *
+ * @return bool true if the input is an integer, false otherwise
+ */
+function is_integer_mixed($input)
+{
+    if (is_array($input) || is_bool($input) || is_object($input)) {
+        return false;
+    }
+    $input = strval($input);
+    return ctype_digit($input) || (startsWith($input, '-') && ctype_digit(substr($input, 1)));
+}
+
+/**
+ * Convert post_max_size/upload_max_filesize (e.g. '16M') parameters to bytes.
+ *
+ * @param string $val Size expressed in string.
+ *
+ * @return int Size expressed in bytes.
+ */
+function return_bytes($val)
+{
+    if (is_integer_mixed($val) || $val === '0' || empty($val)) {
+        return $val;
+    }
+    $val = trim($val);
+    $last = strtolower($val[strlen($val) - 1]);
+    $val = intval(substr($val, 0, -1));
+    switch ($last) {
+        case 'g':
+            $val *= 1024;
+        // do no break in order 1024^2 for each unit
+        case 'm':
+            $val *= 1024;
+        // do no break in order 1024^2 for each unit
+        case 'k':
+            $val *= 1024;
+    }
+    return $val;
+}
+
+/**
+ * Return a human readable size from bytes.
+ *
+ * @param int $bytes value
+ *
+ * @return string Human readable size
+ */
+function human_bytes($bytes)
+{
+    if ($bytes === '') {
+        return t('Setting not set');
+    }
+    if (! is_integer_mixed($bytes)) {
+        return $bytes;
+    }
+    $bytes = intval($bytes);
+    if ($bytes === 0) {
+        return t('Unlimited');
+    }
+
+    $units = [t('B'), t('kiB'), t('MiB'), t('GiB')];
+    for ($i = 0; $i < count($units) && $bytes >= 1024; ++$i) {
+        $bytes /= 1024;
+    }
+
+    return round($bytes) . $units[$i];
+}
+
+/**
+ * Try to determine max file size for uploads (POST).
+ * Returns an integer (in bytes) or formatted depending on $format.
+ *
+ * @param mixed $limitPost   post_max_size PHP setting
+ * @param mixed $limitUpload upload_max_filesize PHP setting
+ * @param bool  $format      Format max upload size to human readable size
+ *
+ * @return int|string max upload file size
+ */
+function get_max_upload_size($limitPost, $limitUpload, $format = true)
+{
+    $size1 = return_bytes($limitPost);
+    $size2 = return_bytes($limitUpload);
+    // Return the smaller of two:
+    $maxsize = min($size1, $size2);
+    return $format ? human_bytes($maxsize) : $maxsize;
+}
+
+/**
+ * Sort the given array alphabetically using php-intl if available.
+ * Case sensitive.
+ *
+ * Note: doesn't support multidimensional arrays
+ *
+ * @param array $data    Input array, passed by reference
+ * @param bool  $reverse Reverse sort if set to true
+ * @param bool  $byKeys  Sort the array by keys if set to true, by value otherwise.
+ */
+function alphabetical_sort(&$data, $reverse = false, $byKeys = false)
+{
+    $callback = function ($a, $b) use ($reverse) {
+        // Collator is part of PHP intl.
+        if (class_exists('Collator')) {
+            $collator = new Collator(setlocale(LC_COLLATE, 0));
+            if (!intl_is_failure(intl_get_error_code())) {
+                return $collator->compare($a, $b) * ($reverse ? -1 : 1);
+            }
+        }
+
+        return strcasecmp($a, $b) * ($reverse ? -1 : 1);
+    };
+
+    if ($byKeys) {
+        uksort($data, $callback);
+    } else {
+        usort($data, $callback);
+    }
+}
+
+/**
+ * Wrapper function for translation which match the API
+ * of gettext()/_() and ngettext().
+ *
+ * @param string $text      Text to translate.
+ * @param string $nText     The plural message ID.
+ * @param int    $nb        The number of items for plural forms.
+ * @param string $domain    The domain where the translation is stored (default: shaarli).
+ * @param array  $variables Associative array of variables to replace in translated text.
+ * @param bool   $fixCase   Apply `ucfirst` on the translated string, might be useful for strings with variables.
+ *
+ * @return string Text translated.
+ */
+function t($text, $nText = '', $nb = 1, $domain = 'shaarli', $variables = [], $fixCase = false)
+{
+    $postFunction = $fixCase ? 'ucfirst' : function ($input) {
+        return $input;
+    };
+
+    return $postFunction(dn__($domain, $text, $nText, $nb, $variables));
+}
+
+/**
+ * Converts an exception into a printable stack trace string.
+ */
+function exception2text(Throwable $e): string
+{
+    return $e->getMessage() . PHP_EOL . $e->getFile() . $e->getLine() . PHP_EOL . $e->getTraceAsString();
+}

application/api/ApiMiddleware.php

@@ -0,0 +1,155 @@
+<?php
+
+namespace Shaarli\Api;
+
+use malkusch\lock\mutex\FlockMutex;
+use Shaarli\Api\Exceptions\ApiAuthorizationException;
+use Shaarli\Api\Exceptions\ApiException;
+use Shaarli\Bookmark\BookmarkFileService;
+use Shaarli\Config\ConfigManager;
+use Slim\Container;
+use Slim\Http\Request;
+use Slim\Http\Response;
+
+/**
+ * Class ApiMiddleware
+ *
+ * This will be called before accessing any API Controller.
+ * Its role is to make sure that the API is enabled, configured, and to validate the JWT token.
+ *
+ * If the request is validated, the controller is called, otherwise a JSON error response is returned.
+ *
+ * @package Api
+ */
+class ApiMiddleware
+{
+    /**
+     * @var int JWT token validity in seconds (9 min).
+     */
+    public static $TOKEN_DURATION = 540;
+
+    /**
+     * @var Container: contains conf, plugins, etc.
+     */
+    protected $container;
+
+    /**
+     * @var ConfigManager instance.
+     */
+    protected $conf;
+
+    /**
+     * ApiMiddleware constructor.
+     *
+     * @param Container $container instance.
+     */
+    public function __construct($container)
+    {
+        $this->container = $container;
+        $this->conf = $this->container->get('conf');
+        $this->setLinkDb($this->conf);
+    }
+
+    /**
+     * Middleware execution:
+     *   - check the API request
+     *   - execute the controller
+     *   - return the response
+     *
+     * @param  Request  $request  Slim request
+     * @param  Response $response Slim response
+     * @param  callable $next     Next action
+     *
+     * @return Response response.
+     */
+    public function __invoke($request, $response, $next)
+    {
+        try {
+            $this->checkRequest($request);
+            $response = $next($request, $response);
+        } catch (ApiException $e) {
+            $e->setResponse($response);
+            $e->setDebug($this->conf->get('dev.debug', false));
+            $response = $e->getApiResponse();
+        }
+
+        return $response
+            ->withHeader('Access-Control-Allow-Origin', '*')
+            ->withHeader(
+                'Access-Control-Allow-Headers',
+                'X-Requested-With, Content-Type, Accept, Origin, Authorization'
+            )
+            ->withHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS')
+        ;
+    }
+
+    /**
+     * Check the request validity (HTTP method, request value, etc.),
+     * that the API is enabled, and the JWT token validity.
+     *
+     * @param  Request $request  Slim request
+     *
+     * @throws ApiAuthorizationException The API is disabled or the token is invalid.
+     */
+    protected function checkRequest($request)
+    {
+        if (! $this->conf->get('api.enabled', true)) {
+            throw new ApiAuthorizationException('API is disabled');
+        }
+        $this->checkToken($request);
+    }
+
+    /**
+     * Check that the JWT token is set and valid.
+     * The API secret setting must be set.
+     *
+     * @param  Request $request  Slim request
+     *
+     * @throws ApiAuthorizationException The token couldn't be validated.
+     */
+    protected function checkToken($request)
+    {
+        if (
+            !$request->hasHeader('Authorization')
+            && !isset($this->container->environment['REDIRECT_HTTP_AUTHORIZATION'])
+        ) {
+            throw new ApiAuthorizationException('JWT token not provided');
+        }
+
+        if (empty($this->conf->get('api.secret'))) {
+            throw new ApiAuthorizationException('Token secret must be set in Shaarli\'s administration');
+        }
+
+        if (isset($this->container->environment['REDIRECT_HTTP_AUTHORIZATION'])) {
+            $authorization = $this->container->environment['REDIRECT_HTTP_AUTHORIZATION'];
+        } else {
+            $authorization = $request->getHeaderLine('Authorization');
+        }
+
+        if (! preg_match('/^Bearer (.*)/i', $authorization, $matches)) {
+            throw new ApiAuthorizationException('Invalid JWT header');
+        }
+
+        ApiUtils::validateJwtToken($matches[1], $this->conf->get('api.secret'));
+    }
+
+    /**
+     * Instantiate a new LinkDB including private bookmarks,
+     * and load in the Slim container.
+     *
+     * FIXME! LinkDB could use a refactoring to avoid this trick.
+     *
+     * @param ConfigManager $conf instance.
+     */
+    protected function setLinkDb($conf)
+    {
+        $linkDb = new BookmarkFileService(
+            $conf,
+            $this->container->get('pluginManager'),
+            $this->container->get('history'),
+            new FlockMutex(fopen(SHAARLI_MUTEX_FILE, 'r'), 2),
+            true
+        );
+        $this->container['db'] = $linkDb;
+    }
+}

application/api/ApiUtils.php

@@ -0,0 +1,174 @@
+<?php
+
+namespace Shaarli\Api;
+
+use Shaarli\Api\Exceptions\ApiAuthorizationException;
+use Shaarli\Bookmark\Bookmark;
+use Shaarli\Http\Base64Url;
+
+/**
+ * REST API utilities
+ */
+class ApiUtils
+{
+    /**
+     * Validates a JWT token authenticity.
+     *
+     * @param string $token  JWT token extracted from the headers.
+     * @param string $secret API secret set in the settings.
+     *
+     * @return bool true on success
+     *
+     * @throws ApiAuthorizationException the token is not valid.
+     */
+    public static function validateJwtToken($token, $secret)
+    {
+        $parts = explode('.', $token);
+        if (count($parts) != 3 || strlen($parts[0]) == 0 || strlen($parts[1]) == 0) {
+            throw new ApiAuthorizationException('Malformed JWT token');
+        }
+
+        $genSign = Base64Url::encode(hash_hmac('sha512', $parts[0] . '.' . $parts[1], $secret, true));
+        if ($parts[2] != $genSign) {
+            throw new ApiAuthorizationException('Invalid JWT signature');
+        }
+
+        $header = json_decode(Base64Url::decode($parts[0]));
+        if ($header === null) {
+            throw new ApiAuthorizationException('Invalid JWT header');
+        }
+
+        $payload = json_decode(Base64Url::decode($parts[1]));
+        if ($payload === null) {
+            throw new ApiAuthorizationException('Invalid JWT payload');
+        }
+
+        if (
+            empty($payload->iat)
+            || $payload->iat > time()
+            || time() - $payload->iat > ApiMiddleware::$TOKEN_DURATION
+        ) {
+            throw new ApiAuthorizationException('Invalid JWT issued time');
+        }
+
+        return true;
+    }
+
+    /**
+     * Format a Link for the REST API.
+     *
+     * @param Bookmark $bookmark Bookmark data read from the datastore.
+     * @param string   $indexUrl Shaarli's index URL (used for relative URL).
+     *
+     * @return array Link data formatted for the REST API.
+     */
+    public static function formatLink($bookmark, $indexUrl)
+    {
+        $out['id'] = $bookmark->getId();
+        // Not an internal link
+        if (! $bookmark->isNote()) {
+            $out['url'] = $bookmark->getUrl();
+        } else {
+            $out['url'] = rtrim($indexUrl, '/') . '/' . ltrim($bookmark->getUrl(), '/');
+        }
+        $out['shorturl'] = $bookmark->getShortUrl();
+        $out['title'] = $bookmark->getTitle();
+        $out['description'] = $bookmark->getDescription();
+        $out['tags'] = $bookmark->getTags();
+        $out['private'] = $bookmark->isPrivate();
+        $out['created'] = $bookmark->getCreated()->format(\DateTime::ATOM);
+        if (! empty($bookmark->getUpdated())) {
+            $out['updated'] = $bookmark->getUpdated()->format(\DateTime::ATOM);
+        } else {
+            $out['updated'] = '';
+        }
+        return $out;
+    }
+
+    /**
+     * Convert a link given through a request, to a valid Bookmark for the datastore.
+     *
+     * If no URL is provided, it will generate a local note URL.
+     * If no title is provided, it will use the URL as title.
+     *
+     * @param array|null $input          Request Link.
+     * @param bool       $defaultPrivate Setting defined if a bookmark is private by default.
+     * @param string     $tagsSeparator  Tags separator loaded from the config file.
+     *
+     * @return Bookmark instance.
+     */
+    public static function buildBookmarkFromRequest(
+        ?array $input,
+        bool $defaultPrivate,
+        string $tagsSeparator
+    ): Bookmark {
+        $bookmark = new Bookmark();
+        $url = ! empty($input['url']) ? cleanup_url($input['url']) : '';
+        if (isset($input['private'])) {
+            $private = filter_var($input['private'], FILTER_VALIDATE_BOOLEAN);
+        } else {
+            $private = $defaultPrivate;
+        }
+
+        $bookmark->setTitle(! empty($input['title']) ? $input['title'] : '');
+        $bookmark->setUrl($url);
+        $bookmark->setDescription(! empty($input['description']) ? $input['description'] : '');
+
+        // Be permissive with provided tags format
+        if (is_string($input['tags'] ?? null)) {
+            $input['tags'] = tags_str2array($input['tags'], $tagsSeparator);
+        }
+        if (is_array($input['tags'] ?? null) && count($input['tags']) === 1 && is_string($input['tags'][0])) {
+            $input['tags'] = tags_str2array($input['tags'][0], $tagsSeparator);
+        }
+
+        $bookmark->setTags(! empty($input['tags']) ? $input['tags'] : []);
+        $bookmark->setPrivate($private);
+
+        $created = \DateTime::createFromFormat(\DateTime::ATOM, $input['created'] ?? '');
+        if ($created instanceof \DateTimeInterface) {
+            $bookmark->setCreated($created);
+        }
+        $updated = \DateTime::createFromFormat(\DateTime::ATOM, $input['updated'] ?? '');
+        if ($updated instanceof \DateTimeInterface) {
+            $bookmark->setUpdated($updated);
+        }
+
+        return $bookmark;
+    }
+
+    /**
+     * Update link fields using an updated link object.
+     *
+     * @param Bookmark $oldLink data
+     * @param Bookmark $newLink data
+     *
+     * @return Bookmark $oldLink updated with $newLink values
+     */
+    public static function updateLink($oldLink, $newLink)
+    {
+        $oldLink->setTitle($newLink->getTitle());
+        $oldLink->setUrl($newLink->getUrl());
+        $oldLink->setDescription($newLink->getDescription());
+        $oldLink->setTags($newLink->getTags());
+        $oldLink->setPrivate($newLink->isPrivate());
+
+        return $oldLink;
+    }
+
+    /**
+     * Format a Tag for the REST API.
+     *
+     * @param string $tag         Tag name
+     * @param int    $occurrences Number of bookmarks using this tag
+     *
+     * @return array Link data formatted for the REST API.
+     */
+    public static function formatTag($tag, $occurences)
+    {
+        return [
+            'name'       => $tag,
+            'occurrences' => $occurences,
+        ];
+    }
+}

application/api/controllers/ApiController.php

@@ -0,0 +1,73 @@
+<?php
+
+namespace Shaarli\Api\Controllers;
+
+use Shaarli\Bookmark\BookmarkServiceInterface;
+use Shaarli\Config\ConfigManager;
+use Shaarli\History;
+use Slim\Container;
+
+/**
+ * Abstract Class ApiController
+ *
+ * Defines REST API Controller dependencies injected from the container.
+ *
+ * @package Api\Controllers
+ */
+abstract class ApiController
+{
+    /**
+     * @var Container
+     */
+    protected $ci;
+
+    /**
+     * @var ConfigManager
+     */
+    protected $conf;
+
+    /**
+     * @var BookmarkServiceInterface
+     */
+    protected $bookmarkService;
+
+    /**
+     * @var History
+     */
+    protected $history;
+
+    /**
+     * @var int|null JSON style option.
+     */
+    protected $jsonStyle;
+
+    /**
+     * ApiController constructor.
+     *
+     * Note: enabling debug mode displays JSON with readable formatting.
+     *
+     * @param Container $ci Slim container.
+     */
+    public function __construct(Container $ci)
+    {
+        $this->ci = $ci;
+        $this->conf = $ci->get('conf');
+        $this->bookmarkService = $ci->get('db');
+        $this->history = $ci->get('history');
+        if ($this->conf->get('dev.debug', false)) {
+            $this->jsonStyle = JSON_PRETTY_PRINT;
+        } else {
+            $this->jsonStyle = null;
+        }
+    }
+
+    /**
+     * Get the container.
+     *
+     * @return Container
+     */
+    public function getCi()
+    {
+        return $this->ci;
+    }
+}

application/api/controllers/HistoryController.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace Shaarli\Api\Controllers;
+
+use Shaarli\Api\Exceptions\ApiBadParametersException;
+use Slim\Http\Request;
+use Slim\Http\Response;
+
+/**
+ * Class History
+ *
+ * REST API Controller: /history
+ *
+ * @package Shaarli\Api\Controllers
+ */
+class HistoryController extends ApiController
+{
+    /**
+     * Service providing operation regarding Shaarli datastore and settings.
+     *
+     * @param Request  $request  Slim request.
+     * @param Response $response Slim response.
+     *
+     * @return Response response.
+     *
+     * @throws ApiBadParametersException Invalid parameters.
+     */
+    public function getHistory($request, $response)
+    {
+        $history = $this->history->getHistory();
+
+        // Return history operations from the {offset}th, starting from {since}.
+        $since = \DateTime::createFromFormat(\DateTime::ATOM, $request->getParam('since', ''));
+        $offset = $request->getParam('offset');
+        if (empty($offset)) {
+            $offset = 0;
+        } elseif (ctype_digit($offset)) {
+            $offset = (int) $offset;
+        } else {
+            throw new ApiBadParametersException('Invalid offset');
+        }
+
+        // limit parameter is either a number of bookmarks or 'all' for everything.
+        $limit = $request->getParam('limit');
+        if (empty($limit)) {
+            $limit = count($history);
+        } elseif (ctype_digit($limit)) {
+            $limit = (int) $limit;
+        } else {
+            throw new ApiBadParametersException('Invalid limit');
+        }
+
+        $out = [];
+        $i = 0;
+        foreach ($history as $entry) {
+            if ((! empty($since) && $entry['datetime'] <= $since) || count($out) >= $limit) {
+                break;
+            }
+            if (++$i > $offset) {
+                $out[$i] = $entry;
+                $out[$i]['datetime'] = $out[$i]['datetime']->format(\DateTime::ATOM);
+            }
+        }
+        $out = array_values($out);
+
+        return $response->withJson($out, 200, $this->jsonStyle);
+    }
+}

application/api/controllers/Info.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace Shaarli\Api\Controllers;
+
+use Shaarli\Bookmark\BookmarkFilter;
+use Slim\Http\Request;
+use Slim\Http\Response;
+
+/**
+ * Class Info
+ *
+ * REST API Controller: /info
+ *
+ * @package Api\Controllers
+ * @see http://shaarli.github.io/api-documentation/#links-instance-information-get
+ */
+class Info extends ApiController
+{
+    /**
+     * Service providing various information about Shaarli instance.
+     *
+     * @param Request  $request  Slim request.
+     * @param Response $response Slim response.
+     *
+     * @return Response response.
+     */
+    public function getInfo($request, $response)
+    {
+        $info = [
+            'global_counter' => $this->bookmarkService->count(),
+            'private_counter' => $this->bookmarkService->count(BookmarkFilter::$PRIVATE),
+            'settings' => [
+                'title' => $this->conf->get('general.title', 'Shaarli'),
+                'header_link' => $this->conf->get('general.header_link', '?'),
+                'timezone' => $this->conf->get('general.timezone', 'UTC'),
+                'enabled_plugins' => $this->conf->get('general.enabled_plugins', []),
+                'default_private_links' => $this->conf->get('privacy.default_private_links', false),
+            ],
+        ];
+
+        return $response->withJson($info, 200, $this->jsonStyle);
+    }
+}

application/api/controllers/Links.php

@@ -0,0 +1,213 @@
+<?php
+
+namespace Shaarli\Api\Controllers;
+
+use Shaarli\Api\ApiUtils;
+use Shaarli\Api\Exceptions\ApiBadParametersException;
+use Shaarli\Api\Exceptions\ApiLinkNotFoundException;
+use Slim\Http\Request;
+use Slim\Http\Response;
+
+/**
+ * Class Links
+ *
+ * REST API Controller: all services related to bookmarks collection.
+ *
+ * @package Api\Controllers
+ * @see http://shaarli.github.io/api-documentation/#links-links-collection
+ */
+class Links extends ApiController
+{
+    /**
+     * @var int Number of bookmarks returned if no limit is provided.
+     */
+    public static $DEFAULT_LIMIT = 20;
+
+    /**
+     * Retrieve a list of bookmarks, allowing different filters.
+     *
+     * @param Request  $request  Slim request.
+     * @param Response $response Slim response.
+     *
+     * @return Response response.
+     *
+     * @throws ApiBadParametersException Invalid parameters.
+     */
+    public function getLinks($request, $response)
+    {
+        $private = $request->getParam('visibility');
+
+        // Return bookmarks from the {offset}th link, starting from 0.
+        $offset = $request->getParam('offset');
+        if (! empty($offset) && ! ctype_digit($offset)) {
+            throw new ApiBadParametersException('Invalid offset');
+        }
+        $offset = ! empty($offset) ? intval($offset) : 0;
+
+        // limit parameter is either a number of bookmarks or 'all' for everything.
+        $limit = $request->getParam('limit');
+        if (empty($limit)) {
+            $limit = self::$DEFAULT_LIMIT;
+        } elseif (ctype_digit($limit)) {
+            $limit = intval($limit);
+        } elseif ($limit === 'all') {
+            $limit = null;
+        } else {
+            throw new ApiBadParametersException('Invalid limit');
+        }
+
+        $searchResult = $this->bookmarkService->search(
+            [
+                'searchtags' => $request->getParam('searchtags', ''),
+                'searchterm' => $request->getParam('searchterm', ''),
+            ],
+            $private,
+            false,
+            false,
+            false,
+            [
+                'limit' => $limit,
+                'offset' => $offset,
+                'allowOutOfBounds' => true,
+            ]
+        );
+
+        // 'environment' is set by Slim and encapsulate $_SERVER.
+        $indexUrl = index_url($this->ci['environment']);
+
+        $out = [];
+        foreach ($searchResult->getBookmarks() as $bookmark) {
+            $out[] = ApiUtils::formatLink($bookmark, $indexUrl);
+        }
+
+        return $response->withJson($out, 200, $this->jsonStyle);
+    }
+
+    /**
+     * Return a single formatted link by its ID.
+     *
+     * @param Request  $request  Slim request.
+     * @param Response $response Slim response.
+     * @param array    $args     Path parameters. including the ID.
+     *
+     * @return Response containing the link array.
+     *
+     * @throws ApiLinkNotFoundException generating a 404 error.
+     */
+    public function getLink($request, $response, $args)
+    {
+        $id = is_integer_mixed($args['id']) ? (int) $args['id'] : null;
+        if ($id === null || ! $this->bookmarkService->exists($id)) {
+            throw new ApiLinkNotFoundException();
+        }
+        $index = index_url($this->ci['environment']);
+        $out = ApiUtils::formatLink($this->bookmarkService->get($id), $index);
+
+        return $response->withJson($out, 200, $this->jsonStyle);
+    }
+
+    /**
+     * Creates a new link from posted request body.
+     *
+     * @param Request  $request  Slim request.
+     * @param Response $response Slim response.
+     *
+     * @return Response response.
+     */
+    public function postLink($request, $response)
+    {
+        $data = (array) ($request->getParsedBody() ?? []);
+        $bookmark = ApiUtils::buildBookmarkFromRequest(
+            $data,
+            $this->conf->get('privacy.default_private_links'),
+            $this->conf->get('general.tags_separator', ' ')
+        );
+        // duplicate by URL, return 409 Conflict
+        if (
+            ! empty($bookmark->getUrl())
+            && ! empty($dup = $this->bookmarkService->findByUrl($bookmark->getUrl()))
+        ) {
+            return $response->withJson(
+                ApiUtils::formatLink($dup, index_url($this->ci['environment'])),
+                409,
+                $this->jsonStyle
+            );
+        }
+
+        $this->bookmarkService->add($bookmark);
+        $out = ApiUtils::formatLink($bookmark, index_url($this->ci['environment']));
+        $redirect = $this->ci->router->pathFor('getLink', ['id' => $bookmark->getId()]);
+        return $response->withAddedHeader('Location', $redirect)
+                        ->withJson($out, 201, $this->jsonStyle);
+    }
+
+    /**
+     * Updates an existing link from posted request body.
+     *
+     * @param Request  $request  Slim request.
+     * @param Response $response Slim response.
+     * @param array    $args     Path parameters. including the ID.
+     *
+     * @return Response response.
+     *
+     * @throws ApiLinkNotFoundException generating a 404 error.
+     */
+    public function putLink($request, $response, $args)
+    {
+        $id = is_integer_mixed($args['id']) ? (int) $args['id'] : null;
+        if ($id === null || !$this->bookmarkService->exists($id)) {
+            throw new ApiLinkNotFoundException();
+        }
+
+        $index = index_url($this->ci['environment']);
+        $data = $request->getParsedBody();
+
+        $requestBookmark = ApiUtils::buildBookmarkFromRequest(
+            $data,
+            $this->conf->get('privacy.default_private_links'),
+            $this->conf->get('general.tags_separator', ' ')
+        );
+        // duplicate URL on a different link, return 409 Conflict
+        if (
+            ! empty($requestBookmark->getUrl())
+            && ! empty($dup = $this->bookmarkService->findByUrl($requestBookmark->getUrl()))
+            && $dup->getId() != $id
+        ) {
+            return $response->withJson(
+                ApiUtils::formatLink($dup, $index),
+                409,
+                $this->jsonStyle
+            );
+        }
+
+        $responseBookmark = $this->bookmarkService->get($id);
+        $responseBookmark = ApiUtils::updateLink($responseBookmark, $requestBookmark);
+        $this->bookmarkService->set($responseBookmark);
+
+        $out = ApiUtils::formatLink($responseBookmark, $index);
+        return $response->withJson($out, 200, $this->jsonStyle);
+    }
+
+    /**
+     * Delete an existing link by its ID.
+     *
+     * @param Request  $request  Slim request.
+     * @param Response $response Slim response.
+     * @param array    $args     Path parameters. including the ID.
+     *
+     * @return Response response.
+     *
+     * @throws ApiLinkNotFoundException generating a 404 error.
+     */
+    public function deleteLink($request, $response, $args)
+    {
+        $id = is_integer_mixed($args['id']) ? (int) $args['id'] : null;
+        if ($id === null || !$this->bookmarkService->exists($id)) {
+            throw new ApiLinkNotFoundException();
+        }
+        $bookmark = $this->bookmarkService->get($id);
+        $this->bookmarkService->remove($bookmark);
+
+        return $response->withStatus(204);
+    }
+}

application/api/controllers/Tags.php

@@ -0,0 +1,174 @@
+<?php
+
+namespace Shaarli\Api\Controllers;
+
+use Shaarli\Api\ApiUtils;
+use Shaarli\Api\Exceptions\ApiBadParametersException;
+use Shaarli\Api\Exceptions\ApiTagNotFoundException;
+use Shaarli\Bookmark\BookmarkFilter;
+use Slim\Http\Request;
+use Slim\Http\Response;
+
+/**
+ * Class Tags
+ *
+ * REST API Controller: all services related to tags collection.
+ *
+ * @package Api\Controllers
+ */
+class Tags extends ApiController
+{
+    /**
+     * @var int Number of bookmarks returned if no limit is provided.
+     */
+    public static $DEFAULT_LIMIT = 'all';
+
+    /**
+     * Retrieve a list of tags, allowing different filters.
+     *
+     * @param Request  $request  Slim request.
+     * @param Response $response Slim response.
+     *
+     * @return Response response.
+     *
+     * @throws ApiBadParametersException Invalid parameters.
+     */
+    public function getTags($request, $response)
+    {
+        $visibility = $request->getParam('visibility');
+        $tags = $this->bookmarkService->bookmarksCountPerTag([], $visibility);
+
+        // Return tags from the {offset}th tag, starting from 0.
+        $offset = $request->getParam('offset');
+        if (! empty($offset) && ! ctype_digit($offset)) {
+            throw new ApiBadParametersException('Invalid offset');
+        }
+        $offset = ! empty($offset) ? intval($offset) : 0;
+        if ($offset > count($tags)) {
+            return $response->withJson([], 200, $this->jsonStyle);
+        }
+
+        // limit parameter is either a number of bookmarks or 'all' for everything.
+        $limit = $request->getParam('limit');
+        if (empty($limit)) {
+            $limit = self::$DEFAULT_LIMIT;
+        }
+        if (ctype_digit($limit)) {
+            $limit = intval($limit);
+        } elseif ($limit === 'all') {
+            $limit = count($tags);
+        } else {
+            throw new ApiBadParametersException('Invalid limit');
+        }
+
+        $out = [];
+        $index = 0;
+        foreach ($tags as $tag => $occurrences) {
+            if (count($out) >= $limit) {
+                break;
+            }
+            if ($index++ >= $offset) {
+                $out[] = ApiUtils::formatTag($tag, $occurrences);
+            }
+        }
+
+        return $response->withJson($out, 200, $this->jsonStyle);
+    }
+
+    /**
+     * Return a single formatted tag by its name.
+     *
+     * @param Request  $request  Slim request.
+     * @param Response $response Slim response.
+     * @param array    $args     Path parameters. including the tag name.
+     *
+     * @return Response containing the link array.
+     *
+     * @throws ApiTagNotFoundException generating a 404 error.
+     */
+    public function getTag($request, $response, $args)
+    {
+        $tags = $this->bookmarkService->bookmarksCountPerTag();
+        if (!isset($tags[$args['tagName']])) {
+            throw new ApiTagNotFoundException();
+        }
+        $out = ApiUtils::formatTag($args['tagName'], $tags[$args['tagName']]);
+
+        return $response->withJson($out, 200, $this->jsonStyle);
+    }
+
+    /**
+     * Rename a tag from the given name.
+     * If the new name provided matches an existing tag, they will be merged.
+     *
+     * @param Request  $request  Slim request.
+     * @param Response $response Slim response.
+     * @param array    $args     Path parameters. including the tag name.
+     *
+     * @return Response response.
+     *
+     * @throws ApiTagNotFoundException generating a 404 error.
+     * @throws ApiBadParametersException new tag name not provided
+     */
+    public function putTag($request, $response, $args)
+    {
+        $tags = $this->bookmarkService->bookmarksCountPerTag();
+        if (! isset($tags[$args['tagName']])) {
+            throw new ApiTagNotFoundException();
+        }
+
+        $data = $request->getParsedBody();
+        if (empty($data['name'])) {
+            throw new ApiBadParametersException('New tag name is required in the request body');
+        }
+
+        $searchResult = $this->bookmarkService->search(
+            ['searchtags' => $args['tagName']],
+            BookmarkFilter::$ALL,
+            true
+        );
+        foreach ($searchResult->getBookmarks() as $bookmark) {
+            $bookmark->renameTag($args['tagName'], $data['name']);
+            $this->bookmarkService->set($bookmark, false);
+            $this->history->updateLink($bookmark);
+        }
+        $this->bookmarkService->save();
+
+        $tags = $this->bookmarkService->bookmarksCountPerTag();
+        $out = ApiUtils::formatTag($data['name'], $tags[$data['name']]);
+        return $response->withJson($out, 200, $this->jsonStyle);
+    }
+
+    /**
+     * Delete an existing tag by its name.
+     *
+     * @param Request  $request  Slim request.
+     * @param Response $response Slim response.
+     * @param array    $args     Path parameters. including the tag name.
+     *
+     * @return Response response.
+     *
+     * @throws ApiTagNotFoundException generating a 404 error.
+     */
+    public function deleteTag($request, $response, $args)
+    {
+        $tags = $this->bookmarkService->bookmarksCountPerTag();
+        if (! isset($tags[$args['tagName']])) {
+            throw new ApiTagNotFoundException();
+        }
+
+        $searchResult = $this->bookmarkService->search(
+            ['searchtags' => $args['tagName']],
+            BookmarkFilter::$ALL,
+            true
+        );
+        foreach ($searchResult->getBookmarks() as $bookmark) {
+            $bookmark->deleteTag($args['tagName']);
+            $this->bookmarkService->set($bookmark, false);
+            $this->history->updateLink($bookmark);
+        }
+        $this->bookmarkService->save();
+
+        return $response->withStatus(204);
+    }
+}

application/api/exceptions/ApiAuthorizationException.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace Shaarli\Api\Exceptions;
+
+/**
+ * Class ApiAuthorizationException
+ *
+ * Request not authorized, return a 401 HTTP code.
+ */
+class ApiAuthorizationException extends ApiException
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function getApiResponse()
+    {
+        $this->setMessage('Not authorized');
+        return $this->buildApiResponse(401);
+    }
+
+    /**
+     * Set the exception message.
+     *
+     * We only return a generic error message in production mode to avoid giving
+     * to much security information.
+     *
+     * @param $message string the exception message.
+     */
+    public function setMessage($message)
+    {
+        $original = $this->debug === true ? ': ' . $this->getMessage() : '';
+        $this->message = $message . $original;
+    }
+}

application/api/exceptions/ApiBadParametersException.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace Shaarli\Api\Exceptions;
+
+/**
+ * Class ApiBadParametersException
+ *
+ * Invalid request exception, return a 400 HTTP code.
+ */
+class ApiBadParametersException extends ApiException
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function getApiResponse()
+    {
+        return $this->buildApiResponse(400);
+    }
+}

application/api/exceptions/ApiException.php

@@ -0,0 +1,78 @@
+<?php
+
+namespace Shaarli\Api\Exceptions;
+
+use Slim\Http\Response;
+
+/**
+ * Abstract class ApiException
+ *
+ * Parent Exception related to the API, able to generate a valid Response (ResponseInterface).
+ * Also can include various information in debug mode.
+ */
+abstract class ApiException extends \Exception
+{
+    /**
+     * @var Response instance from Slim.
+     */
+    protected $response;
+
+    /**
+     * @var bool Debug mode enabled/disabled.
+     */
+    protected $debug;
+
+    /**
+     * Build the final response.
+     *
+     * @return Response Final response to give.
+     */
+    abstract public function getApiResponse();
+
+    /**
+     * Creates ApiResponse body.
+     * In production mode, it will only return the exception message,
+     * but in dev mode, it includes additional information in an array.
+     *
+     * @return array|string response body
+     */
+    protected function getApiResponseBody()
+    {
+        if ($this->debug !== true) {
+            return $this->getMessage();
+        }
+        return [
+            'message' => $this->getMessage(),
+            'stacktrace' => get_class($this) . ': ' . $this->getTraceAsString()
+        ];
+    }
+
+    /**
+     * Build the Response object to return.
+     *
+     * @param int $code HTTP status.
+     *
+     * @return Response with status + body.
+     */
+    protected function buildApiResponse($code)
+    {
+        $style = $this->debug ? JSON_PRETTY_PRINT : null;
+        return $this->response->withJson($this->getApiResponseBody(), $code, $style);
+    }
+
+    /**
+     * @param Response $response
+     */
+    public function setResponse($response)
+    {
+        $this->response = $response;
+    }
+
+    /**
+     * @param bool $debug
+     */
+    public function setDebug($debug)
+    {
+        $this->debug = $debug;
+    }
+}

application/api/exceptions/ApiInternalException.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace Shaarli\Api\Exceptions;
+
+/**
+ * Class ApiInternalException
+ *
+ * Generic exception, return a 500 HTTP code.
+ */
+class ApiInternalException extends ApiException
+{
+    /**
+     * @inheritdoc
+     */
+    public function getApiResponse()
+    {
+        return $this->buildApiResponse(500);
+    }
+}

application/api/exceptions/ApiLinkNotFoundException.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Shaarli\Api\Exceptions;
+
+/**
+ * Class ApiLinkNotFoundException
+ *
+ * Link selected by ID couldn't be found, results in a 404 error.
+ *
+ * @package Shaarli\Api\Exceptions
+ */
+class ApiLinkNotFoundException extends ApiException
+{
+    /**
+     * ApiLinkNotFoundException constructor.
+     */
+    public function __construct()
+    {
+        $this->message = 'Link not found';
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getApiResponse()
+    {
+        return $this->buildApiResponse(404);
+    }
+}

application/api/exceptions/ApiTagNotFoundException.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Shaarli\Api\Exceptions;
+
+/**
+ * Class ApiTagNotFoundException
+ *
+ * Tag selected by name couldn't be found in the datastore, results in a 404 error.
+ *
+ * @package Shaarli\Api\Exceptions
+ */
+class ApiTagNotFoundException extends ApiException
+{
+    /**
+     * ApiLinkNotFoundException constructor.
+     */
+    public function __construct()
+    {
+        $this->message = 'Tag not found';
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getApiResponse()
+    {
+        return $this->buildApiResponse(404);
+    }
+}

application/bookmark/Bookmark.php

@@ -0,0 +1,542 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Bookmark;
+
+use DateTime;
+use DateTimeInterface;
+use Shaarli\Bookmark\Exception\InvalidBookmarkException;
+
+/**
+ * Class Bookmark
+ *
+ * This class represent a single Bookmark with all its attributes.
+ * Every bookmark should manipulated using this, before being formatted.
+ *
+ * @package Shaarli\Bookmark
+ */
+class Bookmark
+{
+    /** @var string Date format used in string (former ID format) */
+    public const LINK_DATE_FORMAT = 'Ymd_His';
+
+    /** @var int Bookmark ID */
+    protected $id;
+
+    /** @var string Permalink identifier */
+    protected $shortUrl;
+
+    /** @var string Bookmark's URL - $shortUrl prefixed with `?` for notes */
+    protected $url;
+
+    /** @var string Bookmark's title */
+    protected $title;
+
+    /** @var string Raw bookmark's description */
+    protected $description;
+
+    /** @var array List of bookmark's tags */
+    protected $tags;
+
+    /** @var string|bool|null Thumbnail's URL - initialized at null, false if no thumbnail could be found */
+    protected $thumbnail;
+
+    /** @var bool Set to true if the bookmark is set as sticky */
+    protected $sticky;
+
+    /** @var DateTimeInterface Creation datetime */
+    protected $created;
+
+    /** @var DateTimeInterface datetime */
+    protected $updated;
+
+    /** @var bool True if the bookmark can only be seen while logged in */
+    protected $private;
+
+    /** @var mixed[] Available to store any additional content for a bookmark. Currently used for search highlight. */
+    protected $additionalContent = [];
+
+    /**
+     * Initialize a link from array data. Especially useful to create a Bookmark from former link storage format.
+     *
+     * @param array  $data
+     * @param string $tagsSeparator Tags separator loaded from the config file.
+     *                              This is a context data, and it should *never* be stored in the Bookmark object.
+     *
+     * @return $this
+     */
+    public function fromArray(array $data, string $tagsSeparator = ' '): Bookmark
+    {
+        $this->id = $data['id'] ?? null;
+        $this->shortUrl = $data['shorturl'] ?? null;
+        $this->url = $data['url'] ?? null;
+        $this->title = $data['title'] ?? null;
+        $this->description = $data['description'] ?? null;
+        $this->thumbnail = $data['thumbnail'] ?? null;
+        $this->sticky = $data['sticky'] ?? false;
+        $this->created = $data['created'] ?? null;
+        if (is_array($data['tags'])) {
+            $this->tags = $data['tags'];
+        } else {
+            $this->tags = tags_str2array($data['tags'] ?? '', $tagsSeparator);
+        }
+        if (! empty($data['updated'])) {
+            $this->updated = $data['updated'];
+        }
+        $this->private = ($data['private'] ?? false) ? true : false;
+        $this->additionalContent = $data['additional_content'] ?? [];
+
+        return $this;
+    }
+
+    /**
+     * Make sure that the current instance of Bookmark is valid and can be saved into the data store.
+     * A valid link requires:
+     *   - an integer ID
+     *   - a short URL (for permalinks)
+     *   - a creation date
+     *
+     * This function also initialize optional empty fields:
+     *   - the URL with the permalink
+     *   - the title with the URL
+     *
+     * Also make sure that we do not save search highlights in the datastore.
+     *
+     * @throws InvalidBookmarkException
+     */
+    public function validate(): void
+    {
+        if (
+            $this->id === null
+            || ! is_int($this->id)
+            || empty($this->shortUrl)
+            || empty($this->created)
+        ) {
+            throw new InvalidBookmarkException($this);
+        }
+        if (empty($this->url)) {
+            $this->url = '/shaare/' . $this->shortUrl;
+        }
+        if (empty($this->title)) {
+            $this->title = $this->url;
+        }
+        if (array_key_exists('search_highlight', $this->additionalContent)) {
+            unset($this->additionalContent['search_highlight']);
+        }
+    }
+
+    /**
+     * Set the Id.
+     * If they're not already initialized, this function also set:
+     *   - created: with the current datetime
+     *   - shortUrl: with a generated small hash from the date and the given ID
+     *
+     * @param int|null $id
+     *
+     * @return Bookmark
+     */
+    public function setId(?int $id): Bookmark
+    {
+        $this->id = $id;
+        if (empty($this->created)) {
+            $this->created = new DateTime();
+        }
+        if (empty($this->shortUrl)) {
+            $this->shortUrl = link_small_hash($this->created, $this->id);
+        }
+
+        return $this;
+    }
+
+    /**
+     * Get the Id.
+     *
+     * @return int|null
+     */
+    public function getId(): ?int
+    {
+        return $this->id;
+    }
+
+    /**
+     * Get the ShortUrl.
+     *
+     * @return string|null
+     */
+    public function getShortUrl(): ?string
+    {
+        return $this->shortUrl;
+    }
+
+    /**
+     * Get the Url.
+     *
+     * @return string|null
+     */
+    public function getUrl(): ?string
+    {
+        return $this->url;
+    }
+
+    /**
+     * Get the Title.
+     *
+     * @return string
+     */
+    public function getTitle(): ?string
+    {
+        return $this->title;
+    }
+
+    /**
+     * Get the Description.
+     *
+     * @return string
+     */
+    public function getDescription(): string
+    {
+        return ! empty($this->description) ? $this->description : '';
+    }
+
+    /**
+     * Get the Created.
+     *
+     * @return DateTimeInterface
+     */
+    public function getCreated(): ?DateTimeInterface
+    {
+        return $this->created;
+    }
+
+    /**
+     * Get the Updated.
+     *
+     * @return DateTimeInterface
+     */
+    public function getUpdated(): ?DateTimeInterface
+    {
+        return $this->updated;
+    }
+
+    /**
+     * Set the ShortUrl.
+     *
+     * @param string|null $shortUrl
+     *
+     * @return Bookmark
+     */
+    public function setShortUrl(?string $shortUrl): Bookmark
+    {
+        $this->shortUrl = $shortUrl;
+
+        return $this;
+    }
+
+    /**
+     * Set the Url.
+     *
+     * @param string|null $url
+     * @param string[]    $allowedProtocols
+     *
+     * @return Bookmark
+     */
+    public function setUrl(?string $url, array $allowedProtocols = []): Bookmark
+    {
+        $url = $url !== null ? trim($url) : '';
+        if (! empty($url)) {
+            $url = whitelist_protocols($url, $allowedProtocols);
+        }
+        $this->url = $url;
+
+        return $this;
+    }
+
+    /**
+     * Set the Title.
+     *
+     * @param string|null $title
+     *
+     * @return Bookmark
+     */
+    public function setTitle(?string $title): Bookmark
+    {
+        $this->title = $title !== null ? trim($title) : '';
+
+        return $this;
+    }
+
+    /**
+     * Set the Description.
+     *
+     * @param string|null $description
+     *
+     * @return Bookmark
+     */
+    public function setDescription(?string $description): Bookmark
+    {
+        $this->description = $description;
+
+        return $this;
+    }
+
+    /**
+     * Set the Created.
+     * Note: you shouldn't set this manually except for special cases (like bookmark import)
+     *
+     * @param DateTimeInterface|null $created
+     *
+     * @return Bookmark
+     */
+    public function setCreated(?DateTimeInterface $created): Bookmark
+    {
+        $this->created = $created;
+
+        return $this;
+    }
+
+    /**
+     * Set the Updated.
+     *
+     * @param DateTimeInterface|null $updated
+     *
+     * @return Bookmark
+     */
+    public function setUpdated(?DateTimeInterface $updated): Bookmark
+    {
+        $this->updated = $updated;
+
+        return $this;
+    }
+
+    /**
+     * Get the Private.
+     *
+     * @return bool
+     */
+    public function isPrivate(): bool
+    {
+        return $this->private ? true : false;
+    }
+
+    /**
+     * Set the Private.
+     *
+     * @param bool|null $private
+     *
+     * @return Bookmark
+     */
+    public function setPrivate(?bool $private): Bookmark
+    {
+        $this->private = $private ? true : false;
+
+        return $this;
+    }
+
+    /**
+     * Get the Tags.
+     *
+     * @return string[]
+     */
+    public function getTags(): array
+    {
+        return is_array($this->tags) ? $this->tags : [];
+    }
+
+    /**
+     * Set the Tags.
+     *
+     * @param string[]|null $tags
+     *
+     * @return Bookmark
+     */
+    public function setTags(?array $tags): Bookmark
+    {
+        $this->tags = array_map(
+            function (string $tag): string {
+                return $tag[0] === '-' ? substr($tag, 1) : $tag;
+            },
+            tags_filter($tags, ' ')
+        );
+
+        return $this;
+    }
+
+    /**
+     * Get the Thumbnail.
+     *
+     * @return string|bool|null Thumbnail's URL - initialized at null, false if no thumbnail could be found
+     */
+    public function getThumbnail()
+    {
+        return !$this->isNote() ? $this->thumbnail : false;
+    }
+
+    /**
+     * Set the Thumbnail.
+     *
+     * @param string|bool|null $thumbnail Thumbnail's URL - false if no thumbnail could be found
+     *
+     * @return Bookmark
+     */
+    public function setThumbnail($thumbnail): Bookmark
+    {
+        $this->thumbnail = $thumbnail;
+
+        return $this;
+    }
+
+    /**
+     * Return true if:
+     *   - the bookmark's thumbnail is not already set to false (= not found)
+     *   - it's not a note
+     *   - it's an HTTP(S) link
+     *   - the thumbnail has not yet be retrieved (null) or its associated cache file doesn't exist anymore
+     *
+     * @return bool True if the bookmark's thumbnail needs to be retrieved.
+     */
+    public function shouldUpdateThumbnail(): bool
+    {
+        return $this->thumbnail !== false
+            && !$this->isNote()
+            && startsWith(strtolower($this->url), 'http')
+            && (null === $this->thumbnail || !is_file($this->thumbnail))
+        ;
+    }
+
+    /**
+     * Get the Sticky.
+     *
+     * @return bool
+     */
+    public function isSticky(): bool
+    {
+        return $this->sticky ? true : false;
+    }
+
+    /**
+     * Set the Sticky.
+     *
+     * @param bool|null $sticky
+     *
+     * @return Bookmark
+     */
+    public function setSticky(?bool $sticky): Bookmark
+    {
+        $this->sticky = $sticky ? true : false;
+
+        return $this;
+    }
+
+    /**
+     * @param string $separator Tags separator loaded from the config file.
+     *
+     * @return string Bookmark's tags as a string, separated by a separator
+     */
+    public function getTagsString(string $separator = ' '): string
+    {
+        return tags_array2str($this->getTags(), $separator);
+    }
+
+    /**
+     * @return bool
+     */
+    public function isNote(): bool
+    {
+        // We check empty value to get a valid result if the link has not been saved yet
+        return empty($this->url) || startsWith($this->url, '/shaare/') || $this->url[0] === '?';
+    }
+
+    /**
+     * Set tags from a string.
+     * Note:
+     *   - tags must be separated whether by a space or a comma
+     *   - multiple spaces will be removed
+     *   - trailing dash in tags will be removed
+     *
+     * @param string|null $tags
+     * @param string      $separator Tags separator loaded from the config file.
+     *
+     * @return $this
+     */
+    public function setTagsString(?string $tags, string $separator = ' '): Bookmark
+    {
+        $this->setTags(tags_str2array($tags, $separator));
+
+        return $this;
+    }
+
+    /**
+     * Get entire additionalContent array.
+     *
+     * @return mixed[]
+     */
+    public function getAdditionalContent(): array
+    {
+        return $this->additionalContent;
+    }
+
+    /**
+     * Set a single entry in additionalContent, by key.
+     *
+     * @param string     $key
+     * @param mixed|null $value Any type of value can be set.
+     *
+     * @return $this
+     */
+    public function setAdditionalContentEntry(string $key, $value): self
+    {
+        $this->additionalContent[$key] = $value;
+
+        return $this;
+    }
+
+    /**
+     * Get a single entry in additionalContent, by key.
+     *
+     * @param string $key
+     * @param mixed|null $default
+     *
+     * @return mixed|null can be any type or even null.
+     */
+    public function getAdditionalContentEntry(string $key, $default = null)
+    {
+        return array_key_exists($key, $this->additionalContent) ? $this->additionalContent[$key] : $default;
+    }
+
+    /**
+     * Rename a tag in tags list.
+     *
+     * @param string $fromTag
+     * @param string $toTag
+     */
+    public function renameTag(string $fromTag, string $toTag): void
+    {
+        if (($pos = array_search($fromTag, $this->tags ?? [])) !== false) {
+            $this->tags[$pos] = trim($toTag);
+        }
+    }
+
+    /**
+     * Add a tag in tags list.
+     *
+     * @param string $tag
+     */
+    public function addTag(string $tag): self
+    {
+        return $this->setTags(array_unique(array_merge($this->getTags(), [$tag])));
+    }
+
+    /**
+     * Delete a tag from tags list.
+     *
+     * @param string $tag
+     */
+    public function deleteTag(string $tag): void
+    {
+        while (($pos = array_search($tag, $this->tags ?? [])) !== false) {
+            unset($this->tags[$pos]);
+            $this->tags = array_values($this->tags);
+        }
+    }
+}

application/bookmark/BookmarkArray.php

@@ -0,0 +1,264 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Bookmark;
+
+use Shaarli\Bookmark\Exception\InvalidBookmarkException;
+
+/**
+ * Class BookmarkArray
+ *
+ * Implementing ArrayAccess, this allows us to use the bookmark list
+ * as an array and iterate over it.
+ *
+ * @package Shaarli\Bookmark
+ */
+class BookmarkArray implements \Iterator, \Countable, \ArrayAccess
+{
+    /**
+     * @var Bookmark[]
+     */
+    protected $bookmarks;
+
+    /**
+     * @var array List of all bookmarks IDS mapped with their array offset.
+     *            Map: id->offset.
+     */
+    protected $ids;
+
+    /**
+     * @var int Position in the $this->keys array (for the Iterator interface)
+     */
+    protected $position;
+
+    /**
+     * @var array List of offset keys (for the Iterator interface implementation)
+     */
+    protected $keys;
+
+    /**
+     * @var array List of all recorded URLs (key=url, value=bookmark offset)
+     *            for fast reserve search (url-->bookmark offset)
+     */
+    protected $urls;
+
+    public function __construct()
+    {
+        $this->ids = [];
+        $this->bookmarks = [];
+        $this->keys = [];
+        $this->urls = [];
+        $this->position = 0;
+    }
+
+    /**
+     * Countable - Counts elements of an object
+     *
+     * @return int Number of bookmarks
+     */
+    public function count(): int
+    {
+        return count($this->bookmarks);
+    }
+
+    /**
+     * ArrayAccess - Assigns a value to the specified offset
+     *
+     * @param int      $offset Bookmark ID
+     * @param Bookmark $value  instance
+     *
+     * @throws InvalidBookmarkException
+     */
+    public function offsetSet($offset, $value): void
+    {
+        if (
+            ! $value instanceof Bookmark
+            || $value->getId() === null || empty($value->getUrl())
+            || ($offset !== null && ! is_int($offset)) || ! is_int($value->getId())
+            || $offset !== null && $offset !== $value->getId()
+        ) {
+            throw new InvalidBookmarkException($value);
+        }
+
+        // If the bookmark exists, we reuse the real offset, otherwise new entry
+        if ($offset !== null) {
+            $existing = $this->getBookmarkOffset($offset);
+        } else {
+            $existing = $this->getBookmarkOffset($value->getId());
+        }
+
+        if ($existing !== null) {
+            $offset = $existing;
+        } else {
+            $offset = count($this->bookmarks);
+        }
+
+        $this->bookmarks[$offset] = $value;
+        $this->urls[$value->getUrl()] = $offset;
+        $this->ids[$value->getId()] = $offset;
+    }
+
+    /**
+     * ArrayAccess - Whether or not an offset exists
+     *
+     * @param int $offset Bookmark ID
+     *
+     * @return bool true if it exists, false otherwise
+     */
+    public function offsetExists($offset): bool
+    {
+        return array_key_exists($this->getBookmarkOffset($offset), $this->bookmarks);
+    }
+
+    /**
+     * ArrayAccess - Unsets an offset
+     *
+     * @param int $offset Bookmark ID
+     */
+    public function offsetUnset($offset): void
+    {
+        $realOffset = $this->getBookmarkOffset($offset);
+        $url = $this->bookmarks[$realOffset]->getUrl();
+        unset($this->urls[$url]);
+        unset($this->ids[$offset]);
+        unset($this->bookmarks[$realOffset]);
+    }
+
+    /**
+     * ArrayAccess - Returns the value at specified offset
+     *
+     * @param int $offset Bookmark ID
+     *
+     * @return Bookmark|null The Bookmark if found, null otherwise
+     */
+    public function offsetGet($offset): ?Bookmark
+    {
+        $realOffset = $this->getBookmarkOffset($offset);
+        return isset($this->bookmarks[$realOffset]) ? $this->bookmarks[$realOffset] : null;
+    }
+
+    /**
+     * Iterator - Returns the current element
+     *
+     * @return Bookmark corresponding to the current position
+     */
+    public function current(): Bookmark
+    {
+        return $this[$this->keys[$this->position]];
+    }
+
+    /**
+     * Iterator - Returns the key of the current element
+     *
+     * @return int Bookmark ID corresponding to the current position
+     */
+    public function key(): int
+    {
+        return $this->keys[$this->position];
+    }
+
+    /**
+     * Iterator - Moves forward to next element
+     */
+    public function next(): void
+    {
+        ++$this->position;
+    }
+
+    /**
+     * Iterator - Rewinds the Iterator to the first element
+     *
+     * Entries are sorted by date (latest first)
+     */
+    public function rewind(): void
+    {
+        $this->keys = array_keys($this->ids);
+        $this->position = 0;
+    }
+
+    /**
+     * Iterator - Checks if current position is valid
+     *
+     * @return bool true if the current Bookmark ID exists, false otherwise
+     */
+    public function valid(): bool
+    {
+        return isset($this->keys[$this->position]);
+    }
+
+    /**
+     * Returns a bookmark offset in bookmarks array from its unique ID.
+     *
+     * @param int|null $id Persistent ID of a bookmark.
+     *
+     * @return int Real offset in local array, or null if doesn't exist.
+     */
+    protected function getBookmarkOffset(?int $id): ?int
+    {
+        if ($id !== null && isset($this->ids[$id])) {
+            return $this->ids[$id];
+        }
+        return null;
+    }
+
+    /**
+     * Return the next key for bookmark creation.
+     * E.g. If the last ID is 597, the next will be 598.
+     *
+     * @return int next ID.
+     */
+    public function getNextId(): int
+    {
+        if (!empty($this->ids)) {
+            return max(array_keys($this->ids)) + 1;
+        }
+        return 0;
+    }
+
+    /**
+     * @param string $url
+     *
+     * @return Bookmark|null
+     */
+    public function getByUrl(string $url): ?Bookmark
+    {
+        if (
+            ! empty($url)
+            && isset($this->urls[$url])
+            && isset($this->bookmarks[$this->urls[$url]])
+        ) {
+            return $this->bookmarks[$this->urls[$url]];
+        }
+        return null;
+    }
+
+    /**
+     * Reorder links by creation date (newest first).
+     *
+     * Also update the urls and ids mapping arrays.
+     *
+     * @param string $order        ASC|DESC
+     * @param bool   $ignoreSticky If set to true, sticky bookmarks won't be first
+     */
+    public function reorder(string $order = 'DESC', bool $ignoreSticky = false): void
+    {
+        $order = $order === 'ASC' ? -1 : 1;
+        // Reorder array by dates.
+        usort($this->bookmarks, function ($a, $b) use ($order, $ignoreSticky) {
+            /** @var $a Bookmark */
+            /** @var $b Bookmark */
+            if (false === $ignoreSticky && $a->isSticky() !== $b->isSticky()) {
+                return $a->isSticky() ? -1 : 1;
+            }
+            return $a->getCreated() < $b->getCreated() ? 1 * $order : -1 * $order;
+        });
+
+        $this->urls = [];
+        $this->ids = [];
+        foreach ($this->bookmarks as $key => $bookmark) {
+            $this->urls[$bookmark->getUrl()] = $key;
+            $this->ids[$bookmark->getId()] = $key;
+        }
+    }
+}

application/bookmark/BookmarkFileService.php

@@ -0,0 +1,443 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Bookmark;
+
+use DateTime;
+use Exception;
+use malkusch\lock\mutex\Mutex;
+use Shaarli\Bookmark\Exception\BookmarkNotFoundException;
+use Shaarli\Bookmark\Exception\DatastoreNotInitializedException;
+use Shaarli\Bookmark\Exception\EmptyDataStoreException;
+use Shaarli\Config\ConfigManager;
+use Shaarli\Formatter\BookmarkMarkdownFormatter;
+use Shaarli\History;
+use Shaarli\Legacy\LegacyLinkDB;
+use Shaarli\Legacy\LegacyUpdater;
+use Shaarli\Plugin\PluginManager;
+use Shaarli\Render\PageCacheManager;
+use Shaarli\Updater\UpdaterUtils;
+
+/**
+ * Class BookmarksService
+ *
+ * This is the entry point to manipulate the bookmark DB.
+ * It manipulates loads links from a file data store containing all bookmarks.
+ *
+ * It also triggers the legacy format (bookmarks as arrays) migration.
+ */
+class BookmarkFileService implements BookmarkServiceInterface
+{
+    /** @var Bookmark[] instance */
+    protected $bookmarks;
+
+    /** @var BookmarkIO instance */
+    protected $bookmarksIO;
+
+    /** @var BookmarkFilter */
+    protected $bookmarkFilter;
+
+    /** @var ConfigManager instance */
+    protected $conf;
+
+    /** @var PluginManager */
+    protected $pluginManager;
+
+    /** @var History instance */
+    protected $history;
+
+    /** @var PageCacheManager instance */
+    protected $pageCacheManager;
+
+    /** @var bool true for logged in users. Default value to retrieve private bookmarks. */
+    protected $isLoggedIn;
+
+    /** @var Mutex */
+    protected $mutex;
+
+    /**
+     * @inheritDoc
+     */
+    public function __construct(
+        ConfigManager $conf,
+        PluginManager $pluginManager,
+        History $history,
+        Mutex $mutex,
+        bool $isLoggedIn
+    ) {
+        $this->conf = $conf;
+        $this->history = $history;
+        $this->mutex = $mutex;
+        $this->pageCacheManager = new PageCacheManager($this->conf->get('resource.page_cache'), $isLoggedIn);
+        $this->bookmarksIO = new BookmarkIO($this->conf, $this->mutex);
+        $this->isLoggedIn = $isLoggedIn;
+
+        if (!$this->isLoggedIn && $this->conf->get('privacy.hide_public_links', false)) {
+            $this->bookmarks = new BookmarkArray();
+        } else {
+            try {
+                $this->bookmarks = $this->bookmarksIO->read();
+            } catch (EmptyDataStoreException | DatastoreNotInitializedException $e) {
+                $this->bookmarks = new BookmarkArray();
+
+                if ($this->isLoggedIn) {
+                    // Datastore file does not exists, we initialize it with default bookmarks.
+                    if ($e instanceof DatastoreNotInitializedException) {
+                        $this->initialize();
+                    } else {
+                        $this->save();
+                    }
+                }
+            }
+
+            if (! $this->bookmarks instanceof BookmarkArray) {
+                $this->migrate();
+                exit(
+                    'Your data store has been migrated, please reload the page.' . PHP_EOL .
+                    'If this message keeps showing up, please delete data/updates.txt file.'
+                );
+            }
+        }
+
+        $this->pluginManager = $pluginManager;
+        $this->bookmarkFilter = new BookmarkFilter($this->bookmarks, $this->conf, $this->pluginManager);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function findByHash(string $hash, string $privateKey = null): Bookmark
+    {
+        $bookmark = $this->bookmarkFilter->filter(BookmarkFilter::$FILTER_HASH, $hash);
+        // PHP 7.3 introduced array_key_first() to avoid this hack
+        $first = reset($bookmark);
+        if (
+            !$this->isLoggedIn
+            && $first->isPrivate()
+            && (empty($privateKey) || $privateKey !== $first->getAdditionalContentEntry('private_key'))
+        ) {
+            throw new BookmarkNotFoundException();
+        }
+
+        return $first;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function findByUrl(string $url): ?Bookmark
+    {
+        return $this->bookmarks->getByUrl($url);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function search(
+        array $request = [],
+        string $visibility = null,
+        bool $caseSensitive = false,
+        bool $untaggedOnly = false,
+        bool $ignoreSticky = false,
+        array $pagination = []
+    ): SearchResult {
+        if ($visibility === null) {
+            $visibility = $this->isLoggedIn ? BookmarkFilter::$ALL : BookmarkFilter::$PUBLIC;
+        }
+
+        // Filter bookmark database according to parameters.
+        $searchTags = isset($request['searchtags']) ? $request['searchtags'] : '';
+        $searchTerm = isset($request['searchterm']) ? $request['searchterm'] : '';
+
+        if ($ignoreSticky) {
+            $this->bookmarks->reorder('DESC', true);
+        }
+
+        $bookmarks = $this->bookmarkFilter->filter(
+            BookmarkFilter::$FILTER_TAG | BookmarkFilter::$FILTER_TEXT,
+            [$searchTags, $searchTerm],
+            $caseSensitive,
+            $visibility,
+            $untaggedOnly
+        );
+
+        return SearchResult::getSearchResult(
+            $bookmarks,
+            $pagination['offset'] ?? 0,
+            $pagination['limit'] ?? null,
+            $pagination['allowOutOfBounds'] ?? false
+        );
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function get(int $id, string $visibility = null): Bookmark
+    {
+        if (! isset($this->bookmarks[$id])) {
+            throw new BookmarkNotFoundException();
+        }
+
+        if ($visibility === null) {
+            $visibility = $this->isLoggedIn ? BookmarkFilter::$ALL : BookmarkFilter::$PUBLIC;
+        }
+
+        $bookmark = $this->bookmarks[$id];
+        if (
+            ($bookmark->isPrivate() && $visibility != 'all' && $visibility != 'private')
+            || (! $bookmark->isPrivate() && $visibility != 'all' && $visibility != 'public')
+        ) {
+            throw new Exception('Unauthorized');
+        }
+
+        return $bookmark;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function set(Bookmark $bookmark, bool $save = true): Bookmark
+    {
+        if (true !== $this->isLoggedIn) {
+            throw new Exception(t('You\'re not authorized to alter the datastore'));
+        }
+        if (! isset($this->bookmarks[$bookmark->getId()])) {
+            throw new BookmarkNotFoundException();
+        }
+        $bookmark->validate();
+
+        $bookmark->setUpdated(new DateTime());
+        $this->bookmarks[$bookmark->getId()] = $bookmark;
+        if ($save === true) {
+            $this->save();
+            $this->history->updateLink($bookmark);
+        }
+        return $this->bookmarks[$bookmark->getId()];
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function add(Bookmark $bookmark, bool $save = true): Bookmark
+    {
+        if (true !== $this->isLoggedIn) {
+            throw new Exception(t('You\'re not authorized to alter the datastore'));
+        }
+        if (!empty($bookmark->getId())) {
+            throw new Exception(t('This bookmarks already exists'));
+        }
+        $bookmark->setId($this->bookmarks->getNextId());
+        $bookmark->validate();
+
+        $this->bookmarks[$bookmark->getId()] = $bookmark;
+        if ($save === true) {
+            $this->save();
+            $this->history->addLink($bookmark);
+        }
+        return $this->bookmarks[$bookmark->getId()];
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function addOrSet(Bookmark $bookmark, bool $save = true): Bookmark
+    {
+        if (true !== $this->isLoggedIn) {
+            throw new Exception(t('You\'re not authorized to alter the datastore'));
+        }
+        if ($bookmark->getId() === null) {
+            return $this->add($bookmark, $save);
+        }
+        return $this->set($bookmark, $save);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function remove(Bookmark $bookmark, bool $save = true): void
+    {
+        if (true !== $this->isLoggedIn) {
+            throw new Exception(t('You\'re not authorized to alter the datastore'));
+        }
+        if (! isset($this->bookmarks[$bookmark->getId()])) {
+            throw new BookmarkNotFoundException();
+        }
+
+        unset($this->bookmarks[$bookmark->getId()]);
+        if ($save === true) {
+            $this->save();
+            $this->history->deleteLink($bookmark);
+        }
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function exists(int $id, string $visibility = null): bool
+    {
+        if (! isset($this->bookmarks[$id])) {
+            return false;
+        }
+
+        if ($visibility === null) {
+            $visibility = $this->isLoggedIn ? 'all' : 'public';
+        }
+
+        $bookmark = $this->bookmarks[$id];
+        if (
+            ($bookmark->isPrivate() && $visibility != 'all' && $visibility != 'private')
+            || (! $bookmark->isPrivate() && $visibility != 'all' && $visibility != 'public')
+        ) {
+            return false;
+        }
+
+        return true;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function count(string $visibility = null): int
+    {
+        return $this->search([], $visibility)->getResultCount();
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function save(): void
+    {
+        if (true !== $this->isLoggedIn) {
+            // TODO: raise an Exception instead
+            die('You are not authorized to change the database.');
+        }
+
+        $this->bookmarks->reorder();
+        $this->bookmarksIO->write($this->bookmarks);
+        $this->pageCacheManager->invalidateCaches();
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function bookmarksCountPerTag(array $filteringTags = [], string $visibility = null): array
+    {
+        $searchResult = $this->search(['searchtags' => $filteringTags], $visibility);
+        $tags = [];
+        $caseMapping = [];
+        foreach ($searchResult->getBookmarks() as $bookmark) {
+            foreach ($bookmark->getTags() as $tag) {
+                if (
+                    empty($tag)
+                    || (! $this->isLoggedIn && startsWith($tag, '.'))
+                    || $tag === BookmarkMarkdownFormatter::NO_MD_TAG
+                    || in_array($tag, $filteringTags, true)
+                ) {
+                    continue;
+                }
+
+                // The first case found will be displayed.
+                if (!isset($caseMapping[strtolower($tag)])) {
+                    $caseMapping[strtolower($tag)] = $tag;
+                    $tags[$caseMapping[strtolower($tag)]] = 0;
+                }
+                $tags[$caseMapping[strtolower($tag)]]++;
+            }
+        }
+
+        /*
+         * Formerly used arsort(), which doesn't define the sort behaviour for equal values.
+         * Also, this function doesn't produce the same result between PHP 5.6 and 7.
+         *
+         * So we now use array_multisort() to sort tags by DESC occurrences,
+         * then ASC alphabetically for equal values.
+         *
+         * @see https://github.com/shaarli/Shaarli/issues/1142
+         */
+        $keys = array_keys($tags);
+        $tmpTags = array_combine($keys, $keys);
+        array_multisort($tags, SORT_DESC, $tmpTags, SORT_ASC, $tags);
+
+        return $tags;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function findByDate(
+        \DateTimeInterface $from,
+        \DateTimeInterface $to,
+        ?\DateTimeInterface &$previous,
+        ?\DateTimeInterface &$next
+    ): array {
+        $out = [];
+        $previous = null;
+        $next = null;
+
+        foreach ($this->search([], null, false, false, true)->getBookmarks() as $bookmark) {
+            if ($to < $bookmark->getCreated()) {
+                $next = $bookmark->getCreated();
+            } elseif ($from < $bookmark->getCreated() && $to > $bookmark->getCreated()) {
+                $out[] = $bookmark;
+            } else {
+                if ($previous !== null) {
+                    break;
+                }
+                $previous = $bookmark->getCreated();
+            }
+        }
+
+        return $out;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getLatest(): ?Bookmark
+    {
+        foreach ($this->search([], null, false, false, true)->getBookmarks() as $bookmark) {
+            return $bookmark;
+        }
+
+        return null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function initialize(): void
+    {
+        $initializer = new BookmarkInitializer($this);
+        $initializer->initialize();
+
+        if (true === $this->isLoggedIn) {
+            $this->save();
+        }
+    }
+
+    /**
+     * Handles migration to the new database format (BookmarksArray).
+     */
+    protected function migrate(): void
+    {
+        $bookmarkDb = new LegacyLinkDB(
+            $this->conf->get('resource.datastore'),
+            true,
+            false
+        );
+        $updater = new LegacyUpdater(
+            UpdaterUtils::readUpdatesFile($this->conf->get('resource.updates')),
+            $bookmarkDb,
+            $this->conf,
+            true
+        );
+        $newUpdates = $updater->update();
+        if (! empty($newUpdates)) {
+            UpdaterUtils::writeUpdatesFile(
+                $this->conf->get('resource.updates'),
+                $updater->getDoneUpdates()
+            );
+        }
+    }
+}

application/bookmark/BookmarkFilter.php

@@ -0,0 +1,635 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Bookmark;
+
+use Shaarli\Bookmark\Exception\BookmarkNotFoundException;
+use Shaarli\Config\ConfigManager;
+use Shaarli\Plugin\PluginManager;
+
+/**
+ * Class LinkFilter.
+ *
+ * Perform search and filter operation on link data list.
+ */
+class BookmarkFilter
+{
+    /**
+     * @var string permalinks.
+     */
+    public static $FILTER_HASH = 'permalink';
+
+    /**
+     * @var string text search.
+     */
+    public static $FILTER_TEXT = 'fulltext';
+
+    /**
+     * @var string tag filter.
+     */
+    public static $FILTER_TAG = 'tags';
+
+    /**
+     * @var string filter by day.
+     */
+    public static $DEFAULT = 'NO_FILTER';
+
+    /** @var string Visibility: all */
+    public static $ALL = 'all';
+
+    /** @var string Visibility: public */
+    public static $PUBLIC = 'public';
+
+    /** @var string Visibility: private */
+    public static $PRIVATE = 'private';
+
+    /**
+     * @var string Allowed characters for hashtags (regex syntax).
+     */
+    public static $HASHTAG_CHARS = '\p{Pc}\p{N}\p{L}\p{Mn}';
+
+    /**
+     * @var Bookmark[] all available bookmarks.
+     */
+    private $bookmarks;
+
+    /** @var ConfigManager */
+    protected $conf;
+
+    /** @var PluginManager */
+    protected $pluginManager;
+
+    /**
+     * @param Bookmark[] $bookmarks initialization.
+     */
+    public function __construct($bookmarks, ConfigManager $conf, PluginManager $pluginManager)
+    {
+        $this->bookmarks = $bookmarks;
+        $this->conf = $conf;
+        $this->pluginManager = $pluginManager;
+    }
+
+    /**
+     * Filter bookmarks according to parameters.
+     *
+     * @param string $type          Type of filter (eg. tags, permalink, etc.).
+     * @param mixed  $request       Filter content.
+     * @param bool   $casesensitive Optional: Perform case sensitive filter if true.
+     * @param string $visibility    Optional: return only all/private/public bookmarks
+     * @param bool   $untaggedonly  Optional: return only untagged bookmarks. Applies only if $type includes FILTER_TAG
+     *
+     * @return Bookmark[] filtered bookmark list.
+     *
+     * @throws BookmarkNotFoundException
+     */
+    public function filter(
+        string $type,
+        $request,
+        bool $casesensitive = false,
+        string $visibility = 'all',
+        bool $untaggedonly = false
+    ) {
+        if (!in_array($visibility, ['all', 'public', 'private'])) {
+            $visibility = 'all';
+        }
+
+        switch ($type) {
+            case self::$FILTER_HASH:
+                return $this->filterSmallHash($request);
+            case self::$FILTER_TAG | self::$FILTER_TEXT: // == "vuotext"
+                $noRequest = empty($request) || (empty($request[0]) && empty($request[1]));
+                if ($noRequest) {
+                    if ($untaggedonly) {
+                        return $this->filterUntagged($visibility);
+                    }
+                    return $this->noFilter($visibility);
+                }
+                if ($untaggedonly) {
+                    $filtered = $this->filterUntagged($visibility);
+                } else {
+                    $filtered = $this->bookmarks;
+                }
+                if (!empty($request[0])) {
+                    $filtered = (new BookmarkFilter($filtered, $this->conf, $this->pluginManager))
+                        ->filterTags($request[0], $casesensitive, $visibility)
+                    ;
+                }
+                if (!empty($request[1])) {
+                    $filtered = (new BookmarkFilter($filtered, $this->conf, $this->pluginManager))
+                        ->filterFulltext($request[1], $visibility)
+                    ;
+                }
+                return $filtered;
+            case self::$FILTER_TEXT:
+                return $this->filterFulltext($request, $visibility);
+            case self::$FILTER_TAG:
+                if ($untaggedonly) {
+                    return $this->filterUntagged($visibility);
+                } else {
+                    return $this->filterTags($request, $casesensitive, $visibility);
+                }
+            default:
+                return $this->noFilter($visibility);
+        }
+    }
+
+    /**
+     * Unknown filter, but handle private only.
+     *
+     * @param string $visibility Optional: return only all/private/public bookmarks
+     *
+     * @return Bookmark[] filtered bookmarks.
+     */
+    private function noFilter(string $visibility = 'all')
+    {
+        $out = [];
+        foreach ($this->bookmarks as $key => $value) {
+            if (
+                !$this->pluginManager->filterSearchEntry(
+                    $value,
+                    ['source' => 'no_filter', 'visibility' => $visibility]
+                )
+            ) {
+                continue;
+            }
+
+            if ($visibility === 'all') {
+                $out[$key] = $value;
+            } elseif ($value->isPrivate() && $visibility === 'private') {
+                $out[$key] = $value;
+            } elseif (!$value->isPrivate() && $visibility === 'public') {
+                $out[$key] = $value;
+            }
+        }
+
+        return $out;
+    }
+
+    /**
+     * Returns the shaare corresponding to a smallHash.
+     *
+     * @param string $smallHash permalink hash.
+     *
+     * @return Bookmark[] $filtered array containing permalink data.
+     *
+     * @throws BookmarkNotFoundException if the smallhash doesn't match any link.
+     */
+    private function filterSmallHash(string $smallHash)
+    {
+        foreach ($this->bookmarks as $key => $l) {
+            if ($smallHash == $l->getShortUrl()) {
+                // Yes, this is ugly and slow
+                return [$key => $l];
+            }
+        }
+
+        throw new BookmarkNotFoundException();
+    }
+
+    /**
+     * Returns the list of bookmarks corresponding to a full-text search
+     *
+     * Searches:
+     *  - in the URLs, title and description;
+     *  - are case-insensitive;
+     *  - terms surrounded by quotes " are exact terms search.
+     *  - terms starting with a dash - are excluded (except exact terms).
+     *
+     * Example:
+     *    print_r($mydb->filterFulltext('hollandais'));
+     *
+     * mb_convert_case($val, MB_CASE_LOWER, 'UTF-8')
+     *  - allows to perform searches on Unicode text
+     *  - see https://github.com/shaarli/Shaarli/issues/75 for examples
+     *
+     * @param string $searchterms search query.
+     * @param string $visibility  Optional: return only all/private/public bookmarks.
+     *
+     * @return Bookmark[] search results.
+     */
+    private function filterFulltext(string $searchterms, string $visibility = 'all')
+    {
+        if (empty($searchterms)) {
+            return $this->noFilter($visibility);
+        }
+
+        $filtered = [];
+        $search = mb_convert_case(html_entity_decode($searchterms), MB_CASE_LOWER, 'UTF-8');
+        $exactRegex = '/"([^"]+)"/';
+        // Retrieve exact search terms.
+        preg_match_all($exactRegex, $search, $exactSearch);
+        $exactSearch = array_values(array_filter($exactSearch[1]));
+
+        // Remove exact search terms to get AND terms search.
+        $explodedSearchAnd = explode(' ', trim(preg_replace($exactRegex, '', $search)));
+        $explodedSearchAnd = array_values(array_filter($explodedSearchAnd));
+
+        // Filter excluding terms and update andSearch.
+        $excludeSearch = [];
+        $andSearch = [];
+        foreach ($explodedSearchAnd as $needle) {
+            if ($needle[0] == '-' && strlen($needle) > 1) {
+                $excludeSearch[] = substr($needle, 1);
+            } else {
+                $andSearch[] = $needle;
+            }
+        }
+
+        // Iterate over every stored link.
+        foreach ($this->bookmarks as $id => $bookmark) {
+            if (
+                !$this->pluginManager->filterSearchEntry(
+                    $bookmark,
+                    [
+                    'source' => 'fulltext',
+                    'searchterms' => $searchterms,
+                    'andSearch' => $andSearch,
+                    'exactSearch' => $exactSearch,
+                    'excludeSearch' => $excludeSearch,
+                    'visibility' => $visibility
+                    ]
+                )
+            ) {
+                continue;
+            }
+
+            // ignore non private bookmarks when 'privatonly' is on.
+            if ($visibility !== 'all') {
+                if (!$bookmark->isPrivate() && $visibility === 'private') {
+                    continue;
+                } elseif ($bookmark->isPrivate() && $visibility === 'public') {
+                    continue;
+                }
+            }
+
+            $lengths = [];
+            $content = $this->buildFullTextSearchableLink($bookmark, $lengths);
+
+            // Be optimistic
+            $found = true;
+            $foundPositions = [];
+
+            // First, we look for exact term search
+            // Then iterate over keywords, if keyword is not found,
+            // no need to check for the others. We want all or nothing.
+            foreach ([$exactSearch, $andSearch] as $search) {
+                for ($i = 0; $i < count($search) && $found !== false; $i++) {
+                    $found = mb_strpos($content, $search[$i]);
+                    if ($found === false) {
+                        break;
+                    }
+
+                    $foundPositions[] = ['start' => $found, 'end' => $found + mb_strlen($search[$i])];
+                }
+            }
+
+            // Exclude terms.
+            for ($i = 0; $i < count($excludeSearch) && $found !== false; $i++) {
+                $found = strpos($content, $excludeSearch[$i]) === false;
+            }
+
+            if ($found !== false) {
+                $bookmark->setAdditionalContentEntry(
+                    'search_highlight',
+                    $this->postProcessFoundPositions($lengths, $foundPositions)
+                );
+
+                $filtered[$id] = $bookmark;
+            }
+        }
+
+        return $filtered;
+    }
+
+    /**
+     * Returns the list of bookmarks associated with a given list of tags
+     *
+     * You can specify one or more tags, separated by space or a comma, e.g.
+     *  print_r($mydb->filterTags('linux programming'));
+     *
+     * @param string|array $tags          list of tags, separated by commas or blank spaces if passed as string.
+     * @param bool         $casesensitive ignore case if false.
+     * @param string       $visibility    Optional: return only all/private/public bookmarks.
+     *
+     * @return Bookmark[] filtered bookmarks.
+     */
+    public function filterTags($tags, bool $casesensitive = false, string $visibility = 'all')
+    {
+        $tagsSeparator = $this->conf->get('general.tags_separator', ' ');
+        // get single tags (we may get passed an array, even though the docs say different)
+        $inputTags = $tags;
+        if (!is_array($tags)) {
+            // we got an input string, split tags
+            $inputTags = tags_str2array($inputTags, $tagsSeparator);
+        }
+        if (count($inputTags) === 0) {
+            // no input tags
+            return $this->noFilter($visibility);
+        }
+
+        // If we only have public visibility, we can't look for hidden tags
+        if ($visibility === self::$PUBLIC) {
+            $inputTags = array_values(array_filter($inputTags, function ($tag) {
+                return ! startsWith($tag, '.');
+            }));
+
+            if (empty($inputTags)) {
+                return [];
+            }
+        }
+
+        // build regex from all tags
+        $re_and = implode(array_map([$this, 'tag2regex'], $inputTags));
+        $re = '/^' . $re_and;
+
+        $orTags = array_filter(array_map(function ($tag) {
+            return startsWith($tag, '~') ? substr($tag, 1) : null;
+        }, $inputTags));
+
+        $re_or = implode('|', array_map([$this, 'tag2matchterm'], $orTags));
+        if ($re_or) {
+            $re_or = '(' . $re_or . ')';
+            $re .= $this->term2match($re_or, false);
+        }
+
+        $re .= '.*$/';
+        if (!$casesensitive) {
+            // make regex case insensitive
+            $re .= 'i';
+        }
+
+        // create resulting array
+        $filtered = [];
+
+        // iterate over each link
+        foreach ($this->bookmarks as $key => $bookmark) {
+            if (
+                !$this->pluginManager->filterSearchEntry(
+                    $bookmark,
+                    [
+                    'source' => 'tags',
+                    'tags' => $tags,
+                    'casesensitive' => $casesensitive,
+                    'visibility' => $visibility
+                    ]
+                )
+            ) {
+                continue;
+            }
+
+            // check level of visibility
+            // ignore non private bookmarks when 'privateonly' is on.
+            if ($visibility !== 'all') {
+                if (!$bookmark->isPrivate() && $visibility === 'private') {
+                    continue;
+                } elseif ($bookmark->isPrivate() && $visibility === 'public') {
+                    continue;
+                }
+            }
+            // build search string, start with tags of current link
+            $search = $bookmark->getTagsString($tagsSeparator);
+            if (strlen(trim($bookmark->getDescription())) && strpos($bookmark->getDescription(), '#') !== false) {
+                // description given and at least one possible tag found
+                $descTags = [];
+                // find all tags in the form of #tag in the description
+                preg_match_all(
+                    '/(?<![' . self::$HASHTAG_CHARS . '])#([' . self::$HASHTAG_CHARS . ']+?)\b/sm',
+                    $bookmark->getDescription(),
+                    $descTags
+                );
+                if (count($descTags[1])) {
+                    // there were some tags in the description, add them to the search string
+                    $search .= $tagsSeparator . tags_array2str($descTags[1], $tagsSeparator);
+                }
+            }
+            // match regular expression with search string
+            if (!preg_match($re, $search)) {
+                // this entry does _not_ match our regex
+                continue;
+            }
+            $filtered[$key] = $bookmark;
+        }
+
+        return $filtered;
+    }
+
+    /**
+     * Return only bookmarks without any tag.
+     *
+     * @param string $visibility return only all/private/public bookmarks.
+     *
+     * @return Bookmark[] filtered bookmarks.
+     */
+    public function filterUntagged(string $visibility)
+    {
+        $filtered = [];
+        foreach ($this->bookmarks as $key => $bookmark) {
+            if (
+                !$this->pluginManager->filterSearchEntry(
+                    $bookmark,
+                    ['source' => 'untagged', 'visibility' => $visibility]
+                )
+            ) {
+                continue;
+            }
+
+            if ($visibility !== 'all') {
+                if (!$bookmark->isPrivate() && $visibility === 'private') {
+                    continue;
+                } elseif ($bookmark->isPrivate() && $visibility === 'public') {
+                    continue;
+                }
+            }
+
+            if (empty($bookmark->getTags())) {
+                $filtered[$key] = $bookmark;
+            }
+        }
+
+        return $filtered;
+    }
+
+    /**
+     * Convert a list of tags (str) to an array. Also
+     * - handle case sensitivity.
+     * - accepts spaces commas as separator.
+     *
+     * @param string $tags          string containing a list of tags.
+     * @param bool   $casesensitive will convert everything to lowercase if false.
+     *
+     * @return string[] filtered tags string.
+     */
+    public static function tagsStrToArray(string $tags, bool $casesensitive): array
+    {
+        // We use UTF-8 conversion to handle various graphemes (i.e. cyrillic, or greek)
+        $tagsOut = $casesensitive ? $tags : mb_convert_case($tags, MB_CASE_LOWER, 'UTF-8');
+        $tagsOut = str_replace(',', ' ', $tagsOut);
+
+        return preg_split('/\s+/', $tagsOut, -1, PREG_SPLIT_NO_EMPTY);
+    }
+
+    /**
+     * generate a regex fragment out of a tag
+     *
+     * @param string $tag to generate regexs from. may start with '-'
+     * to negate, contain '*' as wildcard. Tags starting with '~' are
+     * treated separately as an 'OR' clause.
+     *
+     * @return string generated regex fragment
+     */
+    protected function tag2regex(string $tag): string
+    {
+        $tagsSeparator = $this->conf->get('general.tags_separator', ' ');
+        if (!$tag || $tag === "-" || $tag === "*" || $tag[0] === "~") {
+            // nothing to search, return empty regex
+            return '';
+        }
+        $negate = false;
+        if ($tag[0] === "+" && $tag[1]) {
+            $tag = substr($tag, 1); // use offset to start after '+' character
+        }
+        if ($tag[0] === "-") {
+            // query is negated
+            $tag = substr($tag, 1); // use offset to start after '-' character
+            $negate = true;
+        }
+        $term = $this->tag2matchterm($tag);
+
+        return $this->term2match($term, $negate);
+    }
+
+    /**
+     * generate a regex match term fragment out of a tag
+     *
+     * @param string $tag to to generate regexs from. This function
+     * assumes any leading flags ('-', '~') have been stripped. The
+     * wildcard flag '*' is expanded by this function and any other
+     * regex characters are escaped.
+     *
+     * @return string generated regex match term fragment
+     */
+    protected function tag2matchterm(string $tag): string
+    {
+        $tagsSeparator = $this->conf->get('general.tags_separator', ' ');
+        $len = strlen($tag);
+        $term = '';
+        // iterate over string, separating it into placeholder and content
+        $i = 0; // start at first character
+        for (; $i < $len; $i++) {
+            if ($tag[$i] === '*') {
+                // placeholder found
+                $term .= '[^' . $tagsSeparator . ']*?';
+            } else {
+                // regular characters
+                $offset = strpos($tag, '*', $i);
+                if ($offset === false) {
+                    // no placeholder found, set offset to end of string
+                    $offset = $len;
+                }
+                // subtract one, as we want to get before the placeholder or end of string
+                $offset -= 1;
+                // we got a tag name that we want to search for. escape any regex characters to prevent conflicts.
+                $term .= preg_quote(substr($tag, $i, $offset - $i + 1), '/');
+                // move $i on
+                $i = $offset;
+            }
+        }
+
+        return $term;
+    }
+
+    /**
+     * generate a regex fragment out of a match term
+     *
+     * @param string $term is the match term already generated by tag2matchterm
+     * @param bool $negate if true create a negative lookahead
+     *
+     * @return string generated regex fragment
+     */
+    protected function term2match(string $term, bool $negate): string
+    {
+        $tagsSeparator = $this->conf->get('general.tags_separator', ' ');
+        $regex = $negate ? '(?!' : '(?='; // use negative or positive lookahead
+
+        // before tag may only be the separator or the beginning
+        $regex .= '.*(?:^|' . $tagsSeparator . ')';
+
+        $regex .= $term;
+
+        // after the tag may only be the separator or the end
+        $regex .= '(?:$|' . $tagsSeparator . '))';
+        return $regex;
+    }
+
+    /**
+     * This method finalize the content of the foundPositions array,
+     * by associated all search results to their associated bookmark field,
+     * making sure that there is no overlapping results, etc.
+     *
+     * @param array $fieldLengths   Start and end positions of every bookmark fields in the aggregated bookmark content.
+     * @param array $foundPositions Positions where the search results were found in the aggregated content.
+     *
+     * @return array Updated $foundPositions, by bookmark field.
+     */
+    protected function postProcessFoundPositions(array $fieldLengths, array $foundPositions): array
+    {
+        // Sort results by starting position ASC.
+        usort($foundPositions, function (array $entryA, array $entryB): int {
+            return $entryA['start'] > $entryB['start'] ? 1 : -1;
+        });
+
+        $out = [];
+        $currentMax = -1;
+        foreach ($foundPositions as $foundPosition) {
+            // we do not allow overlapping highlights
+            if ($foundPosition['start'] < $currentMax) {
+                continue;
+            }
+
+            $currentMax = $foundPosition['end'];
+            foreach ($fieldLengths as $part => $length) {
+                if ($foundPosition['start'] < $length['start'] || $foundPosition['start'] > $length['end']) {
+                    continue;
+                }
+
+                $out[$part][] = [
+                    'start' => $foundPosition['start'] - $length['start'],
+                    'end' => $foundPosition['end'] - $length['start'],
+                ];
+                break;
+            }
+        }
+
+        return $out;
+    }
+
+    /**
+     * Concatenate link fields to search across fields. Adds a '\' separator for exact search terms.
+     * Also populate $length array with starting and ending positions of every bookmark field
+     * inside concatenated content.
+     *
+     * @param Bookmark $link
+     * @param array    $lengths (by reference)
+     *
+     * @return string Lowercase concatenated fields content.
+     */
+    protected function buildFullTextSearchableLink(Bookmark $link, array &$lengths): string
+    {
+        $tagString = $link->getTagsString($this->conf->get('general.tags_separator', ' '));
+        $content  = mb_convert_case($link->getTitle(), MB_CASE_LOWER, 'UTF-8') . '\\';
+        $content .= mb_convert_case($link->getDescription(), MB_CASE_LOWER, 'UTF-8') . '\\';
+        $content .= mb_convert_case($link->getUrl(), MB_CASE_LOWER, 'UTF-8') . '\\';
+        $content .= mb_convert_case($tagString, MB_CASE_LOWER, 'UTF-8') . '\\';
+
+        $lengths['title'] = ['start' => 0, 'end' => mb_strlen($link->getTitle())];
+        $nextField = $lengths['title']['end'] + 1;
+        $lengths['description'] = ['start' => $nextField, 'end' => $nextField + mb_strlen($link->getDescription())];
+        $nextField = $lengths['description']['end'] + 1;
+        $lengths['url'] = ['start' => $nextField, 'end' => $nextField + mb_strlen($link->getUrl())];
+        $nextField = $lengths['url']['end'] + 1;
+        $lengths['tags'] = ['start' => $nextField, 'end' => $nextField + mb_strlen($tagString)];
+
+        return $content;
+    }
+}

application/bookmark/BookmarkIO.php

@@ -0,0 +1,177 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Bookmark;
+
+use malkusch\lock\exception\LockAcquireException;
+use malkusch\lock\mutex\Mutex;
+use malkusch\lock\mutex\NoMutex;
+use Shaarli\Bookmark\Exception\DatastoreNotInitializedException;
+use Shaarli\Bookmark\Exception\EmptyDataStoreException;
+use Shaarli\Bookmark\Exception\InvalidWritableDataException;
+use Shaarli\Bookmark\Exception\NotEnoughSpaceException;
+use Shaarli\Bookmark\Exception\NotWritableDataStoreException;
+use Shaarli\Config\ConfigManager;
+
+/**
+ * Class BookmarkIO
+ *
+ * This class performs read/write operation to the file data store.
+ * Used by BookmarkFileService.
+ *
+ * @package Shaarli\Bookmark
+ */
+class BookmarkIO
+{
+    /**
+     * @var string Datastore file path
+     */
+    protected $datastore;
+
+    /**
+     * @var ConfigManager instance
+     */
+    protected $conf;
+
+
+    /** @var Mutex */
+    protected $mutex;
+
+    /**
+     * string Datastore PHP prefix
+     */
+    protected static $phpPrefix = '<?php /* ';
+    /**
+     * string Datastore PHP suffix
+     */
+    protected static $phpSuffix = ' */ ?>';
+
+    /**
+     * LinksIO constructor.
+     *
+     * @param ConfigManager $conf instance
+     */
+    public function __construct(ConfigManager $conf, Mutex $mutex = null)
+    {
+        if ($mutex === null) {
+            // This should only happen with legacy classes
+            $mutex = new NoMutex();
+        }
+        $this->conf = $conf;
+        $this->datastore = $conf->get('resource.datastore');
+        $this->mutex = $mutex;
+    }
+
+    /**
+     * Reads database from disk to memory
+     *
+     * @return Bookmark[]
+     *
+     * @throws NotWritableDataStoreException    Data couldn't be loaded
+     * @throws EmptyDataStoreException          Datastore file exists but does not contain any bookmark
+     * @throws DatastoreNotInitializedException File does not exists
+     */
+    public function read()
+    {
+        if (! file_exists($this->datastore)) {
+            throw new DatastoreNotInitializedException();
+        }
+
+        if (!is_writable($this->datastore)) {
+            throw new NotWritableDataStoreException($this->datastore);
+        }
+
+        $content = null;
+        $this->synchronized(function () use (&$content) {
+            $content = file_get_contents($this->datastore);
+        });
+
+        // Note that gzinflate is faster than gzuncompress.
+        // See: http://www.php.net/manual/en/function.gzdeflate.php#96439
+        $links = unserialize(gzinflate(base64_decode(
+            substr($content, strlen(self::$phpPrefix), -strlen(self::$phpSuffix))
+        )));
+
+        if (empty($links)) {
+            if (filesize($this->datastore) > 100) {
+                throw new NotWritableDataStoreException($this->datastore);
+            }
+            throw new EmptyDataStoreException();
+        }
+
+        return $links;
+    }
+
+    /**
+     * Saves the database from memory to disk
+     *
+     * @param Bookmark[] $links
+     *
+     * @throws NotWritableDataStoreException the datastore is not writable
+     * @throws InvalidWritableDataException
+     */
+    public function write($links)
+    {
+        if (is_file($this->datastore) && !is_writeable($this->datastore)) {
+            // The datastore exists but is not writeable
+            throw new NotWritableDataStoreException($this->datastore);
+        } elseif (!is_file($this->datastore) && !is_writeable(dirname($this->datastore))) {
+            // The datastore does not exist and its parent directory is not writeable
+            throw new NotWritableDataStoreException(dirname($this->datastore));
+        }
+
+        $data = base64_encode(gzdeflate(serialize($links)));
+
+        if (empty($data)) {
+            throw new InvalidWritableDataException();
+        }
+
+        $data = self::$phpPrefix . $data . self::$phpSuffix;
+
+        $this->synchronized(function () use ($data) {
+            if (!$this->checkDiskSpace($data)) {
+                throw new NotEnoughSpaceException();
+            }
+
+            file_put_contents(
+                $this->datastore,
+                $data
+            );
+        });
+    }
+
+    /**
+     * Wrapper applying mutex to provided function.
+     * If the lock can't be acquired (e.g. some shared hosting provider), we execute the function without mutex.
+     *
+     * @see https://github.com/shaarli/Shaarli/issues/1650
+     *
+     * @param callable $function
+     */
+    protected function synchronized(callable $function): void
+    {
+        try {
+            $this->mutex->synchronized($function);
+        } catch (LockAcquireException $exception) {
+            $function();
+        }
+    }
+
+    /**
+     * Make sure that there is enough disk space available to save the current data store.
+     * We add an arbitrary margin of 500kB.
+     *
+     * @param string $data to be saved
+     *
+     * @return bool True if data can safely be saved
+     */
+    public function checkDiskSpace(string $data): bool
+    {
+        if (function_exists('disk_free_space') === false) {
+            return true;
+        }
+
+        return disk_free_space(dirname($this->datastore)) > (strlen($data) + 1024 * 500);
+    }
+}

application/bookmark/BookmarkInitializer.php

@@ -0,0 +1,115 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Bookmark;
+
+/**
+ * Class BookmarkInitializer
+ *
+ * This class is used to initialized default bookmarks after a fresh install of Shaarli.
+ * It should be only called if the datastore file does not exist(users might want to delete the default bookmarks).
+ *
+ * To prevent data corruption, it does not overwrite existing bookmarks,
+ * even though there should not be any.
+ *
+ * We disable this because otherwise it creates indentation issues, and heredoc is not supported by PHP gettext.
+ * @phpcs:disable Generic.Files.LineLength.TooLong
+ *
+ * @package Shaarli\Bookmark
+ */
+class BookmarkInitializer
+{
+    /** @var BookmarkServiceInterface */
+    protected $bookmarkService;
+
+    /**
+     * BookmarkInitializer constructor.
+     *
+     * @param BookmarkServiceInterface $bookmarkService
+     */
+    public function __construct(BookmarkServiceInterface $bookmarkService)
+    {
+        $this->bookmarkService = $bookmarkService;
+    }
+
+    /**
+     * Initialize the data store with default bookmarks
+     */
+    public function initialize(): void
+    {
+        $bookmark = new Bookmark();
+        $bookmark->setTitle('Calm Jazz Music - YouTube ' . t('(private bookmark with thumbnail demo)'));
+        $bookmark->setUrl('https://www.youtube.com/watch?v=DVEUcbPkb-c');
+        $bookmark->setDescription(t(
+            'Shaarli will automatically pick up the thumbnail for links to a variety of websites.
+
+Explore your new Shaarli instance by trying out controls and menus.
+Visit the project on [Github](https://github.com/shaarli/Shaarli) or [the documentation](https://shaarli.readthedocs.io/en/master/) to learn more about Shaarli.
+
+Now you can edit or delete the default shaares.
+'
+        ));
+        $bookmark->setTagsString('shaarli help thumbnail');
+        $bookmark->setPrivate(true);
+        $this->bookmarkService->add($bookmark, false);
+
+        $bookmark = new Bookmark();
+        $bookmark->setTitle(t('Note: Shaare descriptions'));
+        $bookmark->setDescription(t(
+            'Adding a shaare without entering a URL creates a text-only "note" post such as this one.
+This note is private, so you are the only one able to see it while logged in.
+
+You can use this to keep notes, post articles, code snippets, and much more.
+
+The Markdown formatting setting allows you to format your notes and bookmark description:
+
+### Title headings
+
+#### Multiple headings levels
+  * bullet lists
+  * _italic_ text
+  * **bold** text
+  * ~~strike through~~ text
+  * `code` blocks
+  * images
+  * [links](https://en.wikipedia.org/wiki/Markdown)
+
+Markdown also supports tables:
+
+| Name    | Type      | Color  | Qty   |
+| ------- | --------- | ------ | ----- |
+| Orange  | Fruit     | Orange | 126   |
+| Apple   | Fruit     | Any    | 62    |
+| Lemon   | Fruit     | Yellow | 30    |
+| Carrot  | Vegetable | Red    | 14    |
+'
+        ));
+        $bookmark->setTagsString('shaarli help');
+        $bookmark->setPrivate(true);
+        $this->bookmarkService->add($bookmark, false);
+
+        $bookmark = new Bookmark();
+        $bookmark->setTitle(
+            'Shaarli - ' . t('The personal, minimalist, super fast, database-free, bookmarking service')
+        );
+        $bookmark->setDescription(t(
+            'Welcome to Shaarli!
+
+Shaarli allows you to bookmark your favorite pages, and share them with others or store them privately.
+You can add a description to your bookmarks, such as this one, and tag them.
+
+Create a new shaare by clicking the `+Shaare` button, or using any of the recommended tools (browser extension, mobile app, bookmarklet, REST API, etc.).
+
+You can easily retrieve your links, even with thousands of them, using the internal search engine, or search through tags (e.g. this Shaare is tagged with `shaarli` and `help`).
+Hashtags such as #shaarli #help are also supported.
+You can also filter the available [RSS feed](/feed/atom) and picture wall by tag or plaintext search.
+
+We hope that you will enjoy using Shaarli, maintained with ❤️ by the community!
+Feel free to open [an issue](https://github.com/shaarli/Shaarli/issues) if you have a suggestion or encounter an issue.
+'
+        ));
+        $bookmark->setTagsString('shaarli help');
+        $this->bookmarkService->add($bookmark, false);
+    }
+}

application/bookmark/BookmarkServiceInterface.php

@@ -0,0 +1,189 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Bookmark;
+
+use Shaarli\Bookmark\Exception\BookmarkNotFoundException;
+use Shaarli\Bookmark\Exception\NotWritableDataStoreException;
+
+/**
+ * Class BookmarksService
+ *
+ * This is the entry point to manipulate the bookmark DB.
+ *
+ * Regarding return types of a list of bookmarks, it can either be an array or an ArrayAccess implementation,
+ * so until PHP 8.0 is the minimal supported version with union return types it cannot be explicitly added.
+ */
+interface BookmarkServiceInterface
+{
+    /**
+     * Find a bookmark by hash
+     *
+     * @param string      $hash       Bookmark's hash
+     * @param string|null $privateKey Optional key used to access private links while logged out
+     *
+     * @return Bookmark
+     *
+     * @throws \Exception
+     */
+    public function findByHash(string $hash, string $privateKey = null);
+
+    /**
+     * @param $url
+     *
+     * @return Bookmark|null
+     */
+    public function findByUrl(string $url): ?Bookmark;
+
+    /**
+     * Search bookmarks
+     *
+     * @param array   $request
+     * @param ?string $visibility
+     * @param bool    $caseSensitive
+     * @param bool    $untaggedOnly
+     * @param bool    $ignoreSticky
+     * @param array   $pagination     This array can contain the following keys for pagination: limit, offset.
+     *
+     * @return SearchResult
+     */
+    public function search(
+        array $request = [],
+        string $visibility = null,
+        bool $caseSensitive = false,
+        bool $untaggedOnly = false,
+        bool $ignoreSticky = false,
+        array $pagination = []
+    ): SearchResult;
+
+    /**
+     * Get a single bookmark by its ID.
+     *
+     * @param int    $id          Bookmark ID
+     * @param ?string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an
+     *                            exception
+     *
+     * @return Bookmark
+     *
+     * @throws BookmarkNotFoundException
+     * @throws \Exception
+     */
+    public function get(int $id, string $visibility = null);
+
+    /**
+     * Updates an existing bookmark (depending on its ID).
+     *
+     * @param Bookmark $bookmark
+     * @param bool     $save Writes to the datastore if set to true
+     *
+     * @return Bookmark Updated bookmark
+     *
+     * @throws BookmarkNotFoundException
+     * @throws \Exception
+     */
+    public function set(Bookmark $bookmark, bool $save = true): Bookmark;
+
+    /**
+     * Adds a new bookmark (the ID must be empty).
+     *
+     * @param Bookmark $bookmark
+     * @param bool     $save Writes to the datastore if set to true
+     *
+     * @return Bookmark new bookmark
+     *
+     * @throws \Exception
+     */
+    public function add(Bookmark $bookmark, bool $save = true): Bookmark;
+
+    /**
+     * Adds or updates a bookmark depending on its ID:
+     *   - a Bookmark without ID will be added
+     *   - a Bookmark with an existing ID will be updated
+     *
+     * @param Bookmark $bookmark
+     * @param bool     $save
+     *
+     * @return Bookmark
+     *
+     * @throws \Exception
+     */
+    public function addOrSet(Bookmark $bookmark, bool $save = true): Bookmark;
+
+    /**
+     * Deletes a bookmark.
+     *
+     * @param Bookmark $bookmark
+     * @param bool     $save
+     *
+     * @throws \Exception
+     */
+    public function remove(Bookmark $bookmark, bool $save = true): void;
+
+    /**
+     * Get a single bookmark by its ID.
+     *
+     * @param int     $id         Bookmark ID
+     * @param ?string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an
+     *                            exception
+     *
+     * @return bool
+     */
+    public function exists(int $id, string $visibility = null): bool;
+
+    /**
+     * Return the number of available bookmarks for given visibility.
+     *
+     * @param ?string $visibility public|private|all
+     *
+     * @return int Number of bookmarks
+     */
+    public function count(string $visibility = null): int;
+
+    /**
+     * Write the datastore.
+     *
+     * @throws NotWritableDataStoreException
+     */
+    public function save(): void;
+
+    /**
+     * Returns the list tags appearing in the bookmarks with the given tags
+     *
+     * @param array|null  $filteringTags tags selecting the bookmarks to consider
+     * @param string|null $visibility    process only all/private/public bookmarks
+     *
+     * @return array tag => bookmarksCount
+     */
+    public function bookmarksCountPerTag(array $filteringTags = [], ?string $visibility = null): array;
+
+    /**
+     * Return a list of bookmark matching provided period of time.
+     * It also update directly previous and next date outside of given period found in the datastore.
+     *
+     * @param \DateTimeInterface      $from     Starting date.
+     * @param \DateTimeInterface      $to       Ending date.
+     * @param \DateTimeInterface|null $previous (by reference) updated with first created date found before $from.
+     * @param \DateTimeInterface|null $next     (by reference) updated with first created date found after $to.
+     *
+     * @return array List of bookmarks matching provided period of time.
+     */
+    public function findByDate(
+        \DateTimeInterface $from,
+        \DateTimeInterface $to,
+        ?\DateTimeInterface &$previous,
+        ?\DateTimeInterface &$next
+    ): array;
+
+    /**
+     * Returns the latest bookmark by creation date.
+     *
+     * @return Bookmark|null Found Bookmark or null if the datastore is empty.
+     */
+    public function getLatest(): ?Bookmark;
+
+    /**
+     * Creates the default database after a fresh install.
+     */
+    public function initialize(): void;
+}

application/bookmark/LinkUtils.php

@@ -0,0 +1,253 @@
+<?php
+
+use Shaarli\Bookmark\Bookmark;
+use Shaarli\Formatter\BookmarkDefaultFormatter;
+
+/**
+ * Extract title from an HTML document.
+ *
+ * @param string $html HTML content where to look for a title.
+ *
+ * @return bool|string Extracted title if found, false otherwise.
+ */
+function html_extract_title($html)
+{
+    if (preg_match('!<title.*?>(.*?)</title>!is', $html, $matches)) {
+        return trim(str_replace("\n", '', $matches[1]));
+    }
+    return false;
+}
+
+/**
+ * Extract charset from HTTP header if it's defined.
+ *
+ * @param string $header HTTP header Content-Type line.
+ *
+ * @return bool|string Charset string if found (lowercase), false otherwise.
+ */
+function header_extract_charset($header)
+{
+    preg_match('/charset=["\']?([^; "\']+)/i', $header, $match);
+    if (! empty($match[1])) {
+        return strtolower(trim($match[1]));
+    }
+
+    return false;
+}
+
+/**
+ * Extract charset HTML content (tag <meta charset>).
+ *
+ * @param string $html HTML content where to look for charset.
+ *
+ * @return bool|string Charset string if found, false otherwise.
+ */
+function html_extract_charset($html)
+{
+    // Get encoding specified in HTML header.
+    preg_match('#<meta .*charset=["\']?([^";\'>/]+)["\']? */?>#Usi', $html, $enc);
+    if (!empty($enc[1])) {
+        return strtolower($enc[1]);
+    }
+
+    return false;
+}
+
+/**
+ * Extract meta tag from HTML content in either:
+ *   - OpenGraph: <meta property="og:[tag]" ...>
+ *   - Meta tag: <meta name="[tag]" ...>
+ *
+ * @param string $tag  Name of the tag to retrieve.
+ * @param string $html HTML content where to look for charset.
+ *
+ * @return bool|string Charset string if found, false otherwise.
+ */
+function html_extract_tag($tag, $html)
+{
+    $propertiesKey = ['property', 'name', 'itemprop'];
+    $properties = implode('|', $propertiesKey);
+    // We need a OR here to accept either 'property=og:noquote' or 'property="og:unrelated og:my-tag"'
+    $orCondition  = '["\']?(?:og:)?' . $tag . '["\']?|["\'][^\'"]*?(?:og:)?' . $tag . '[^\'"]*?[\'"]';
+    // Support quotes in double quoted content, and the other way around
+    $content = 'content=(["\'])((?:(?!\1).)*)\1';
+    // Try to retrieve OpenGraph tag.
+    $ogRegex = '#<meta[^>]+(?:' . $properties . ')=(?:' . $orCondition . ')[^>]*' . $content . '.*?>#';
+    // If the attributes are not in the order property => content (e.g. Github)
+    // New regex to keep this readable... more or less.
+    $ogRegexReverse = '#<meta[^>]+' . $content . '[^>]+(?:' . $properties . ')=(?:' . $orCondition . ').*?>#';
+
+    if (
+        preg_match($ogRegex, $html, $matches) > 0
+        || preg_match($ogRegexReverse, $html, $matches) > 0
+    ) {
+        return $matches[2];
+    }
+
+    return false;
+}
+
+/**
+ * In a string, converts URLs to clickable bookmarks.
+ *
+ * @param string $text       input string.
+ *
+ * @return string returns $text with all bookmarks converted to HTML bookmarks.
+ *
+ * @see Function inspired from http://www.php.net/manual/en/function.preg-replace.php#85722
+ */
+function text2clickable($text)
+{
+    $regex = '!(((?:https?|ftp|file)://|apt:|magnet:)\S+[a-z0-9\(\)]/?)!si';
+    $format = function (array $match): string {
+        return '<a href="' .
+            str_replace(
+                BookmarkDefaultFormatter::SEARCH_HIGHLIGHT_OPEN,
+                '',
+                str_replace(BookmarkDefaultFormatter::SEARCH_HIGHLIGHT_CLOSE, '', $match[1])
+            ) .
+            '">' . $match[1] . '</a>'
+        ;
+    };
+
+    return preg_replace_callback($regex, $format, $text);
+}
+
+/**
+ * Auto-link hashtags.
+ *
+ * @param string $description Given description.
+ * @param string $indexUrl    Root URL.
+ *
+ * @return string Description with auto-linked hashtags.
+ */
+function hashtag_autolink($description, $indexUrl = '')
+{
+    $tokens = '(?:' . BookmarkDefaultFormatter::SEARCH_HIGHLIGHT_OPEN . ')' .
+              '(?:' . BookmarkDefaultFormatter::SEARCH_HIGHLIGHT_CLOSE . ')'
+    ;
+    /*
+     * To support unicode: http://stackoverflow.com/a/35498078/1484919
+     * \p{Pc} - to match underscore
+     * \p{N} - numeric character in any script
+     * \p{L} - letter from any language
+     * \p{Mn} - any non marking space (accents, umlauts, etc)
+     */
+    $regex = '/(^|\s)#([\p{Pc}\p{N}\p{L}\p{Mn}' . $tokens . ']+)/mui';
+    $format = function (array $match) use ($indexUrl): string {
+        $cleanMatch = str_replace(
+            BookmarkDefaultFormatter::SEARCH_HIGHLIGHT_OPEN,
+            '',
+            str_replace(BookmarkDefaultFormatter::SEARCH_HIGHLIGHT_CLOSE, '', $match[2])
+        );
+        return $match[1] . '<a href="' . $indexUrl . './add-tag/' . $cleanMatch . '"' .
+            ' title="Hashtag ' . $cleanMatch . '">' .
+                '#' . $match[2] .
+        '</a>';
+    };
+
+    return preg_replace_callback($regex, $format, $description);
+}
+
+/**
+ * This function inserts &nbsp; where relevant so that multiple spaces are properly displayed in HTML
+ * even in the absence of <pre>  (This is used in description to keep text formatting).
+ *
+ * @param string $text input text.
+ *
+ * @return string formatted text.
+ */
+function space2nbsp($text)
+{
+    return preg_replace('/(^| ) /m', '$1&nbsp;', $text);
+}
+
+/**
+ * Format Shaarli's description
+ *
+ * @param string $description shaare's description.
+ * @param string $indexUrl    URL to Shaarli's index.
+ * @param bool   $autolink    Turn on/off automatic linkifications of URLs and hashtags
+ *
+ * @return string formatted description.
+ */
+function format_description($description, $indexUrl = '', $autolink = true)
+{
+    if ($autolink) {
+        $description = hashtag_autolink(text2clickable($description), $indexUrl);
+    }
+
+    return nl2br(space2nbsp($description));
+}
+
+/**
+ * Generate a small hash for a link.
+ *
+ * @param DateTime $date Link creation date.
+ * @param int      $id   Link ID.
+ *
+ * @return string the small hash generated from link data.
+ */
+function link_small_hash($date, $id)
+{
+    return smallHash($date->format(Bookmark::LINK_DATE_FORMAT) . $id);
+}
+
+/**
+ * Returns whether or not the link is an internal note.
+ * Its URL starts by `?` because it's actually a permalink.
+ *
+ * @param string $linkUrl
+ *
+ * @return bool true if internal note, false otherwise.
+ */
+function is_note($linkUrl)
+{
+    return isset($linkUrl[0]) && $linkUrl[0] === '?';
+}
+
+/**
+ * Extract an array of tags from a given tag string, with provided separator.
+ *
+ * @param string|null $tags      String containing a list of tags separated by $separator.
+ * @param string      $separator Shaarli's default: ' ' (whitespace)
+ *
+ * @return array List of tags
+ */
+function tags_str2array(?string $tags, string $separator): array
+{
+    // For whitespaces, we use the special \s regex character
+    $separator = str_replace([' ', '/'], ['\s', '\/'], $separator);
+
+    return preg_split('/\s*' . $separator . '+\s*/', trim($tags ?? ''), -1, PREG_SPLIT_NO_EMPTY) ?: [];
+}
+
+/**
+ * Return a tag string with provided separator from a list of tags.
+ * Note that given array is clean up by tags_filter().
+ *
+ * @param array|null $tags      List of tags
+ * @param string     $separator
+ *
+ * @return string
+ */
+function tags_array2str(?array $tags, string $separator): string
+{
+    return implode($separator, tags_filter($tags, $separator));
+}
+
+/**
+ * Clean an array of tags: trim + remove empty entries
+ *
+ * @param array|null $tags List of tags
+ * @param string     $separator
+ *
+ * @return array
+ */
+function tags_filter(?array $tags, string $separator): array
+{
+    $trimDefault = " \t\n\r\0\x0B";
+    return array_values(array_filter(array_map(function (string $entry) use ($separator, $trimDefault): string {
+        return trim($entry, $trimDefault . $separator);
+    }, $tags ?? [])));
+}

application/bookmark/SearchResult.php

@@ -0,0 +1,136 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Bookmark;
+
+/**
+ * Read-only class used to represent search result, including pagination.
+ */
+class SearchResult
+{
+    /** @var Bookmark[] List of result bookmarks with pagination applied */
+    protected $bookmarks;
+
+    /** @var int number of Bookmarks found, with pagination applied */
+    protected $resultCount;
+
+    /** @var int total number of result found */
+    protected $totalCount;
+
+    /** @var int pagination: limit number of result bookmarks */
+    protected $limit;
+
+    /** @var int pagination: offset to apply to complete result list */
+    protected $offset;
+
+    public function __construct(array $bookmarks, int $totalCount, int $offset, ?int $limit)
+    {
+        $this->bookmarks = $bookmarks;
+        $this->resultCount = count($bookmarks);
+        $this->totalCount = $totalCount;
+        $this->limit = $limit;
+        $this->offset = $offset;
+    }
+
+    /**
+     * Build a SearchResult from provided full result set and pagination settings.
+     *
+     * @param Bookmark[] $bookmarks        Full set of result which will be filtered
+     * @param int        $offset           Start recording results from $offset
+     * @param int|null   $limit            End recording results after $limit bookmarks is reached
+     * @param bool       $allowOutOfBounds Set to false to display the last page if the offset is out of bound,
+     *                                     return empty result set otherwise (default: false)
+     *
+     * @return SearchResult
+     */
+    public static function getSearchResult(
+        $bookmarks,
+        int $offset = 0,
+        ?int $limit = null,
+        bool $allowOutOfBounds = false
+    ): self {
+        $totalCount = count($bookmarks);
+        if (!$allowOutOfBounds && $offset > $totalCount) {
+            $offset = $limit === null ? 0 : $limit * -1;
+        }
+
+        if ($bookmarks instanceof BookmarkArray) {
+            $buffer = [];
+            foreach ($bookmarks as $key => $value) {
+                $buffer[$key] = $value;
+            }
+            $bookmarks = $buffer;
+        }
+
+        return new static(
+            array_slice($bookmarks, $offset, $limit, true),
+            $totalCount,
+            $offset,
+            $limit
+        );
+    }
+
+    /** @return Bookmark[] List of result bookmarks with pagination applied */
+    public function getBookmarks(): array
+    {
+        return $this->bookmarks;
+    }
+
+    /** @return int number of Bookmarks found, with pagination applied */
+    public function getResultCount(): int
+    {
+        return $this->resultCount;
+    }
+
+    /** @return int total number of result found */
+    public function getTotalCount(): int
+    {
+        return $this->totalCount;
+    }
+
+    /** @return int pagination: limit number of result bookmarks */
+    public function getLimit(): ?int
+    {
+        return $this->limit;
+    }
+
+    /** @return int pagination: offset to apply to complete result list */
+    public function getOffset(): int
+    {
+        return $this->offset;
+    }
+
+    /** @return int Current page of result set in complete results */
+    public function getPage(): int
+    {
+        if (empty($this->limit)) {
+            return $this->offset === 0 ? 1 : 2;
+        }
+        $base = $this->offset >= 0 ? $this->offset : $this->totalCount + $this->offset;
+
+        return (int) ceil($base / $this->limit) + 1;
+    }
+
+    /** @return int Get the # of the last page */
+    public function getLastPage(): int
+    {
+        if (empty($this->limit)) {
+            return $this->offset === 0 ? 1 : 2;
+        }
+
+        return (int) ceil($this->totalCount / $this->limit);
+    }
+
+    /** @return bool Either the current page is the last one or not */
+    public function isLastPage(): bool
+    {
+        return $this->getPage() === $this->getLastPage();
+    }
+
+    /** @return bool Either the current page is the first one or not */
+    public function isFirstPage(): bool
+    {
+        return $this->offset === 0;
+    }
+}

application/bookmark/exception/BookmarkNotFoundException.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Shaarli\Bookmark\Exception;
+
+use Exception;
+
+class BookmarkNotFoundException extends Exception
+{
+    /**
+     * LinkNotFoundException constructor.
+     */
+    public function __construct()
+    {
+        $this->message = t('The link you are trying to reach does not exist or has been deleted.');
+    }
+}

application/bookmark/exception/DatastoreNotInitializedException.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Bookmark\Exception;
+
+class DatastoreNotInitializedException extends \Exception
+{
+}

application/bookmark/exception/EmptyDataStoreException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace Shaarli\Bookmark\Exception;
+
+class EmptyDataStoreException extends \Exception
+{
+}

application/bookmark/exception/InvalidBookmarkException.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Shaarli\Bookmark\Exception;
+
+use Shaarli\Bookmark\Bookmark;
+
+class InvalidBookmarkException extends \Exception
+{
+    public function __construct($bookmark)
+    {
+        if ($bookmark instanceof Bookmark) {
+            if ($bookmark->getCreated() instanceof \DateTime) {
+                $created = $bookmark->getCreated()->format(\DateTime::ATOM);
+            } elseif (empty($bookmark->getCreated())) {
+                $created = '';
+            } else {
+                $created = 'Not a DateTime object';
+            }
+            $this->message = 'This bookmark is not valid' . PHP_EOL;
+            $this->message .= ' - ID: ' . $bookmark->getId() . PHP_EOL;
+            $this->message .= ' - Title: ' . $bookmark->getTitle() . PHP_EOL;
+            $this->message .= ' - Url: ' . $bookmark->getUrl() . PHP_EOL;
+            $this->message .= ' - ShortUrl: ' . $bookmark->getShortUrl() . PHP_EOL;
+            $this->message .= ' - Created: ' . $created . PHP_EOL;
+        } else {
+            $this->message = 'The provided data is not a bookmark' . PHP_EOL;
+            $this->message .= var_export($bookmark, true);
+        }
+    }
+}

application/bookmark/exception/InvalidWritableDataException.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Shaarli\Bookmark\Exception;
+
+class InvalidWritableDataException extends \Exception
+{
+    /**
+     * InvalidWritableDataException constructor.
+     */
+    public function __construct()
+    {
+        $this->message = 'Couldn\'t generate bookmark data to store in the datastore. Skipping file writing.';
+    }
+}

application/bookmark/exception/NotEnoughSpaceException.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Shaarli\Bookmark\Exception;
+
+class NotEnoughSpaceException extends \Exception
+{
+    /**
+     * NotEnoughSpaceException constructor.
+     */
+    public function __construct()
+    {
+        $this->message = 'Not enough available disk space to save the datastore.';
+    }
+}

application/bookmark/exception/NotWritableDataStoreException.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Shaarli\Bookmark\Exception;
+
+class NotWritableDataStoreException extends \Exception
+{
+    /**
+     * NotReadableDataStore constructor.
+     *
+     * @param string $dataStore file path
+     */
+    public function __construct($dataStore)
+    {
+        $this->message = 'Couldn\'t load data from the data store file "' . $dataStore . '". ' .
+            'Your data might be corrupted, or your file isn\'t readable.';
+    }
+}

application/config/ConfigIO.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace Shaarli\Config;
+
+/**
+ * Interface ConfigIO
+ *
+ * This describes how Config types should store their configuration.
+ */
+interface ConfigIO
+{
+    /**
+     * Read configuration.
+     *
+     * @param string $filepath Config file absolute path.
+     *
+     * @return array All configuration in an array.
+     */
+    public function read($filepath);
+
+    /**
+     * Write configuration.
+     *
+     * @param string $filepath Config file absolute path.
+     * @param array  $conf   All configuration in an array.
+     */
+    public function write($filepath, $conf);
+
+    /**
+     * Get config file extension according to config type.
+     *
+     * @return string Config file extension.
+     */
+    public function getExtension();
+}

application/config/ConfigJson.php

@@ -0,0 +1,90 @@
+<?php
+namespace Shaarli\Config;
+
+/**
+ * Class ConfigJson (ConfigIO implementation)
+ *
+ * Handle Shaarli's JSON configuration file.
+ */
+class ConfigJson implements ConfigIO
+{
+    /**
+     * @inheritdoc
+     */
+    public function read($filepath)
+    {
+        if (! is_readable($filepath)) {
+            return array();
+        }
+        $data = file_get_contents($filepath);
+        $data = str_replace(self::getPhpHeaders(), '', $data);
+        $data = str_replace(self::getPhpSuffix(), '', $data);
+        $data = json_decode(trim($data), true);
+        if ($data === null) {
+            $errorCode = json_last_error();
+            $error  = sprintf(
+                'An error occurred while parsing JSON configuration file (%s): error code #%d',
+                $filepath,
+                $errorCode
+            );
+            $error .= '<br>➜ <code>' . json_last_error_msg() .'</code>';
+            if ($errorCode === JSON_ERROR_SYNTAX) {
+                $error .= '<br>';
+                $error .= 'Please check your JSON syntax (without PHP comment tags) using a JSON lint tool such as ';
+                $error .= '<a href="http://jsonlint.com/">jsonlint.com</a>.';
+            }
+            throw new \Exception($error);
+        }
+        return $data;
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function write($filepath, $conf)
+    {
+        // JSON_PRETTY_PRINT is available from PHP 5.4.
+        $print = defined('JSON_PRETTY_PRINT') ? JSON_PRETTY_PRINT : 0;
+        $data = self::getPhpHeaders() . json_encode($conf, $print) . self::getPhpSuffix();
+        if (empty($filepath) || !file_put_contents($filepath, $data)) {
+            throw new \Shaarli\Exceptions\IOException(
+                $filepath,
+                t('Shaarli could not create the config file. '.
+                  'Please make sure Shaarli has the right to write in the folder is it installed in.')
+            );
+        }
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function getExtension()
+    {
+        return '.json.php';
+    }
+
+    /**
+     * The JSON data is wrapped in a PHP file for security purpose.
+     * This way, even if the file is accessible, credentials and configuration won't be exposed.
+     *
+     * Note: this isn't a static field because concatenation isn't supported in field declaration before PHP 5.6.
+     *
+     * @return string PHP start tag and comment tag.
+     */
+    public static function getPhpHeaders()
+    {
+        return '<?php /*';
+    }
+
+    /**
+     * Get PHP comment closing tags.
+     *
+     * Static method for consistency with getPhpHeaders.
+     *
+     * @return string PHP comment closing.
+     */
+    public static function getPhpSuffix()
+    {
+        return '*/ ?>';
+    }
+}

application/config/ConfigManager.php

@@ -0,0 +1,429 @@
+<?php
+
+namespace Shaarli\Config;
+
+use Shaarli\Config\Exception\MissingFieldConfigException;
+use Shaarli\Config\Exception\UnauthorizedConfigException;
+use Shaarli\Thumbnailer;
+
+/**
+ * Class ConfigManager
+ *
+ * Manages all Shaarli's settings.
+ * See the documentation for more information on settings:
+ *   - doc/md/Shaarli-configuration.md
+ *   - https://shaarli.readthedocs.io/en/master/Shaarli-configuration/#configuration
+ */
+class ConfigManager
+{
+    /**
+     * @var string Flag telling a setting is not found.
+     */
+    protected static $NOT_FOUND = 'NOT_FOUND';
+
+    public static $DEFAULT_PLUGINS = ['qrcode'];
+
+    /**
+     * @var string Config folder.
+     */
+    protected $configFile;
+
+    /**
+     * @var array Loaded config array.
+     */
+    protected $loadedConfig;
+
+    /**
+     * @var ConfigIO implementation instance.
+     */
+    protected $configIO;
+
+    /**
+     * Constructor.
+     *
+     * @param string $configFile Configuration file path without extension.
+     */
+    public function __construct($configFile = 'data/config')
+    {
+        $this->configFile = $configFile;
+        $this->initialize();
+    }
+
+    /**
+     * Reset the ConfigManager instance.
+     */
+    public function reset()
+    {
+        $this->initialize();
+    }
+
+    /**
+     * Rebuild the loaded config array from config files.
+     */
+    public function reload()
+    {
+        $this->load();
+    }
+
+    /**
+     * Initialize the ConfigIO and loaded the conf.
+     */
+    protected function initialize()
+    {
+        if (file_exists($this->configFile . '.php')) {
+            $this->configIO = new ConfigPhp();
+        } else {
+            $this->configIO = new ConfigJson();
+        }
+        $this->load();
+    }
+
+    /**
+     * Load configuration in the ConfigurationManager.
+     */
+    protected function load()
+    {
+        try {
+            $this->loadedConfig = $this->configIO->read($this->getConfigFileExt());
+        } catch (\Exception $e) {
+            die($e->getMessage());
+        }
+        $this->setDefaultValues();
+    }
+
+    /**
+     * Get a setting.
+     *
+     * Supports nested settings with dot separated keys.
+     * Eg. 'config.stuff.option' will find $conf[config][stuff][option],
+     * or in JSON:
+     *   { "config": { "stuff": {"option": "mysetting" } } } }
+     *
+     * @param string $setting Asked setting, keys separated with dots.
+     * @param string $default Default value if not found.
+     *
+     * @return mixed Found setting, or the default value.
+     */
+    public function get($setting, $default = '')
+    {
+        // During the ConfigIO transition, map legacy settings to the new ones.
+        if ($this->configIO instanceof ConfigPhp && isset(ConfigPhp::$LEGACY_KEYS_MAPPING[$setting])) {
+            $setting = ConfigPhp::$LEGACY_KEYS_MAPPING[$setting];
+        }
+
+        $settings = explode('.', $setting);
+        $value = self::getConfig($settings, $this->loadedConfig);
+        if ($value === self::$NOT_FOUND) {
+            return $default;
+        }
+        return $value;
+    }
+
+    /**
+     * Set a setting, and eventually write it.
+     *
+     * Supports nested settings with dot separated keys.
+     *
+     * @param string $setting    Asked setting, keys separated with dots.
+     * @param mixed  $value      Value to set.
+     * @param bool   $write      Write the new setting in the config file, default false.
+     * @param bool   $isLoggedIn User login state, default false.
+     *
+     * @throws \Exception Invalid
+     */
+    public function set($setting, $value, $write = false, $isLoggedIn = false)
+    {
+        if (empty($setting) || ! is_string($setting)) {
+            throw new \Exception(t('Invalid setting key parameter. String expected, got: ') . gettype($setting));
+        }
+
+        // During the ConfigIO transition, map legacy settings to the new ones.
+        if ($this->configIO instanceof ConfigPhp && isset(ConfigPhp::$LEGACY_KEYS_MAPPING[$setting])) {
+            $setting = ConfigPhp::$LEGACY_KEYS_MAPPING[$setting];
+        }
+
+        $settings = explode('.', $setting);
+        self::setConfig($settings, $value, $this->loadedConfig);
+        if ($write) {
+            $this->write($isLoggedIn);
+        }
+    }
+
+    /**
+     * Remove a config element from the config file.
+     *
+     * @param string $setting    Asked setting, keys separated with dots.
+     * @param bool   $write      Write the new setting in the config file, default false.
+     * @param bool   $isLoggedIn User login state, default false.
+     *
+     * @throws \Exception Invalid
+     */
+    public function remove($setting, $write = false, $isLoggedIn = false)
+    {
+        if (empty($setting) || ! is_string($setting)) {
+            throw new \Exception(t('Invalid setting key parameter. String expected, got: ') . gettype($setting));
+        }
+
+        // During the ConfigIO transition, map legacy settings to the new ones.
+        if ($this->configIO instanceof ConfigPhp && isset(ConfigPhp::$LEGACY_KEYS_MAPPING[$setting])) {
+            $setting = ConfigPhp::$LEGACY_KEYS_MAPPING[$setting];
+        }
+
+        $settings = explode('.', $setting);
+        self::removeConfig($settings, $this->loadedConfig);
+        if ($write) {
+            $this->write($isLoggedIn);
+        }
+    }
+
+    /**
+     * Check if a settings exists.
+     *
+     * Supports nested settings with dot separated keys.
+     *
+     * @param string $setting    Asked setting, keys separated with dots.
+     *
+     * @return bool true if the setting exists, false otherwise.
+     */
+    public function exists($setting)
+    {
+        // During the ConfigIO transition, map legacy settings to the new ones.
+        if ($this->configIO instanceof ConfigPhp && isset(ConfigPhp::$LEGACY_KEYS_MAPPING[$setting])) {
+            $setting = ConfigPhp::$LEGACY_KEYS_MAPPING[$setting];
+        }
+
+        $settings = explode('.', $setting);
+        $value = self::getConfig($settings, $this->loadedConfig);
+        if ($value === self::$NOT_FOUND) {
+            return false;
+        }
+        return true;
+    }
+
+    /**
+     * Call the config writer.
+     *
+     * @param bool $isLoggedIn User login state.
+     *
+     * @return bool True if the configuration has been successfully written, false otherwise.
+     *
+     * @throws MissingFieldConfigException: a mandatory field has not been provided in $conf.
+     * @throws UnauthorizedConfigException: user is not authorize to change configuration.
+     * @throws \Shaarli\Exceptions\IOException: an error occurred while writing the new config file.
+     */
+    public function write($isLoggedIn)
+    {
+        // These fields are required in configuration.
+        $mandatoryFields = [
+            'credentials.login',
+            'credentials.hash',
+            'credentials.salt',
+            'security.session_protection_disabled',
+            'general.timezone',
+            'general.title',
+            'general.header_link',
+            'privacy.default_private_links',
+        ];
+
+        // Only logged in user can alter config.
+        if (is_file($this->getConfigFileExt()) && !$isLoggedIn) {
+            throw new UnauthorizedConfigException();
+        }
+
+        // Check that all mandatory fields are provided in $conf.
+        foreach ($mandatoryFields as $field) {
+            if (! $this->exists($field)) {
+                throw new MissingFieldConfigException($field);
+            }
+        }
+
+        return $this->configIO->write($this->getConfigFileExt(), $this->loadedConfig);
+    }
+
+    /**
+     * Set the config file path (without extension).
+     *
+     * @param string $configFile File path.
+     */
+    public function setConfigFile($configFile)
+    {
+        $this->configFile = $configFile;
+    }
+
+    /**
+     * Return the configuration file path (without extension).
+     *
+     * @return string Config path.
+     */
+    public function getConfigFile()
+    {
+        return $this->configFile;
+    }
+
+    /**
+     * Get the configuration file path with its extension.
+     *
+     * @return string Config file path.
+     */
+    public function getConfigFileExt()
+    {
+        return $this->configFile . $this->configIO->getExtension();
+    }
+
+    /**
+     * Recursive function which find asked setting in the loaded config.
+     *
+     * @param array $settings Ordered array which contains keys to find.
+     * @param array $conf   Loaded settings, then sub-array.
+     *
+     * @return mixed Found setting or NOT_FOUND flag.
+     */
+    protected static function getConfig($settings, $conf)
+    {
+        if (!is_array($settings) || count($settings) == 0) {
+            return self::$NOT_FOUND;
+        }
+
+        $setting = array_shift($settings);
+        if (!isset($conf[$setting])) {
+            return self::$NOT_FOUND;
+        }
+
+        if (count($settings) > 0) {
+            return self::getConfig($settings, $conf[$setting]);
+        }
+        return $conf[$setting];
+    }
+
+    /**
+     * Recursive function which find asked setting in the loaded config.
+     *
+     * @param array $settings Ordered array which contains keys to find.
+     * @param mixed $value
+     * @param array $conf     Loaded settings, then sub-array.
+     *
+     * @return mixed Found setting or NOT_FOUND flag.
+     */
+    protected static function setConfig($settings, $value, &$conf)
+    {
+        if (!is_array($settings) || count($settings) == 0) {
+            return self::$NOT_FOUND;
+        }
+
+        $setting = array_shift($settings);
+        if (count($settings) > 0) {
+            return self::setConfig($settings, $value, $conf[$setting]);
+        }
+        $conf[$setting] = $value;
+    }
+
+    /**
+     * Recursive function which find asked setting in the loaded config and deletes it.
+     *
+     * @param array $settings Ordered array which contains keys to find.
+     * @param array $conf     Loaded settings, then sub-array.
+     *
+     * @return mixed Found setting or NOT_FOUND flag.
+     */
+    protected static function removeConfig($settings, &$conf)
+    {
+        if (!is_array($settings) || count($settings) == 0) {
+            return self::$NOT_FOUND;
+        }
+
+        $setting = array_shift($settings);
+        if (count($settings) > 0) {
+            return self::removeConfig($settings, $conf[$setting]);
+        }
+        unset($conf[$setting]);
+    }
+
+    /**
+     * Set a bunch of default values allowing Shaarli to start without a config file.
+     */
+    protected function setDefaultValues()
+    {
+        $this->setEmpty('resource.data_dir', 'data');
+        $this->setEmpty('resource.config', 'data/config.php');
+        $this->setEmpty('resource.datastore', 'data/datastore.php');
+        $this->setEmpty('resource.ban_file', 'data/ipbans.php');
+        $this->setEmpty('resource.updates', 'data/updates.txt');
+        $this->setEmpty('resource.log', 'data/log.txt');
+        $this->setEmpty('resource.update_check', 'data/lastupdatecheck.txt');
+        $this->setEmpty('resource.history', 'data/history.php');
+        $this->setEmpty('resource.raintpl_tpl', 'tpl/');
+        $this->setEmpty('resource.theme', 'default');
+        $this->setEmpty('resource.raintpl_tmp', 'tmp/');
+        $this->setEmpty('resource.thumbnails_cache', 'cache');
+        $this->setEmpty('resource.page_cache', 'pagecache');
+
+        $this->setEmpty('security.ban_after', 4);
+        $this->setEmpty('security.ban_duration', 1800);
+        $this->setEmpty('security.session_protection_disabled', false);
+        $this->setEmpty('security.open_shaarli', false);
+        $this->setEmpty('security.allowed_protocols', ['ftp', 'ftps', 'magnet']);
+
+        $this->setEmpty('general.header_link', '/');
+        $this->setEmpty('general.links_per_page', 20);
+        $this->setEmpty('general.enabled_plugins', self::$DEFAULT_PLUGINS);
+        $this->setEmpty('general.default_note_title', 'Note: ');
+        $this->setEmpty('general.retrieve_description', true);
+        $this->setEmpty('general.enable_async_metadata', true);
+        $this->setEmpty('general.tags_separator', ' ');
+
+        $this->setEmpty('updates.check_updates', true);
+        $this->setEmpty('updates.check_updates_branch', 'latest');
+        $this->setEmpty('updates.check_updates_interval', 86400);
+
+        $this->setEmpty('feed.rss_permalinks', true);
+        $this->setEmpty('feed.show_atom', true);
+
+        $this->setEmpty('privacy.default_private_links', false);
+        $this->setEmpty('privacy.hide_public_links', false);
+        $this->setEmpty('privacy.force_login', false);
+        $this->setEmpty('privacy.hide_timestamps', false);
+        // default state of the 'remember me' checkbox of the login form
+        $this->setEmpty('privacy.remember_user_default', true);
+
+        $this->setEmpty('thumbnails.mode', Thumbnailer::MODE_ALL);
+        $this->setEmpty('thumbnails.width', '125');
+        $this->setEmpty('thumbnails.height', '90');
+
+        $this->setEmpty('translation.language', 'auto');
+        $this->setEmpty('translation.mode', 'php');
+        $this->setEmpty('translation.extensions', []);
+
+        $this->setEmpty('plugins', []);
+
+        $this->setEmpty('formatter', 'markdown');
+    }
+
+    /**
+     * Set only if the setting does not exists.
+     *
+     * @param string $key   Setting key.
+     * @param mixed  $value Setting value.
+     */
+    public function setEmpty($key, $value)
+    {
+        if (! $this->exists($key)) {
+            $this->set($key, $value);
+        }
+    }
+
+    /**
+     * @return ConfigIO
+     */
+    public function getConfigIO()
+    {
+        return $this->configIO;
+    }
+
+    /**
+     * @param ConfigIO $configIO
+     */
+    public function setConfigIO($configIO)
+    {
+        $this->configIO = $configIO;
+    }
+}

application/config/ConfigPhp.php

@@ -0,0 +1,144 @@
+<?php
+
+namespace Shaarli\Config;
+
+/**
+ * Class ConfigPhp (ConfigIO implementation)
+ *
+ * Handle Shaarli's legacy PHP configuration file.
+ * Note: this is only designed to support the transition to JSON configuration.
+ */
+class ConfigPhp implements ConfigIO
+{
+    /**
+     * @var array List of config key without group.
+     */
+    public static $ROOT_KEYS = [
+        'login',
+        'hash',
+        'salt',
+        'timezone',
+        'title',
+        'titleLink',
+        'redirector',
+        'disablesessionprotection',
+        'privateLinkByDefault',
+    ];
+
+    /**
+     * Map legacy config keys with the new ones.
+     * If ConfigPhp is used, getting <newkey> will actually look for <legacykey>.
+     * The updater will use this array to transform keys when switching to JSON.
+     *
+     * @var array current key => legacy key.
+     */
+    public static $LEGACY_KEYS_MAPPING = [
+        'credentials.login' => 'login',
+        'credentials.hash' => 'hash',
+        'credentials.salt' => 'salt',
+        'resource.data_dir' => 'config.DATADIR',
+        'resource.config' => 'config.CONFIG_FILE',
+        'resource.datastore' => 'config.DATASTORE',
+        'resource.updates' => 'config.UPDATES_FILE',
+        'resource.log' => 'config.LOG_FILE',
+        'resource.update_check' => 'config.UPDATECHECK_FILENAME',
+        'resource.raintpl_tpl' => 'config.RAINTPL_TPL',
+        'resource.theme' => 'config.theme',
+        'resource.raintpl_tmp' => 'config.RAINTPL_TMP',
+        'resource.thumbnails_cache' => 'config.CACHEDIR',
+        'resource.page_cache' => 'config.PAGECACHE',
+        'resource.ban_file' => 'config.IPBANS_FILENAME',
+        'security.session_protection_disabled' => 'disablesessionprotection',
+        'security.ban_after' => 'config.BAN_AFTER',
+        'security.ban_duration' => 'config.BAN_DURATION',
+        'general.title' => 'title',
+        'general.timezone' => 'timezone',
+        'general.header_link' => 'titleLink',
+        'updates.check_updates' => 'config.ENABLE_UPDATECHECK',
+        'updates.check_updates_branch' => 'config.UPDATECHECK_BRANCH',
+        'updates.check_updates_interval' => 'config.UPDATECHECK_INTERVAL',
+        'privacy.default_private_links' => 'privateLinkByDefault',
+        'feed.rss_permalinks' => 'config.ENABLE_RSS_PERMALINKS',
+        'general.links_per_page' => 'config.LINKS_PER_PAGE',
+        'thumbnail.enable_thumbnails' => 'config.ENABLE_THUMBNAILS',
+        'thumbnail.enable_localcache' => 'config.ENABLE_LOCALCACHE',
+        'general.enabled_plugins' => 'config.ENABLED_PLUGINS',
+        'redirector.url' => 'redirector',
+        'redirector.encode_url' => 'config.REDIRECTOR_URLENCODE',
+        'feed.show_atom' => 'config.SHOW_ATOM',
+        'privacy.hide_public_links' => 'config.HIDE_PUBLIC_LINKS',
+        'privacy.hide_timestamps' => 'config.HIDE_TIMESTAMPS',
+        'security.open_shaarli' => 'config.OPEN_SHAARLI',
+    ];
+
+    /**
+     * @inheritdoc
+     */
+    public function read($filepath)
+    {
+        if (! file_exists($filepath) || ! is_readable($filepath)) {
+            return [];
+        }
+
+        include $filepath;
+
+        $out = [];
+        foreach (self::$ROOT_KEYS as $key) {
+            $out[$key] = isset($GLOBALS[$key]) ? $GLOBALS[$key] : '';
+        }
+        $out['config'] = isset($GLOBALS['config']) ? $GLOBALS['config'] : [];
+        $out['plugins'] = isset($GLOBALS['plugins']) ? $GLOBALS['plugins'] : [];
+        return $out;
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function write($filepath, $conf)
+    {
+        $configStr = '<?php ' . PHP_EOL;
+        foreach (self::$ROOT_KEYS as $key) {
+            if (isset($conf[$key])) {
+                $configStr .= '$GLOBALS[\'' . $key . '\'] = ' . var_export($conf[$key], true) . ';' . PHP_EOL;
+            }
+        }
+
+        // Store all $conf['config']
+        foreach ($conf['config'] as $key => $value) {
+            $configStr .= '$GLOBALS[\'config\'][\''
+                . $key
+                . '\'] = '
+                . var_export($conf['config'][$key], true) . ';'
+                . PHP_EOL;
+        }
+
+        if (isset($conf['plugins'])) {
+            foreach ($conf['plugins'] as $key => $value) {
+                $configStr .= '$GLOBALS[\'plugins\'][\''
+                    . $key
+                    . '\'] = '
+                    . var_export($conf['plugins'][$key], true) . ';'
+                    . PHP_EOL;
+            }
+        }
+
+        if (
+            !file_put_contents($filepath, $configStr)
+            || strcmp(file_get_contents($filepath), $configStr) != 0
+        ) {
+            throw new \Shaarli\Exceptions\IOException(
+                $filepath,
+                t('Shaarli could not create the config file. ' .
+                  'Please make sure Shaarli has the right to write in the folder is it installed in.')
+            );
+        }
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function getExtension()
+    {
+        return '.php';
+    }
+}

application/config/ConfigPlugin.php

@@ -0,0 +1,127 @@
+<?php
+
+use Shaarli\Config\Exception\PluginConfigOrderException;
+use Shaarli\Plugin\PluginManager;
+
+/**
+ * Plugin configuration helper functions.
+ *
+ * Note: no access to configuration files here.
+ */
+
+/**
+ * Process plugin administration form data and save it in an array.
+ *
+ * @param array $formData Data sent by the plugin admin form.
+ *
+ * @return array New list of enabled plugin, ordered.
+ *
+ * @throws PluginConfigOrderException Plugins can't be sorted because their order is invalid.
+ */
+function save_plugin_config($formData)
+{
+    // We can only save existing plugins
+    $directories = str_replace(
+        PluginManager::$PLUGINS_PATH . '/',
+        '',
+        glob(PluginManager::$PLUGINS_PATH . '/*')
+    );
+    $formData = array_filter(
+        $formData,
+        function ($value, string $key) use ($directories) {
+            return startsWith($key, 'order') || in_array($key, $directories);
+        },
+        ARRAY_FILTER_USE_BOTH
+    );
+
+    // Make sure there are no duplicates in orders.
+    if (!validate_plugin_order($formData)) {
+        throw new PluginConfigOrderException();
+    }
+
+    $plugins = [];
+    $newEnabledPlugins = [];
+    foreach ($formData as $key => $data) {
+        if (startsWith($key, 'order')) {
+            continue;
+        }
+
+        // If there is no order, it means a disabled plugin has been enabled.
+        if (isset($formData['order_' . $key])) {
+            $plugins[(int) $formData['order_' . $key]] = $key;
+        } else {
+            $newEnabledPlugins[] = $key;
+        }
+    }
+
+    // New enabled plugins will be added at the end of order.
+    $plugins = array_merge($plugins, $newEnabledPlugins);
+
+    // Sort plugins by order.
+    if (!ksort($plugins)) {
+        throw new PluginConfigOrderException();
+    }
+
+    $finalPlugins = [];
+    // Make plugins order continuous.
+    foreach ($plugins as $plugin) {
+        $finalPlugins[] = $plugin;
+    }
+
+    return $finalPlugins;
+}
+
+/**
+ * Validate plugin array submitted.
+ * Will fail if there is duplicate orders value.
+ *
+ * @param array $formData Data from submitted form.
+ *
+ * @return bool true if ok, false otherwise.
+ */
+function validate_plugin_order($formData)
+{
+    $orders = [];
+    foreach ($formData as $key => $value) {
+        // No duplicate order allowed.
+        if (in_array($value, $orders, true)) {
+            return false;
+        }
+
+        if (startsWith($key, 'order')) {
+            $orders[] = $value;
+        }
+    }
+
+    return true;
+}
+
+/**
+ * Affect plugin parameters values from the ConfigManager into plugins array.
+ *
+ * @param mixed $plugins Plugins array:
+ *                         $plugins[<plugin_name>]['parameters'][<param_name>] = [
+ *                                                                                 'value' => <value>,
+ *                                                                                 'desc' => <description>
+ *                                                                               ]
+ * @param mixed $conf  Plugins configuration.
+ *
+ * @return mixed Updated $plugins array.
+ */
+function load_plugin_parameter_values($plugins, $conf)
+{
+    $out = $plugins;
+    foreach ($plugins as $name => $plugin) {
+        if (empty($plugin['parameters'])) {
+            continue;
+        }
+
+        foreach ($plugin['parameters'] as $key => $param) {
+            if (!empty($conf[$key])) {
+                $out[$name]['parameters'][$key]['value'] = $conf[$key];
+            }
+        }
+    }
+
+    return $out;
+}

application/config/exception/MissingFieldConfigException.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Shaarli\Config\Exception;
+
+/**
+ * Exception used if a mandatory field is missing in given configuration.
+ */
+class MissingFieldConfigException extends \Exception
+{
+    public $field;
+
+    /**
+     * Construct exception.
+     *
+     * @param string $field field name missing.
+     */
+    public function __construct($field)
+    {
+        $this->field = $field;
+        $this->message = sprintf(t('Configuration value is required for %s'), $this->field);
+    }
+}

application/config/exception/PluginConfigOrderException.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Shaarli\Config\Exception;
+
+/**
+ * Exception used if an error occur while saving plugin configuration.
+ */
+class PluginConfigOrderException extends \Exception
+{
+    /**
+     * Construct exception.
+     */
+    public function __construct()
+    {
+        $this->message = t('An error occurred while trying to save plugins loading order.');
+    }
+}

application/config/exception/UnauthorizedConfigException.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Shaarli\Config\Exception;
+
+/**
+ * Exception used if an unauthorized attempt to edit configuration has been made.
+ */
+class UnauthorizedConfigException extends \Exception
+{
+    /**
+     * Construct exception.
+     */
+    public function __construct()
+    {
+        $this->message = t('You are not authorized to alter config.');
+    }
+}

application/container/ContainerBuilder.php

@@ -0,0 +1,176 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Container;
+
+use malkusch\lock\mutex\FlockMutex;
+use Psr\Log\LoggerInterface;
+use Shaarli\Bookmark\BookmarkFileService;
+use Shaarli\Bookmark\BookmarkServiceInterface;
+use Shaarli\Config\ConfigManager;
+use Shaarli\Feed\FeedBuilder;
+use Shaarli\Formatter\FormatterFactory;
+use Shaarli\Front\Controller\Visitor\ErrorController;
+use Shaarli\Front\Controller\Visitor\ErrorNotFoundController;
+use Shaarli\History;
+use Shaarli\Http\HttpAccess;
+use Shaarli\Http\MetadataRetriever;
+use Shaarli\Netscape\NetscapeBookmarkUtils;
+use Shaarli\Plugin\PluginManager;
+use Shaarli\Render\PageBuilder;
+use Shaarli\Render\PageCacheManager;
+use Shaarli\Security\CookieManager;
+use Shaarli\Security\LoginManager;
+use Shaarli\Security\SessionManager;
+use Shaarli\Thumbnailer;
+use Shaarli\Updater\Updater;
+use Shaarli\Updater\UpdaterUtils;
+
+/**
+ * Class ContainerBuilder
+ *
+ * Helper used to build a Slim container instance with Shaarli's object dependencies.
+ * Note that most injected objects MUST be added as closures, to let the container instantiate
+ * only the objects it requires during the execution.
+ *
+ * @package Container
+ */
+class ContainerBuilder
+{
+    /** @var ConfigManager */
+    protected $conf;
+
+    /** @var SessionManager */
+    protected $session;
+
+    /** @var CookieManager */
+    protected $cookieManager;
+
+    /** @var LoginManager */
+    protected $login;
+
+    /** @var PluginManager */
+    protected $pluginManager;
+
+    /** @var LoggerInterface */
+    protected $logger;
+
+    /** @var string|null */
+    protected $basePath = null;
+
+    public function __construct(
+        ConfigManager $conf,
+        SessionManager $session,
+        CookieManager $cookieManager,
+        LoginManager $login,
+        PluginManager $pluginManager,
+        LoggerInterface $logger
+    ) {
+        $this->conf = $conf;
+        $this->session = $session;
+        $this->login = $login;
+        $this->cookieManager = $cookieManager;
+        $this->pluginManager = $pluginManager;
+        $this->logger = $logger;
+    }
+
+    public function build(): ShaarliContainer
+    {
+        $container = new ShaarliContainer();
+
+        $container['conf'] = $this->conf;
+        $container['sessionManager'] = $this->session;
+        $container['cookieManager'] = $this->cookieManager;
+        $container['loginManager'] = $this->login;
+        $container['pluginManager'] = $this->pluginManager;
+        $container['logger'] = $this->logger;
+        $container['basePath'] = $this->basePath;
+
+
+        $container['history'] = function (ShaarliContainer $container): History {
+            return new History($container->conf->get('resource.history'));
+        };
+
+        $container['bookmarkService'] = function (ShaarliContainer $container): BookmarkServiceInterface {
+            return new BookmarkFileService(
+                $container->conf,
+                $container->pluginManager,
+                $container->history,
+                new FlockMutex(fopen(SHAARLI_MUTEX_FILE, 'r'), 2),
+                $container->loginManager->isLoggedIn()
+            );
+        };
+
+        $container['metadataRetriever'] = function (ShaarliContainer $container): MetadataRetriever {
+            return new MetadataRetriever($container->conf, $container->httpAccess);
+        };
+
+        $container['pageBuilder'] = function (ShaarliContainer $container): PageBuilder {
+            return new PageBuilder(
+                $container->conf,
+                $container->sessionManager->getSession(),
+                $container->logger,
+                $container->bookmarkService,
+                $container->sessionManager->generateToken(),
+                $container->loginManager->isLoggedIn()
+            );
+        };
+
+        $container['formatterFactory'] = function (ShaarliContainer $container): FormatterFactory {
+            return new FormatterFactory(
+                $container->conf,
+                $container->loginManager->isLoggedIn()
+            );
+        };
+
+        $container['pageCacheManager'] = function (ShaarliContainer $container): PageCacheManager {
+            return new PageCacheManager(
+                $container->conf->get('resource.page_cache'),
+                $container->loginManager->isLoggedIn()
+            );
+        };
+
+        $container['feedBuilder'] = function (ShaarliContainer $container): FeedBuilder {
+            return new FeedBuilder(
+                $container->bookmarkService,
+                $container->formatterFactory->getFormatter(),
+                $container->environment,
+                $container->loginManager->isLoggedIn()
+            );
+        };
+
+        $container['thumbnailer'] = function (ShaarliContainer $container): Thumbnailer {
+            return new Thumbnailer($container->conf);
+        };
+
+        $container['httpAccess'] = function (): HttpAccess {
+            return new HttpAccess();
+        };
+
+        $container['netscapeBookmarkUtils'] = function (ShaarliContainer $container): NetscapeBookmarkUtils {
+            return new NetscapeBookmarkUtils($container->bookmarkService, $container->conf, $container->history);
+        };
+
+        $container['updater'] = function (ShaarliContainer $container): Updater {
+            return new Updater(
+                UpdaterUtils::readUpdatesFile($container->conf->get('resource.updates')),
+                $container->bookmarkService,
+                $container->conf,
+                $container->loginManager->isLoggedIn()
+            );
+        };
+
+        $container['notFoundHandler'] = function (ShaarliContainer $container): ErrorNotFoundController {
+            return new ErrorNotFoundController($container);
+        };
+        $container['errorHandler'] = function (ShaarliContainer $container): ErrorController {
+            return new ErrorController($container);
+        };
+        $container['phpErrorHandler'] = function (ShaarliContainer $container): ErrorController {
+            return new ErrorController($container);
+        };
+
+        return $container;
+    }
+}

application/container/ShaarliContainer.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Container;
+
+use Psr\Log\LoggerInterface;
+use Shaarli\Bookmark\BookmarkServiceInterface;
+use Shaarli\Config\ConfigManager;
+use Shaarli\Feed\FeedBuilder;
+use Shaarli\Formatter\FormatterFactory;
+use Shaarli\History;
+use Shaarli\Http\HttpAccess;
+use Shaarli\Http\MetadataRetriever;
+use Shaarli\Netscape\NetscapeBookmarkUtils;
+use Shaarli\Plugin\PluginManager;
+use Shaarli\Render\PageBuilder;
+use Shaarli\Render\PageCacheManager;
+use Shaarli\Security\CookieManager;
+use Shaarli\Security\LoginManager;
+use Shaarli\Security\SessionManager;
+use Shaarli\Thumbnailer;
+use Shaarli\Updater\Updater;
+use Slim\Container;
+
+/**
+ * Extension of Slim container to document the injected objects.
+ *
+ * @property string                   $basePath              Shaarli's instance base path (e.g. `/shaarli/`)
+ * @property BookmarkServiceInterface $bookmarkService
+ * @property CookieManager            $cookieManager
+ * @property ConfigManager            $conf
+ * @property mixed[]                  $environment           $_SERVER automatically injected by Slim
+ * @property callable                 $errorHandler          Overrides default Slim exception display
+ * @property FeedBuilder              $feedBuilder
+ * @property FormatterFactory         $formatterFactory
+ * @property History                  $history
+ * @property HttpAccess               $httpAccess
+ * @property LoginManager             $loginManager
+ * @property LoggerInterface          $logger
+ * @property MetadataRetriever        $metadataRetriever
+ * @property NetscapeBookmarkUtils    $netscapeBookmarkUtils
+ * @property callable                 $notFoundHandler       Overrides default Slim exception display
+ * @property PageBuilder              $pageBuilder
+ * @property PageCacheManager         $pageCacheManager
+ * @property callable                 $phpErrorHandler       Overrides default Slim PHP error display
+ * @property PluginManager            $pluginManager
+ * @property SessionManager           $sessionManager
+ * @property Thumbnailer              $thumbnailer
+ * @property Updater                  $updater
+ */
+class ShaarliContainer extends Container
+{
+}

application/exceptions/IOException.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace Shaarli\Exceptions;
+
+use Exception;
+
+/**
+ * Exception class thrown when a filesystem access failure happens
+ */
+class IOException extends Exception
+{
+    private $path;
+
+    /**
+     * Construct a new IOException
+     *
+     * @param string $path    path to the resource that cannot be accessed
+     * @param string $message Custom exception message.
+     */
+    public function __construct($path, $message = '')
+    {
+        $this->path = $path;
+        $this->message = empty($message) ? t('Error accessing') : $message;
+        $this->message .= ' "' . $this->path . '"';
+    }
+}

application/feed/CachedPage.php

@@ -0,0 +1,81 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Feed;
+
+use DatePeriod;
+
+/**
+ * Simple cache system, mainly for the RSS/ATOM feeds
+ */
+class CachedPage
+{
+    /** Directory containing page caches */
+    protected $cacheDir;
+
+    /** Should this URL be cached (boolean)? */
+    protected $shouldBeCached;
+
+    /** Name of the cache file for this URL */
+    protected $filename;
+
+    /** @var DatePeriod|null Optionally specify a period of time for cache validity */
+    protected $validityPeriod;
+
+    /**
+     * Creates a new CachedPage
+     *
+     * @param string      $cacheDir       page cache directory
+     * @param string      $url            page URL
+     * @param bool        $shouldBeCached whether this page needs to be cached
+     * @param ?DatePeriod $validityPeriod Optionally specify a time limit on requested cache
+     */
+    public function __construct($cacheDir, $url, $shouldBeCached, ?DatePeriod $validityPeriod)
+    {
+        // TODO: check write access to the cache directory
+        $this->cacheDir = $cacheDir;
+        $this->filename = $this->cacheDir . '/' . sha1($url) . '.cache';
+        $this->shouldBeCached = $shouldBeCached;
+        $this->validityPeriod = $validityPeriod;
+    }
+
+    /**
+     * Returns the cached version of a page, if it exists and should be cached
+     *
+     * @return string a cached version of the page if it exists, null otherwise
+     */
+    public function cachedVersion()
+    {
+        if (!$this->shouldBeCached) {
+            return null;
+        }
+        if (!is_file($this->filename)) {
+            return null;
+        }
+        if ($this->validityPeriod !== null) {
+            $cacheDate = \DateTime::createFromFormat('U', (string) filemtime($this->filename));
+            if (
+                $cacheDate < $this->validityPeriod->getStartDate()
+                || $cacheDate > $this->validityPeriod->getEndDate()
+            ) {
+                return null;
+            }
+        }
+
+        return file_get_contents($this->filename);
+    }
+
+    /**
+     * Puts a page in the cache
+     *
+     * @param string $pageContent XML content to cache
+     */
+    public function cache($pageContent)
+    {
+        if (!$this->shouldBeCached) {
+            return;
+        }
+        file_put_contents($this->filename, $pageContent);
+    }
+}

application/feed/FeedBuilder.php

@@ -0,0 +1,286 @@
+<?php
+
+namespace Shaarli\Feed;
+
+use DateTime;
+use Shaarli\Bookmark\Bookmark;
+use Shaarli\Bookmark\BookmarkServiceInterface;
+use Shaarli\Formatter\BookmarkFormatter;
+
+/**
+ * FeedBuilder class.
+ *
+ * Used to build ATOM and RSS feeds data.
+ */
+class FeedBuilder
+{
+    /**
+     * @var string Constant: RSS feed type.
+     */
+    public static $FEED_RSS = 'rss';
+
+    /**
+     * @var string Constant: ATOM feed type.
+     */
+    public static $FEED_ATOM = 'atom';
+
+    /**
+     * @var string Default language if the locale isn't set.
+     */
+    public static $DEFAULT_LANGUAGE = 'en-en';
+
+    /**
+     * @var int Number of bookmarks to display in a feed by default.
+     */
+    public static $DEFAULT_NB_LINKS = 50;
+
+    /**
+     * @var BookmarkServiceInterface instance.
+     */
+    protected $linkDB;
+
+    /**
+     * @var BookmarkFormatter instance.
+     */
+    protected $formatter;
+
+    /** @var mixed[] $_SERVER */
+    protected $serverInfo;
+
+    /**
+     * @var boolean True if the user is currently logged in, false otherwise.
+     */
+    protected $isLoggedIn;
+
+    /**
+     * @var boolean Use permalinks instead of direct bookmarks if true.
+     */
+    protected $usePermalinks;
+
+    /**
+     * @var boolean true to hide dates in feeds.
+     */
+    protected $hideDates;
+
+    /**
+     * @var string server locale.
+     */
+    protected $locale;
+    /**
+     * @var DateTime Latest item date.
+     */
+    protected $latestDate;
+
+    /**
+     * Feed constructor.
+     *
+     * @param BookmarkServiceInterface $linkDB     LinkDB instance.
+     * @param BookmarkFormatter        $formatter  instance.
+     * @param array                    $serverInfo $_SERVER.
+     * @param boolean                  $isLoggedIn True if the user is currently logged in, false otherwise.
+     */
+    public function __construct($linkDB, $formatter, $serverInfo, $isLoggedIn)
+    {
+        $this->linkDB = $linkDB;
+        $this->formatter = $formatter;
+        $this->serverInfo = $serverInfo;
+        $this->isLoggedIn = $isLoggedIn;
+    }
+
+    /**
+     * Build data for feed templates.
+     *
+     * @param string $feedType   Type of feed (RSS/ATOM).
+     * @param array  $userInput  $_GET.
+     *
+     * @return array Formatted data for feeds templates.
+     */
+    public function buildData(string $feedType, ?array $userInput)
+    {
+        // Search for untagged bookmarks
+        if (isset($this->userInput['searchtags']) && empty($userInput['searchtags'])) {
+            $userInput['searchtags'] = false;
+        }
+
+        $limit = $this->getLimit($userInput);
+
+        // Optionally filter the results:
+        $searchResult = $this->linkDB->search($userInput ?? [], null, false, false, true, ['limit' => $limit]);
+
+        $pageaddr = escape(index_url($this->serverInfo));
+        $this->formatter->addContextData('index_url', $pageaddr);
+        $links = [];
+        foreach ($searchResult->getBookmarks() as $key => $bookmark) {
+            $links[$key] = $this->buildItem($feedType, $bookmark, $pageaddr);
+        }
+
+        $data['language'] = $this->getTypeLanguage($feedType);
+        $data['last_update'] = $this->getLatestDateFormatted($feedType);
+        $data['show_dates'] = !$this->hideDates || $this->isLoggedIn;
+        // Remove leading path from REQUEST_URI (already contained in $pageaddr).
+        $requestUri = preg_replace('#(.*?/)(feed.*)#', '$2', escape($this->serverInfo['REQUEST_URI']));
+        $data['self_link'] = $pageaddr . $requestUri;
+        $data['index_url'] = $pageaddr;
+        $data['usepermalinks'] = $this->usePermalinks === true;
+        $data['links'] = $links;
+
+        return $data;
+    }
+
+    /**
+     * Set this to true to use permalinks instead of direct bookmarks.
+     *
+     * @param boolean $usePermalinks true to force permalinks.
+     */
+    public function setUsePermalinks($usePermalinks)
+    {
+        $this->usePermalinks = $usePermalinks;
+    }
+
+    /**
+     * Set this to true to hide timestamps in feeds.
+     *
+     * @param boolean $hideDates true to enable.
+     */
+    public function setHideDates($hideDates)
+    {
+        $this->hideDates = $hideDates;
+    }
+
+    /**
+     * Set the locale. Used to show feed language.
+     *
+     * @param string $locale The locale (eg. 'fr_FR.UTF8').
+     */
+    public function setLocale($locale)
+    {
+        $this->locale = strtolower($locale);
+    }
+
+    /**
+     * Build a feed item (one per shaare).
+     *
+     * @param string $feedType Type of feed (RSS/ATOM).
+     * @param Bookmark $link     Single link array extracted from LinkDB.
+     * @param string   $pageaddr Index URL.
+     *
+     * @return array Link array with feed attributes.
+     */
+    protected function buildItem(string $feedType, $link, $pageaddr)
+    {
+        $data = $this->formatter->format($link);
+        $data['guid'] = rtrim($pageaddr, '/') . '/shaare/' . $data['shorturl'];
+        if ($this->usePermalinks === true) {
+            $permalink = '<a href="' . $data['url'] . '" title="' . t('Direct link') . '">' . t('Direct link') . '</a>';
+        } else {
+            $permalink = '<a href="' . $data['guid'] . '" title="' . t('Permalink') . '">' . t('Permalink') . '</a>';
+        }
+        $data['description'] .= PHP_EOL . PHP_EOL . '<br>&#8212; ' . $permalink;
+
+        $data['pub_iso_date'] = $this->getIsoDate($feedType, $data['created']);
+
+        // atom:entry elements MUST contain exactly one atom:updated element.
+        if (!empty($link->getUpdated())) {
+            $data['up_iso_date'] = $this->getIsoDate($feedType, $data['updated'], DateTime::ATOM);
+        } else {
+            $data['up_iso_date'] = $this->getIsoDate($feedType, $data['created'], DateTime::ATOM);
+        }
+
+        // Save the more recent item.
+        if (empty($this->latestDate) || $this->latestDate < $data['created']) {
+            $this->latestDate = $data['created'];
+        }
+        if (!empty($data['updated']) && $this->latestDate < $data['updated']) {
+            $this->latestDate = $data['updated'];
+        }
+
+        return $data;
+    }
+
+    /**
+     * Get the language according to the feed type, based on the locale:
+     *
+     *   - RSS format: en-us (default: 'en-en').
+     *   - ATOM format: fr (default: 'en').
+     *
+     * @param string $feedType Type of feed (RSS/ATOM).
+     *
+     * @return string The language.
+     */
+    protected function getTypeLanguage(string $feedType)
+    {
+        // Use the locale do define the language, if available.
+        if (!empty($this->locale) && preg_match('/^\w{2}[_\-]\w{2}/', $this->locale)) {
+            $length = ($feedType === self::$FEED_RSS) ? 5 : 2;
+            return str_replace('_', '-', substr($this->locale, 0, $length));
+        }
+        return ($feedType === self::$FEED_RSS) ? 'en-en' : 'en';
+    }
+
+    /**
+     * Format the latest item date found according to the feed type.
+     *
+     * Return an empty string if invalid DateTime is passed.
+     *
+     * @param string $feedType Type of feed (RSS/ATOM).
+     *
+     * @return string Formatted date.
+     */
+    protected function getLatestDateFormatted(string $feedType)
+    {
+        if (empty($this->latestDate) || !$this->latestDate instanceof DateTime) {
+            return '';
+        }
+
+        $type = ($feedType == self::$FEED_RSS) ? DateTime::RSS : DateTime::ATOM;
+        return $this->latestDate->format($type);
+    }
+
+    /**
+     * Get ISO date from DateTime according to feed type.
+     *
+     * @param string      $feedType Type of feed (RSS/ATOM).
+     * @param DateTime    $date   Date to format.
+     * @param string|bool $format Force format.
+     *
+     * @return string Formatted date.
+     */
+    protected function getIsoDate(string $feedType, DateTime $date, $format = false)
+    {
+        if ($format !== false) {
+            return $date->format($format);
+        }
+        if ($feedType == self::$FEED_RSS) {
+            return $date->format(DateTime::RSS);
+        }
+        return $date->format(DateTime::ATOM);
+    }
+
+    /**
+     * Returns the number of link to display according to 'nb' user input parameter.
+     *
+     * If 'nb' not set or invalid, default value: $DEFAULT_NB_LINKS.
+     * If 'nb' is set to 'all', display all filtered bookmarks (max parameter).
+     *
+     * @param array $userInput $_GET.
+     *
+     * @return int number of bookmarks to display.
+     */
+    protected function getLimit(?array $userInput)
+    {
+        if (empty($userInput['nb'])) {
+            return self::$DEFAULT_NB_LINKS;
+        }
+
+        if ($userInput['nb'] == 'all') {
+            return null;
+        }
+
+        $intNb = intval($userInput['nb']);
+        if (!is_int($intNb) || $intNb == 0) {
+            return self::$DEFAULT_NB_LINKS;
+        }
+
+        return $intNb;
+    }
+}

application/formatter/BookmarkDefaultFormatter.php

@@ -0,0 +1,229 @@
+<?php
+
+namespace Shaarli\Formatter;
+
+use Shaarli\Bookmark\Bookmark;
+
+/**
+ * Class BookmarkDefaultFormatter
+ *
+ * Default bookmark formatter.
+ * Escape values for HTML display and automatically add link to URL and hashtags.
+ *
+ * @package Shaarli\Formatter
+ */
+class BookmarkDefaultFormatter extends BookmarkFormatter
+{
+    public const SEARCH_HIGHLIGHT_OPEN = 'SHAARLI_O_HIGHLIGHT';
+    public const SEARCH_HIGHLIGHT_CLOSE = 'SHAARLI_C_HIGHLIGHT';
+
+    /**
+     * @inheritdoc
+     */
+    protected function formatTitle($bookmark)
+    {
+        return escape($bookmark->getTitle());
+    }
+
+    /**
+     * @inheritdoc
+     */
+    protected function formatTitleHtml($bookmark)
+    {
+        $title = $this->tokenizeSearchHighlightField(
+            $bookmark->getTitle() ?? '',
+            $bookmark->getAdditionalContentEntry('search_highlight')['title'] ?? []
+        );
+
+        return $this->replaceTokens(escape($title));
+    }
+
+    /**
+     * @inheritdoc
+     */
+    protected function formatDescription($bookmark)
+    {
+        $indexUrl = ! empty($this->contextData['index_url']) ? $this->contextData['index_url'] : '';
+        $description = $this->tokenizeSearchHighlightField(
+            $bookmark->getDescription() ?? '',
+            $bookmark->getAdditionalContentEntry('search_highlight')['description'] ?? []
+        );
+        $description = format_description(
+            escape($description),
+            $indexUrl,
+            $this->conf->get('formatter_settings.autolink', true)
+        );
+
+        return $this->replaceTokens($description);
+    }
+
+    /**
+     * @inheritdoc
+     */
+    protected function formatTagList($bookmark)
+    {
+        return escape(parent::formatTagList($bookmark));
+    }
+
+    /**
+     * @inheritdoc
+     */
+    protected function formatTagListHtml($bookmark)
+    {
+        $tagsSeparator = $this->conf->get('general.tags_separator', ' ');
+        if (empty($bookmark->getAdditionalContentEntry('search_highlight')['tags'])) {
+            return $this->formatTagList($bookmark);
+        }
+
+        $tags = $this->tokenizeSearchHighlightField(
+            $bookmark->getTagsString($tagsSeparator),
+            $bookmark->getAdditionalContentEntry('search_highlight')['tags']
+        );
+        $tags = $this->filterTagList(tags_str2array($tags, $tagsSeparator));
+        $tags = escape($tags);
+        $tags = $this->replaceTokensArray($tags);
+
+        return $tags;
+    }
+
+    /**
+     * @inheritdoc
+     */
+    protected function formatTagString($bookmark)
+    {
+        return implode($this->conf->get('general.tags_separator'), $this->formatTagList($bookmark));
+    }
+
+    /**
+     * @inheritdoc
+     */
+    protected function formatUrl($bookmark)
+    {
+        if ($bookmark->isNote() && isset($this->contextData['index_url'])) {
+            return rtrim($this->contextData['index_url'], '/') . '/' . escape(ltrim($bookmark->getUrl(), '/'));
+        }
+
+        return escape($bookmark->getUrl());
+    }
+
+    /**
+     * @inheritdoc
+     */
+    protected function formatRealUrl($bookmark)
+    {
+        if ($bookmark->isNote()) {
+            if (isset($this->contextData['index_url'])) {
+                $prefix = rtrim($this->contextData['index_url'], '/') . '/';
+            }
+
+            if (isset($this->contextData['base_path'])) {
+                $prefix = rtrim($this->contextData['base_path'], '/') . '/';
+            }
+
+            return escape($prefix ?? '') . escape(ltrim($bookmark->getUrl() ?? '', '/'));
+        }
+
+        return escape($bookmark->getUrl());
+    }
+
+    /**
+     * @inheritdoc
+     */
+    protected function formatUrlHtml($bookmark)
+    {
+        $url = $this->tokenizeSearchHighlightField(
+            $bookmark->getUrl() ?? '',
+            $bookmark->getAdditionalContentEntry('search_highlight')['url'] ?? []
+        );
+
+        return $this->replaceTokens(escape($url));
+    }
+
+    /**
+     * @inheritdoc
+     */
+    protected function formatThumbnail($bookmark)
+    {
+        return escape($bookmark->getThumbnail());
+    }
+
+    /**
+     * @inheritDoc
+     */
+    protected function formatAdditionalContent(Bookmark $bookmark): array
+    {
+        $additionalContent = parent::formatAdditionalContent($bookmark);
+
+        unset($additionalContent['search_highlight']);
+
+        return $additionalContent;
+    }
+
+    /**
+     * Insert search highlight token in provided field content based on a list of search result positions
+     *
+     * @param string     $fieldContent
+     * @param array|null $positions    List of of search results with 'start' and 'end' positions.
+     *
+     * @return string Updated $fieldContent.
+     */
+    protected function tokenizeSearchHighlightField(string $fieldContent, ?array $positions): string
+    {
+        if (empty($positions)) {
+            return $fieldContent;
+        }
+
+        $insertedTokens = 0;
+        $tokenLength = strlen(static::SEARCH_HIGHLIGHT_OPEN);
+        foreach ($positions as $position) {
+            $position = [
+                'start' => $position['start'] + ($insertedTokens * $tokenLength),
+                'end' => $position['end'] + ($insertedTokens * $tokenLength),
+            ];
+
+            $content = mb_substr($fieldContent, 0, $position['start']);
+            $content .= static::SEARCH_HIGHLIGHT_OPEN;
+            $content .= mb_substr($fieldContent, $position['start'], $position['end'] - $position['start']);
+            $content .= static::SEARCH_HIGHLIGHT_CLOSE;
+            $content .= mb_substr($fieldContent, $position['end']);
+
+            $fieldContent = $content;
+
+            $insertedTokens += 2;
+        }
+
+        return $fieldContent;
+    }
+
+    /**
+     * Replace search highlight tokens with HTML highlighted span.
+     *
+     * @param string $fieldContent
+     *
+     * @return string updated content.
+     */
+    protected function replaceTokens(string $fieldContent): string
+    {
+        return str_replace(
+            [static::SEARCH_HIGHLIGHT_OPEN, static::SEARCH_HIGHLIGHT_CLOSE],
+            ['<span class="search-highlight">', '</span>'],
+            $fieldContent
+        );
+    }
+
+    /**
+     * Apply replaceTokens to an array of content strings.
+     *
+     * @param string[] $fieldContents
+     *
+     * @return array
+     */
+    protected function replaceTokensArray(array $fieldContents): array
+    {
+        foreach ($fieldContents as &$entry) {
+            $entry = $this->replaceTokens($entry);
+        }
+
+        return $fieldContents;
+    }
+}

application/formatter/BookmarkFormatter.php

@@ -0,0 +1,390 @@
+<?php
+
+namespace Shaarli\Formatter;
+
+use DateTimeInterface;
+use Shaarli\Bookmark\Bookmark;
+use Shaarli\Config\ConfigManager;
+
+/**
+ * Class BookmarkFormatter
+ *
+ * Abstract class processing all bookmark attributes through methods designed to be overridden.
+ *
+ * List of available formatted fields:
+ *   - id                 ID
+ *   - shorturl           Unique identifier, used in permalinks
+ *   - url                URL, can be altered in some way, e.g. passing through an HTTP reverse proxy
+ *   - real_url           (legacy) same as `url`
+ *   - url_html           URL to be displayed in HTML content (it can contain HTML tags)
+ *   - title              Title
+ *   - title_html         Title to be displayed in HTML content (it can contain HTML tags)
+ *   - description        Description content. It most likely contains HTML tags
+ *   - thumbnail          Thumbnail: path to local cache file, false if there is none, null if hasn't been retrieved
+ *   - taglist            List of tags (array)
+ *   - taglist_urlencoded List of tags (array) URL encoded: it must be used to create a link to a URL containing a tag
+ *   - taglist_html       List of tags (array) to be displayed in HTML content (it can contain HTML tags)
+ *   - tags               Tags separated by a single whitespace
+ *   - tags_urlencoded    Tags separated by a single whitespace, URL encoded: must be used to create a link
+ *   - sticky             Is sticky (bool)
+ *   - private            Is private (bool)
+ *   - class              Additional CSS class
+ *   - created            Creation DateTime
+ *   - updated            Last edit DateTime
+ *   - timestamp          Creation timestamp
+ *   - updated_timestamp  Last edit timestamp
+ *
+ * @package Shaarli\Formatter
+ */
+abstract class BookmarkFormatter
+{
+    /**
+     * @var ConfigManager
+     */
+    protected $conf;
+
+    /** @var bool */
+    protected $isLoggedIn;
+
+    /**
+     * @var array Additional parameters than can be used for specific formatting
+     *            e.g. index_url for Feed formatting
+     */
+    protected $contextData = [];
+
+    /**
+     * LinkDefaultFormatter constructor.
+     * @param ConfigManager $conf
+     */
+    public function __construct(ConfigManager $conf, bool $isLoggedIn)
+    {
+        $this->conf = $conf;
+        $this->isLoggedIn = $isLoggedIn;
+    }
+
+    /**
+     * Convert a Bookmark into an array usable by templates and plugins.
+     *
+     * All Bookmark attributes are formatted through a format method
+     * that can be overridden in a formatter extending this class.
+     *
+     * @param Bookmark $bookmark instance
+     *
+     * @return array formatted representation of a Bookmark
+     */
+    public function format($bookmark)
+    {
+        $out['id'] = $this->formatId($bookmark);
+        $out['shorturl'] = $this->formatShortUrl($bookmark);
+        $out['url'] = $this->formatUrl($bookmark);
+        $out['real_url'] = $this->formatRealUrl($bookmark);
+        $out['url_html'] = $this->formatUrlHtml($bookmark);
+        $out['title'] = $this->formatTitle($bookmark);
+        $out['title_html'] = $this->formatTitleHtml($bookmark);
+        $out['description'] = $this->formatDescription($bookmark);
+        $out['thumbnail'] = $this->formatThumbnail($bookmark);
+        $out['taglist'] = $this->formatTagList($bookmark);
+        $out['taglist_urlencoded'] = $this->formatTagListUrlEncoded($bookmark);
+        $out['taglist_html'] = $this->formatTagListHtml($bookmark);
+        $out['tags'] = $this->formatTagString($bookmark);
+        $out['tags_urlencoded'] = $this->formatTagStringUrlEncoded($bookmark);
+        $out['sticky'] = $bookmark->isSticky();
+        $out['private'] = $bookmark->isPrivate();
+        $out['class'] = $this->formatClass($bookmark);
+        $out['created'] = $this->formatCreated($bookmark);
+        $out['updated'] = $this->formatUpdated($bookmark);
+        $out['timestamp'] = $this->formatCreatedTimestamp($bookmark);
+        $out['updated_timestamp'] = $this->formatUpdatedTimestamp($bookmark);
+        $out['additional_content'] = $this->formatAdditionalContent($bookmark);
+
+        return $out;
+    }
+
+    /**
+     * Add additional data available to formatters.
+     * This is used for example to add `index_url` in description's links.
+     *
+     * @param string $key   Context data key
+     * @param string $value Context data value
+     */
+    public function addContextData($key, $value)
+    {
+        $this->contextData[$key] = $value;
+
+        return $this;
+    }
+
+    /**
+     * Format ID
+     *
+     * @param Bookmark $bookmark instance
+     *
+     * @return int formatted ID
+     */
+    protected function formatId($bookmark)
+    {
+        return $bookmark->getId();
+    }
+
+    /**
+     * Format ShortUrl
+     *
+     * @param Bookmark $bookmark instance
+     *
+     * @return string formatted ShortUrl
+     */
+    protected function formatShortUrl($bookmark)
+    {
+        return $bookmark->getShortUrl();
+    }
+
+    /**
+     * Format Url
+     *
+     * @param Bookmark $bookmark instance
+     *
+     * @return string formatted Url
+     */
+    protected function formatUrl($bookmark)
+    {
+        return $bookmark->getUrl();
+    }
+
+    /**
+     * Format RealUrl
+     * Legacy: identical to Url
+     *
+     * @param Bookmark $bookmark instance
+     *
+     * @return string formatted RealUrl
+     */
+    protected function formatRealUrl($bookmark)
+    {
+        return $this->formatUrl($bookmark);
+    }
+
+    /**
+     * Format Url Html: to be displayed in HTML content, it can contains HTML tags.
+     *
+     * @param Bookmark $bookmark instance
+     *
+     * @return string formatted Url HTML
+     */
+    protected function formatUrlHtml($bookmark)
+    {
+        return $this->formatUrl($bookmark);
+    }
+
+    /**
+     * Format Title
+     *
+     * @param Bookmark $bookmark instance
+     *
+     * @return string formatted Title
+     */
+    protected function formatTitle($bookmark)
+    {
+        return $bookmark->getTitle();
+    }
+
+    /**
+     * Format Title HTML: to be displayed in HTML content, it can contains HTML tags.
+     *
+     * @param Bookmark $bookmark instance
+     *
+     * @return string formatted Title
+     */
+    protected function formatTitleHtml($bookmark)
+    {
+        return $bookmark->getTitle();
+    }
+
+    /**
+     * Format Description
+     *
+     * @param Bookmark $bookmark instance
+     *
+     * @return string formatted Description
+     */
+    protected function formatDescription($bookmark)
+    {
+        return $bookmark->getDescription();
+    }
+
+    /**
+     * Format Thumbnail
+     *
+     * @param Bookmark $bookmark instance
+     *
+     * @return string formatted Thumbnail
+     */
+    protected function formatThumbnail($bookmark)
+    {
+        return $bookmark->getThumbnail();
+    }
+
+    /**
+     * Format Tags
+     *
+     * @param Bookmark $bookmark instance
+     *
+     * @return array formatted Tags
+     */
+    protected function formatTagList($bookmark)
+    {
+        return $this->filterTagList($bookmark->getTags());
+    }
+
+    /**
+     * Format Url Encoded Tags
+     *
+     * @param Bookmark $bookmark instance
+     *
+     * @return array formatted Tags
+     */
+    protected function formatTagListUrlEncoded($bookmark)
+    {
+        return array_map('urlencode', $this->filterTagList($bookmark->getTags()));
+    }
+
+    /**
+     * Format Tags HTML: to be displayed in HTML content, it can contains HTML tags.
+     *
+     * @param Bookmark $bookmark instance
+     *
+     * @return array formatted Tags
+     */
+    protected function formatTagListHtml($bookmark)
+    {
+        return $this->formatTagList($bookmark);
+    }
+
+    /**
+     * Format TagString
+     *
+     * @param Bookmark $bookmark instance
+     *
+     * @return string formatted TagString
+     */
+    protected function formatTagString($bookmark)
+    {
+        return implode($this->conf->get('general.tags_separator', ' '), $this->formatTagList($bookmark));
+    }
+
+    /**
+     * Format TagString
+     *
+     * @param Bookmark $bookmark instance
+     *
+     * @return string formatted TagString
+     */
+    protected function formatTagStringUrlEncoded($bookmark)
+    {
+        return implode(' ', $this->formatTagListUrlEncoded($bookmark));
+    }
+
+    /**
+     * Format Class
+     * Used to add specific CSS class for a link
+     *
+     * @param Bookmark $bookmark instance
+     *
+     * @return string formatted Class
+     */
+    protected function formatClass($bookmark)
+    {
+        return $bookmark->isPrivate() ? 'private' : '';
+    }
+
+    /**
+     * Format Created
+     *
+     * @param Bookmark $bookmark instance
+     *
+     * @return DateTimeInterface instance
+     */
+    protected function formatCreated(Bookmark $bookmark)
+    {
+        return $bookmark->getCreated();
+    }
+
+    /**
+     * Format Updated
+     *
+     * @param Bookmark $bookmark instance
+     *
+     * @return DateTimeInterface instance
+     */
+    protected function formatUpdated(Bookmark $bookmark)
+    {
+        return $bookmark->getUpdated();
+    }
+
+    /**
+     * Format CreatedTimestamp
+     *
+     * @param Bookmark $bookmark instance
+     *
+     * @return int formatted CreatedTimestamp
+     */
+    protected function formatCreatedTimestamp(Bookmark $bookmark)
+    {
+        if (! empty($bookmark->getCreated())) {
+            return $bookmark->getCreated()->getTimestamp();
+        }
+        return 0;
+    }
+
+    /**
+     * Format UpdatedTimestamp
+     *
+     * @param Bookmark $bookmark instance
+     *
+     * @return int formatted UpdatedTimestamp
+     */
+    protected function formatUpdatedTimestamp(Bookmark $bookmark)
+    {
+        if (! empty($bookmark->getUpdated())) {
+            return $bookmark->getUpdated()->getTimestamp();
+        }
+        return 0;
+    }
+
+    /**
+     * Format bookmark's additional content
+     *
+     * @param Bookmark $bookmark instance
+     *
+     * @return mixed[]
+     */
+    protected function formatAdditionalContent(Bookmark $bookmark): array
+    {
+        return $bookmark->getAdditionalContent();
+    }
+
+    /**
+     * Format tag list, e.g. remove private tags if the user is not logged in.
+     * TODO: this method is called multiple time to format tags, the result should be cached.
+     *
+     * @param array $tags
+     *
+     * @return array
+     */
+    protected function filterTagList(array $tags): array
+    {
+        if ($this->isLoggedIn === true) {
+            return $tags;
+        }
+
+        $out = [];
+        foreach ($tags as $tag) {
+            if (strpos($tag, '.') === 0) {
+                continue;
+            }
+
+            $out[] = $tag;
+        }
+
+        return $out;
+    }
+}

application/formatter/BookmarkMarkdownExtraFormatter.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Shaarli\Formatter;
+
+use Shaarli\Config\ConfigManager;
+use Shaarli\Formatter\Parsedown\ShaarliParsedownExtra;
+
+/**
+ * Class BookmarkMarkdownExtraFormatter
+ *
+ * Format bookmark description into MarkdownExtra format.
+ *
+ * @see https://michelf.ca/projects/php-markdown/extra/
+ *
+ * @package Shaarli\Formatter
+ */
+class BookmarkMarkdownExtraFormatter extends BookmarkMarkdownFormatter
+{
+    public function __construct(ConfigManager $conf, bool $isLoggedIn)
+    {
+        parent::__construct($conf, $isLoggedIn);
+        $this->parsedown = new ShaarliParsedownExtra();
+    }
+}

application/formatter/BookmarkMarkdownFormatter.php

@@ -0,0 +1,221 @@
+<?php
+
+namespace Shaarli\Formatter;
+
+use Shaarli\Config\ConfigManager;
+use Shaarli\Formatter\Parsedown\ShaarliParsedown;
+
+/**
+ * Class BookmarkMarkdownFormatter
+ *
+ * Format bookmark description into Markdown format.
+ *
+ * @package Shaarli\Formatter
+ */
+class BookmarkMarkdownFormatter extends BookmarkDefaultFormatter
+{
+    /**
+     * When this tag is present in a bookmark, its description should not be processed with Markdown
+     */
+    public const NO_MD_TAG = 'nomarkdown';
+
+    /** @var \Parsedown instance */
+    protected $parsedown;
+
+    /** @var bool used to escape HTML in Markdown or not.
+     *            It MUST be set to true for shared instance as HTML content can
+     *            introduce XSS vulnerabilities.
+     */
+    protected $escape;
+
+    /**
+     * @var array List of allowed protocols for links inside bookmark's description.
+     */
+    protected $allowedProtocols;
+
+    /**
+     * LinkMarkdownFormatter constructor.
+     *
+     * @param ConfigManager $conf instance
+     * @param bool          $isLoggedIn
+     */
+    public function __construct(ConfigManager $conf, bool $isLoggedIn)
+    {
+        parent::__construct($conf, $isLoggedIn);
+
+        $this->parsedown = new ShaarliParsedown();
+        $this->escape = $conf->get('security.markdown_escape', true);
+        $this->allowedProtocols = $conf->get('security.allowed_protocols', []);
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function formatDescription($bookmark)
+    {
+        if (in_array(self::NO_MD_TAG, $bookmark->getTags())) {
+            return parent::formatDescription($bookmark);
+        }
+
+        $processedDescription = $this->tokenizeSearchHighlightField(
+            $bookmark->getDescription() ?? '',
+            $bookmark->getAdditionalContentEntry('search_highlight')['description'] ?? []
+        );
+        $processedDescription = $this->filterProtocols($processedDescription);
+        $processedDescription = $this->formatHashTags($processedDescription);
+        $processedDescription = $this->reverseEscapedHtml($processedDescription);
+        $processedDescription = $this->parsedown
+            ->setMarkupEscaped($this->escape)
+            ->setBreaksEnabled(true)
+            ->text($processedDescription);
+        $processedDescription = $this->sanitizeHtml($processedDescription);
+        $processedDescription = $this->replaceTokens($processedDescription);
+
+        if (!empty($processedDescription)) {
+            $processedDescription = '<div class="markdown">' . $processedDescription . '</div>';
+        }
+
+        return $processedDescription;
+    }
+
+    /**
+     * Remove the NO markdown tag if it is present
+     *
+     * @inheritdoc
+     */
+    protected function formatTagList($bookmark)
+    {
+        $out = parent::formatTagList($bookmark);
+        if ($this->isLoggedIn === false && ($pos = array_search(self::NO_MD_TAG, $out)) !== false) {
+            unset($out[$pos]);
+            return array_values($out);
+        }
+        return $out;
+    }
+
+    /**
+     * Replace not whitelisted protocols with http:// in given description.
+     * Also adds `index_url` to relative links if it's specified
+     *
+     * @param string $description      input description text.
+     *
+     * @return string $description without malicious link.
+     */
+    protected function filterProtocols($description)
+    {
+        $allowedProtocols = $this->allowedProtocols;
+        $indexUrl = ! empty($this->contextData['index_url']) ? $this->contextData['index_url'] : '';
+
+        return preg_replace_callback(
+            '#]\((.*?)\)#is',
+            function ($match) use ($allowedProtocols, $indexUrl) {
+                $link = startsWith($match[1], '?') || startsWith($match[1], '/') ? $indexUrl : '';
+                $link .= whitelist_protocols($match[1], $allowedProtocols);
+                return '](' . $link . ')';
+            },
+            $description
+        );
+    }
+
+    /**
+     * Replace hashtag in Markdown links format
+     * E.g. `#hashtag` becomes `[#hashtag](./add-tag/hashtag)`
+     * It includes the index URL if specified.
+     *
+     * @param string $description
+     *
+     * @return string
+     */
+    protected function formatHashTags($description)
+    {
+        $indexUrl = ! empty($this->contextData['index_url']) ? $this->contextData['index_url'] : '';
+        $tokens = '(?:' . BookmarkDefaultFormatter::SEARCH_HIGHLIGHT_OPEN . ')' .
+            '(?:' . BookmarkDefaultFormatter::SEARCH_HIGHLIGHT_CLOSE . ')'
+        ;
+
+        /*
+         * To support unicode: http://stackoverflow.com/a/35498078/1484919
+         * \p{Pc} - to match underscore
+         * \p{N} - numeric character in any script
+         * \p{L} - letter from any language
+         * \p{Mn} - any non marking space (accents, umlauts, etc)
+         */
+        $regex = '/(^|\s)#([\p{Pc}\p{N}\p{L}\p{Mn}' . $tokens . ']+)/mui';
+        $replacement = function (array $match) use ($indexUrl): string {
+            $cleanMatch = str_replace(
+                BookmarkDefaultFormatter::SEARCH_HIGHLIGHT_OPEN,
+                '',
+                str_replace(BookmarkDefaultFormatter::SEARCH_HIGHLIGHT_CLOSE, '', $match[2])
+            );
+            return $match[1] . '[#' . $match[2] . '](' . $indexUrl . './add-tag/' . $cleanMatch . ')';
+        };
+
+        $descriptionLines = explode(PHP_EOL, $description);
+        $descriptionOut = '';
+        $codeBlockOn = false;
+        $lineCount = 0;
+
+        foreach ($descriptionLines as $descriptionLine) {
+            // Detect line of code: starting with 4 spaces,
+            // except lists which can start with +/*/- or `2.` after spaces.
+            $codeLineOn = preg_match('/^    +(?=[^\+\*\-])(?=(?!\d\.).)/', $descriptionLine) > 0;
+            // Detect and toggle block of code
+            if (!$codeBlockOn) {
+                $codeBlockOn = preg_match('/^```/', $descriptionLine) > 0;
+            } elseif (preg_match('/^```/', $descriptionLine) > 0) {
+                $codeBlockOn = false;
+            }
+
+            if (!$codeBlockOn && !$codeLineOn) {
+                $descriptionLine = preg_replace_callback($regex, $replacement, $descriptionLine);
+            }
+
+            $descriptionOut .= $descriptionLine;
+            if ($lineCount++ < count($descriptionLines) - 1) {
+                $descriptionOut .= PHP_EOL;
+            }
+        }
+
+        return $descriptionOut;
+    }
+
+    /**
+     * Remove dangerous HTML tags (tags, iframe, etc.).
+     * Doesn't affect <code> content (already escaped by Parsedown).
+     *
+     * @param string $description input description text.
+     *
+     * @return string given string escaped.
+     */
+    protected function sanitizeHtml($description)
+    {
+        $escapeTags = [
+            'script',
+            'style',
+            'link',
+            'iframe',
+            'frameset',
+            'frame',
+        ];
+        foreach ($escapeTags as $tag) {
+            $description = preg_replace_callback(
+                '#<\s*' . $tag . '[^>]*>(.*</\s*' . $tag . '[^>]*>)?#is',
+                function ($match) {
+                    return escape($match[0]);
+                },
+                $description
+            );
+        }
+        $description = preg_replace(
+            '#(<[^>]+\s)on[a-z]*="?[^ "]*"?#is',
+            '$1',
+            $description
+        );
+        return $description;
+    }
+
+    protected function reverseEscapedHtml($description)
+    {
+        return unescape($description);
+    }
+}

application/formatter/BookmarkRawFormatter.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Shaarli\Formatter;
+
+/**
+ * Class BookmarkRawFormatter
+ *
+ * Used to retrieve bookmarks as array with raw values.
+ * Warning: Do NOT use this for HTML content as it can introduce XSS vulnerabilities.
+ *
+ * @package Shaarli\Formatter
+ */
+class BookmarkRawFormatter extends BookmarkFormatter
+{
+}

application/formatter/FormatterFactory.php

@@ -0,0 +1,51 @@
+<?php
+
+namespace Shaarli\Formatter;
+
+use Shaarli\Config\ConfigManager;
+
+/**
+ * Class FormatterFactory
+ *
+ * Helper class used to instantiate the proper BookmarkFormatter.
+ *
+ * @package Shaarli\Formatter
+ */
+class FormatterFactory
+{
+    /** @var ConfigManager instance */
+    protected $conf;
+
+    /** @var bool */
+    protected $isLoggedIn;
+
+    /**
+     * FormatterFactory constructor.
+     *
+     * @param ConfigManager $conf
+     * @param bool          $isLoggedIn
+     */
+    public function __construct(ConfigManager $conf, bool $isLoggedIn)
+    {
+        $this->conf = $conf;
+        $this->isLoggedIn = $isLoggedIn;
+    }
+
+    /**
+     * Instanciate a BookmarkFormatter depending on the configuration or provided formatter type.
+     *
+     * @param string|null $type force a specific type regardless of the configuration
+     *
+     * @return BookmarkFormatter instance.
+     */
+    public function getFormatter(string $type = null): BookmarkFormatter
+    {
+        $type = $type ? $type : $this->conf->get('formatter', 'default');
+        $className = '\\Shaarli\\Formatter\\Bookmark' . ucfirst($type) . 'Formatter';
+        if (!class_exists($className)) {
+            $className = '\\Shaarli\\Formatter\\BookmarkDefaultFormatter';
+        }
+
+        return new $className($this->conf, $this->isLoggedIn);
+    }
+}

application/formatter/Parsedown/ShaarliParsedown.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Formatter\Parsedown;
+
+/**
+ * Parsedown extension for Shaarli.
+ *
+ * Extension for both Parsedown and ParsedownExtra centralized in ShaarliParsedownTrait.
+ */
+class ShaarliParsedown extends \Parsedown
+{
+    use ShaarliParsedownTrait;
+}

application/formatter/Parsedown/ShaarliParsedownExtra.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Formatter\Parsedown;
+
+/**
+ * ParsedownExtra extension for Shaarli.
+ *
+ * Extension for both Parsedown and ParsedownExtra centralized in ShaarliParsedownTrait.
+ */
+class ShaarliParsedownExtra extends \ParsedownExtra
+{
+    use ShaarliParsedownTrait;
+}

application/formatter/Parsedown/ShaarliParsedownTrait.php

@@ -0,0 +1,81 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Formatter\Parsedown;
+
+use Shaarli\Formatter\BookmarkDefaultFormatter as Formatter;
+
+/**
+ * Trait used for Parsedown and ParsedownExtra extension.
+ *
+ * Extended:
+ *   - Format links properly in search context
+ */
+trait ShaarliParsedownTrait
+{
+    /**
+     * @inheritDoc
+     */
+    protected function inlineLink($excerpt)
+    {
+        return $this->shaarliFormatLink(parent::inlineLink($excerpt), true);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    protected function inlineUrl($excerpt)
+    {
+        return $this->shaarliFormatLink(parent::inlineUrl($excerpt), false);
+    }
+
+    /**
+     * Properly format markdown link:
+     *   - remove highlight tags from HREF attribute
+     *   - (optional) add highlight tags to link caption
+     *
+     * @param array|null $link     Parsedown formatted link array.
+     *                             It can be empty.
+     * @param bool       $fullWrap Add highlight tags the whole link caption
+     *
+     * @return array|null
+     */
+    protected function shaarliFormatLink(?array $link, bool $fullWrap): ?array
+    {
+        // If open and clean search tokens are found in the link, process.
+        if (
+            is_array($link)
+            && strpos($link['element']['attributes']['href'] ?? '', Formatter::SEARCH_HIGHLIGHT_OPEN) !== false
+            && strpos($link['element']['attributes']['href'] ?? '', Formatter::SEARCH_HIGHLIGHT_CLOSE) !== false
+        ) {
+            $link['element']['attributes']['href'] = $this->shaarliRemoveSearchTokens(
+                $link['element']['attributes']['href']
+            );
+
+            if ($fullWrap) {
+                $link['element']['text'] = Formatter::SEARCH_HIGHLIGHT_OPEN .
+                    $link['element']['text'] .
+                    Formatter::SEARCH_HIGHLIGHT_CLOSE
+                ;
+            }
+        }
+
+        return $link;
+    }
+
+    /**
+     * Remove open and close tags from provided string.
+     *
+     * @param string $entry input
+     *
+     * @return string Striped input
+     */
+    protected function shaarliRemoveSearchTokens(string $entry): string
+    {
+        $entry = str_replace(Formatter::SEARCH_HIGHLIGHT_OPEN, '', $entry);
+        $entry = str_replace(Formatter::SEARCH_HIGHLIGHT_CLOSE, '', $entry);
+
+        return $entry;
+    }
+}

application/front/ShaarliAdminMiddleware.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace Shaarli\Front;
+
+use Slim\Http\Request;
+use Slim\Http\Response;
+
+/**
+ * Middleware used for controller requiring to be authenticated.
+ * It extends ShaarliMiddleware, and just make sure that the user is authenticated.
+ * Otherwise, it redirects to the login page.
+ */
+class ShaarliAdminMiddleware extends ShaarliMiddleware
+{
+    public function __invoke(Request $request, Response $response, callable $next): Response
+    {
+        $this->initBasePath($request);
+
+        if (true !== $this->container->loginManager->isLoggedIn()) {
+            $returnUrl = urlencode($this->container->environment['REQUEST_URI']);
+
+            return $response->withRedirect($this->container->basePath . '/login?returnurl=' . $returnUrl);
+        }
+
+        return parent::__invoke($request, $response, $next);
+    }
+}

application/front/ShaarliMiddleware.php

@@ -0,0 +1,116 @@
+<?php
+
+namespace Shaarli\Front;
+
+use Shaarli\Container\ShaarliContainer;
+use Shaarli\Front\Exception\UnauthorizedException;
+use Slim\Http\Request;
+use Slim\Http\Response;
+
+/**
+ * Class ShaarliMiddleware
+ *
+ * This will be called before accessing any Shaarli controller.
+ */
+class ShaarliMiddleware
+{
+    /** @var ShaarliContainer contains all Shaarli DI */
+    protected $container;
+
+    public function __construct(ShaarliContainer $container)
+    {
+        $this->container = $container;
+    }
+
+    /**
+     * Middleware execution:
+     *   - run updates
+     *   - if not logged in open shaarli, redirect to login
+     *   - execute the controller
+     *   - return the response
+     *
+     * In case of error, the error template will be displayed with the exception message.
+     *
+     * @param  Request  $request  Slim request
+     * @param  Response $response Slim response
+     * @param  callable $next     Next action
+     *
+     * @return Response response.
+     */
+    public function __invoke(Request $request, Response $response, callable $next): Response
+    {
+        $this->initBasePath($request);
+
+        try {
+            if (
+                !is_file($this->container->conf->getConfigFileExt())
+                && !in_array($next->getName(), ['displayInstall', 'saveInstall'], true)
+            ) {
+                return $response->withRedirect($this->container->basePath . '/install');
+            }
+
+            $this->runUpdates();
+            $this->checkOpenShaarli($request, $response, $next);
+
+            return $next($request, $response);
+        } catch (UnauthorizedException $e) {
+            $returnUrl = urlencode($this->container->environment['REQUEST_URI']);
+
+            return $response->withRedirect($this->container->basePath . '/login?returnurl=' . $returnUrl);
+        }
+        // Other exceptions are handled by ErrorController
+    }
+
+    /**
+     * Run the updater for every requests processed while logged in.
+     */
+    protected function runUpdates(): void
+    {
+        if ($this->container->loginManager->isLoggedIn() !== true) {
+            return;
+        }
+
+        $this->container->updater->setBasePath($this->container->basePath);
+        $newUpdates = $this->container->updater->update();
+        if (!empty($newUpdates)) {
+            $this->container->updater->writeUpdates(
+                $this->container->conf->get('resource.updates'),
+                $this->container->updater->getDoneUpdates()
+            );
+
+            $this->container->pageCacheManager->invalidateCaches();
+        }
+    }
+
+    /**
+     * Access is denied to most pages with `hide_public_links` + `force_login` settings.
+     */
+    protected function checkOpenShaarli(Request $request, Response $response, callable $next): bool
+    {
+        if (
+// if the user isn't logged in
+            !$this->container->loginManager->isLoggedIn()
+            // and Shaarli doesn't have public content...
+            && $this->container->conf->get('privacy.hide_public_links')
+            // and is configured to enforce the login
+            && $this->container->conf->get('privacy.force_login')
+            // and the current page isn't already the login page
+            // and the user is not requesting a feed (which would lead to a different content-type as expected)
+            && !in_array($next->getName(), ['login', 'processLogin', 'atom', 'rss'], true)
+        ) {
+            throw new UnauthorizedException();
+        }
+
+        return true;
+    }
+
+    /**
+     * Initialize the URL base path if it hasn't been defined yet.
+     */
+    protected function initBasePath(Request $request): void
+    {
+        if (null === $this->container->basePath) {
+            $this->container->basePath = rtrim($request->getUri()->getBasePath(), '/');
+        }
+    }
+}

application/front/controller/admin/ConfigureController.php

@@ -0,0 +1,132 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Front\Controller\Admin;
+
+use Shaarli\Languages;
+use Shaarli\Render\TemplatePage;
+use Shaarli\Render\ThemeUtils;
+use Shaarli\Thumbnailer;
+use Slim\Http\Request;
+use Slim\Http\Response;
+use Throwable;
+
+/**
+ * Class ConfigureController
+ *
+ * Slim controller used to handle Shaarli configuration page (display + save new config).
+ */
+class ConfigureController extends ShaarliAdminController
+{
+    /**
+     * GET /admin/configure - Displays the configuration page
+     */
+    public function index(Request $request, Response $response): Response
+    {
+        $this->assignView('title', $this->container->conf->get('general.title', 'Shaarli'));
+        $this->assignView('theme', $this->container->conf->get('resource.theme'));
+        $this->assignView(
+            'theme_available',
+            ThemeUtils::getThemes($this->container->conf->get('resource.raintpl_tpl'))
+        );
+        $this->assignView('formatter_available', ['default', 'markdown', 'markdownExtra']);
+        list($continents, $cities) = generateTimeZoneData(
+            timezone_identifiers_list(),
+            $this->container->conf->get('general.timezone')
+        );
+        $this->assignView('continents', $continents);
+        $this->assignView('cities', $cities);
+        $this->assignView('retrieve_description', $this->container->conf->get('general.retrieve_description', false));
+        $this->assignView('private_links_default', $this->container->conf->get('privacy.default_private_links', false));
+        $this->assignView(
+            'session_protection_disabled',
+            $this->container->conf->get('security.session_protection_disabled', false)
+        );
+        $this->assignView('enable_rss_permalinks', $this->container->conf->get('feed.rss_permalinks', false));
+        $this->assignView('enable_update_check', $this->container->conf->get('updates.check_updates', true));
+        $this->assignView('hide_public_links', $this->container->conf->get('privacy.hide_public_links', false));
+        $this->assignView('api_enabled', $this->container->conf->get('api.enabled', true));
+        $this->assignView('api_secret', $this->container->conf->get('api.secret'));
+        $this->assignView('languages', Languages::getAvailableLanguages());
+        $this->assignView('gd_enabled', extension_loaded('gd'));
+        $this->assignView('thumbnails_mode', $this->container->conf->get('thumbnails.mode', Thumbnailer::MODE_NONE));
+        $this->assignView(
+            'pagetitle',
+            t('Configure') . ' - ' . $this->container->conf->get('general.title', 'Shaarli')
+        );
+
+        return $response->write($this->render(TemplatePage::CONFIGURE));
+    }
+
+    /**
+     * POST /admin/configure - Update Shaarli's configuration
+     */
+    public function save(Request $request, Response $response): Response
+    {
+        $this->checkToken($request);
+
+        $continent = $request->getParam('continent');
+        $city = $request->getParam('city');
+        $tz = 'UTC';
+        if (null !== $continent && null !== $city && isTimeZoneValid($continent, $city)) {
+            $tz = $continent . '/' . $city;
+        }
+
+        $this->container->conf->set('general.timezone', $tz);
+        $this->container->conf->set('general.title', escape($request->getParam('title')));
+        $this->container->conf->set('general.header_link', escape($request->getParam('titleLink')));
+        $this->container->conf->set('general.retrieve_description', !empty($request->getParam('retrieveDescription')));
+        $this->container->conf->set('resource.theme', escape($request->getParam('theme')));
+        $this->container->conf->set(
+            'security.session_protection_disabled',
+            !empty($request->getParam('disablesessionprotection'))
+        );
+        $this->container->conf->set(
+            'privacy.default_private_links',
+            !empty($request->getParam('privateLinkByDefault'))
+        );
+        $this->container->conf->set('feed.rss_permalinks', !empty($request->getParam('enableRssPermalinks')));
+        $this->container->conf->set('updates.check_updates', !empty($request->getParam('updateCheck')));
+        $this->container->conf->set('privacy.hide_public_links', !empty($request->getParam('hidePublicLinks')));
+        $this->container->conf->set('api.enabled', !empty($request->getParam('enableApi')));
+        $this->container->conf->set('api.secret', escape($request->getParam('apiSecret')));
+        $this->container->conf->set('formatter', escape($request->getParam('formatter')));
+
+        if (!empty($request->getParam('language'))) {
+            $this->container->conf->set('translation.language', escape($request->getParam('language')));
+        }
+
+        $thumbnailsMode = extension_loaded('gd') ? $request->getParam('enableThumbnails') : Thumbnailer::MODE_NONE;
+        if (
+            $thumbnailsMode !== Thumbnailer::MODE_NONE
+            && $thumbnailsMode !== $this->container->conf->get('thumbnails.mode', Thumbnailer::MODE_NONE)
+        ) {
+            $this->saveWarningMessage(
+                t('You have enabled or changed thumbnails mode.') .
+                '<a href="' . $this->container->basePath . '/admin/thumbnails">' .
+                    t('Please synchronize them.') .
+                '</a>'
+            );
+        }
+        $this->container->conf->set('thumbnails.mode', $thumbnailsMode);
+
+        try {
+            $this->container->conf->write($this->container->loginManager->isLoggedIn());
+            $this->container->history->updateSettings();
+            $this->container->pageCacheManager->invalidateCaches();
+        } catch (Throwable $e) {
+            $this->assignView('message', t('Error while writing config file after configuration update.'));
+
+            if ($this->container->conf->get('dev.debug', false)) {
+                $this->assignView('stacktrace', $e->getMessage() . PHP_EOL . $e->getTraceAsString());
+            }
+
+            return $response->write($this->render('error'));
+        }
+
+        $this->saveSuccessMessage(t('Configuration was saved.'));
+
+        return $this->redirect($response, '/admin/configure');
+    }
+}

application/front/controller/admin/ExportController.php

@@ -0,0 +1,80 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Front\Controller\Admin;
+
+use DateTime;
+use Shaarli\Bookmark\Bookmark;
+use Shaarli\Render\TemplatePage;
+use Slim\Http\Request;
+use Slim\Http\Response;
+
+/**
+ * Class ExportController
+ *
+ * Slim controller used to display Shaarli data export page,
+ * and process the bookmarks export as a Netscape Bookmarks file.
+ */
+class ExportController extends ShaarliAdminController
+{
+    /**
+     * GET /admin/export - Display export page
+     */
+    public function index(Request $request, Response $response): Response
+    {
+        $this->assignView('pagetitle', t('Export') . ' - ' . $this->container->conf->get('general.title', 'Shaarli'));
+
+        return $response->write($this->render(TemplatePage::EXPORT));
+    }
+
+    /**
+     * POST /admin/export - Process export, and serve download file named
+     *                      bookmarks_(all|private|public)_datetime.html
+     */
+    public function export(Request $request, Response $response): Response
+    {
+        $this->checkToken($request);
+
+        $selection = $request->getParam('selection');
+
+        if (empty($selection)) {
+            $this->saveErrorMessage(t('Please select an export mode.'));
+
+            return $this->redirect($response, '/admin/export');
+        }
+
+        $prependNoteUrl = filter_var($request->getParam('prepend_note_url') ?? false, FILTER_VALIDATE_BOOLEAN);
+
+        try {
+            $formatter = $this->container->formatterFactory->getFormatter('raw');
+
+            $this->assignView(
+                'links',
+                $this->container->netscapeBookmarkUtils->filterAndFormat(
+                    $formatter,
+                    $selection,
+                    $prependNoteUrl,
+                    index_url($this->container->environment)
+                )
+            );
+        } catch (\Exception $exc) {
+            $this->saveErrorMessage($exc->getMessage());
+
+            return $this->redirect($response, '/admin/export');
+        }
+
+        $now = new DateTime();
+        $response = $response->withHeader('Content-Type', 'text/html; charset=utf-8');
+        $response = $response->withHeader(
+            'Content-disposition',
+            'attachment; filename=bookmarks_' . $selection . '_' . $now->format(Bookmark::LINK_DATE_FORMAT) . '.html'
+        );
+
+        $this->assignView('date', $now->format(DateTime::RFC822));
+        $this->assignView('eol', PHP_EOL);
+        $this->assignView('selection', $selection);
+
+        return $response->write($this->render(TemplatePage::NETSCAPE_EXPORT_BOOKMARKS));
+    }
+}

application/front/controller/admin/ImportController.php

@@ -0,0 +1,82 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Front\Controller\Admin;
+
+use Psr\Http\Message\UploadedFileInterface;
+use Shaarli\Render\TemplatePage;
+use Slim\Http\Request;
+use Slim\Http\Response;
+
+/**
+ * Class ImportController
+ *
+ * Slim controller used to display Shaarli data import page,
+ * and import bookmarks from Netscape Bookmarks file.
+ */
+class ImportController extends ShaarliAdminController
+{
+    /**
+     * GET /admin/import - Display import page
+     */
+    public function index(Request $request, Response $response): Response
+    {
+        $this->assignView(
+            'maxfilesize',
+            get_max_upload_size(
+                ini_get('post_max_size'),
+                ini_get('upload_max_filesize'),
+                false
+            )
+        );
+        $this->assignView(
+            'maxfilesizeHuman',
+            get_max_upload_size(
+                ini_get('post_max_size'),
+                ini_get('upload_max_filesize'),
+                true
+            )
+        );
+        $this->assignView('pagetitle', t('Import') . ' - ' . $this->container->conf->get('general.title', 'Shaarli'));
+
+        return $response->write($this->render(TemplatePage::IMPORT));
+    }
+
+    /**
+     * POST /admin/import - Process import file provided and create bookmarks
+     */
+    public function import(Request $request, Response $response): Response
+    {
+        $this->checkToken($request);
+
+        $file = ($request->getUploadedFiles() ?? [])['filetoupload'] ?? null;
+        if (!$file instanceof UploadedFileInterface) {
+            $this->saveErrorMessage(t('No import file provided.'));
+
+            return $this->redirect($response, '/admin/import');
+        }
+
+
+        // Import bookmarks from an uploaded file
+        if (0 === $file->getSize()) {
+            // The file is too big or some form field may be missing.
+            $msg = sprintf(
+                t(
+                    'The file you are trying to upload is probably bigger than what this webserver can accept'
+                    . ' (%s). Please upload in smaller chunks.'
+                ),
+                get_max_upload_size(ini_get('post_max_size'), ini_get('upload_max_filesize'))
+            );
+            $this->saveErrorMessage($msg);
+
+            return $this->redirect($response, '/admin/import');
+        }
+
+        $status = $this->container->netscapeBookmarkUtils->import($request->getParams(), $file);
+
+        $this->saveSuccessMessage($status);
+
+        return $this->redirect($response, '/admin/import');
+    }
+}

application/front/controller/admin/LogoutController.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Front\Controller\Admin;
+
+use Shaarli\Security\CookieManager;
+use Shaarli\Security\LoginManager;
+use Slim\Http\Request;
+use Slim\Http\Response;
+
+/**
+ * Class LogoutController
+ *
+ * Slim controller used to logout the user.
+ * It invalidates page cache and terminate the user session. Then it redirects to the homepage.
+ */
+class LogoutController extends ShaarliAdminController
+{
+    public function index(Request $request, Response $response): Response
+    {
+        $this->container->pageCacheManager->invalidateCaches();
+        $this->container->sessionManager->logout();
+        $this->container->cookieManager->setCookieParameter(
+            CookieManager::STAY_SIGNED_IN,
+            'false',
+            0,
+            $this->container->basePath . '/'
+        );
+
+        return $this->redirect($response, '/');
+    }
+}

application/front/controller/admin/ManageTagController.php

@@ -0,0 +1,124 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Front\Controller\Admin;
+
+use Shaarli\Bookmark\BookmarkFilter;
+use Shaarli\Render\TemplatePage;
+use Slim\Http\Request;
+use Slim\Http\Response;
+
+/**
+ * Class ManageTagController
+ *
+ * Slim controller used to handle Shaarli manage tags page (rename and delete tags).
+ */
+class ManageTagController extends ShaarliAdminController
+{
+    /**
+     * GET /admin/tags - Displays the manage tags page
+     */
+    public function index(Request $request, Response $response): Response
+    {
+        $fromTag = $request->getParam('fromtag') ?? '';
+
+        $this->assignView('fromtag', escape($fromTag));
+        $separator = escape($this->container->conf->get('general.tags_separator', ' '));
+        if ($separator === ' ') {
+            $separator = '&nbsp;';
+            $this->assignView('tags_separator_desc', t('whitespace'));
+        }
+        $this->assignView('tags_separator', $separator);
+        $this->assignView(
+            'pagetitle',
+            t('Manage tags') . ' - ' . $this->container->conf->get('general.title', 'Shaarli')
+        );
+
+        return $response->write($this->render(TemplatePage::CHANGE_TAG));
+    }
+
+    /**
+     * POST /admin/tags - Update or delete provided tag
+     */
+    public function save(Request $request, Response $response): Response
+    {
+        $this->checkToken($request);
+
+        $isDelete = null !== $request->getParam('deletetag') && null === $request->getParam('renametag');
+
+        $fromTag = trim($request->getParam('fromtag') ?? '');
+        $toTag = trim($request->getParam('totag') ?? '');
+
+        if (0 === strlen($fromTag) || false === $isDelete && 0 === strlen($toTag)) {
+            $this->saveWarningMessage(t('Invalid tags provided.'));
+
+            return $this->redirect($response, '/admin/tags');
+        }
+
+        // TODO: move this to bookmark service
+        $searchResult = $this->container->bookmarkService->search(
+            ['searchtags' => $fromTag],
+            BookmarkFilter::$ALL,
+            true
+        );
+        foreach ($searchResult->getBookmarks() as $bookmark) {
+            if (false === $isDelete) {
+                $bookmark->renameTag($fromTag, $toTag);
+            } else {
+                $bookmark->deleteTag($fromTag);
+            }
+
+            $this->container->bookmarkService->set($bookmark, false);
+            $this->container->history->updateLink($bookmark);
+        }
+
+        $this->container->bookmarkService->save();
+
+        $count = $searchResult->getResultCount();
+        if (true === $isDelete) {
+            $alert = sprintf(
+                t('The tag was removed from %d bookmark.', 'The tag was removed from %d bookmarks.', $count),
+                $count
+            );
+        } else {
+            $alert = sprintf(
+                t('The tag was renamed in %d bookmark.', 'The tag was renamed in %d bookmarks.', $count),
+                $count
+            );
+        }
+
+        $this->saveSuccessMessage($alert);
+
+        $redirect = true === $isDelete ? '/admin/tags' : '/?searchtags=' . urlencode($toTag);
+
+        return $this->redirect($response, $redirect);
+    }
+
+    /**
+     * POST /admin/tags/change-separator - Change tag separator
+     */
+    public function changeSeparator(Request $request, Response $response): Response
+    {
+        $this->checkToken($request);
+
+        $reservedCharacters = ['-', '.', '*'];
+        $newSeparator = $request->getParam('separator');
+        if ($newSeparator === null || mb_strlen($newSeparator) !== 1) {
+            $this->saveErrorMessage(t('Tags separator must be a single character.'));
+        } elseif (in_array($newSeparator, $reservedCharacters, true)) {
+            $reservedCharacters = implode(' ', array_map(function (string $character) {
+                return '<code>' . $character . '</code>';
+            }, $reservedCharacters));
+            $this->saveErrorMessage(
+                t('These characters are reserved and can\'t be used as tags separator: ') . $reservedCharacters
+            );
+        } else {
+            $this->container->conf->set('general.tags_separator', $newSeparator, true, true);
+
+            $this->saveSuccessMessage('Your tags separator setting has been updated!');
+        }
+
+        return $this->redirect($response, '/admin/tags');
+    }
+}

application/front/controller/admin/MetadataController.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Front\Controller\Admin;
+
+use Slim\Http\Request;
+use Slim\Http\Response;
+
+/**
+ * Controller used to retrieve/update bookmark's metadata.
+ */
+class MetadataController extends ShaarliAdminController
+{
+    /**
+     * GET /admin/metadata/{url} - Attempt to retrieve the bookmark title from provided URL.
+     */
+    public function ajaxRetrieveTitle(Request $request, Response $response): Response
+    {
+        $url = $request->getParam('url');
+
+        // Only try to extract metadata from URL with HTTP(s) scheme
+        if (!empty($url) && strpos(get_url_scheme($url) ?: '', 'http') !== false) {
+            return $response->withJson($this->container->metadataRetriever->retrieve($url));
+        }
+
+        return $response->withJson([]);
+    }
+}

application/front/controller/admin/PasswordController.php

@@ -0,0 +1,101 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Front\Controller\Admin;
+
+use Shaarli\Container\ShaarliContainer;
+use Shaarli\Front\Exception\OpenShaarliPasswordException;
+use Shaarli\Front\Exception\ShaarliFrontException;
+use Shaarli\Render\TemplatePage;
+use Slim\Http\Request;
+use Slim\Http\Response;
+use Throwable;
+
+/**
+ * Class PasswordController
+ *
+ * Slim controller used to handle passwords update.
+ */
+class PasswordController extends ShaarliAdminController
+{
+    public function __construct(ShaarliContainer $container)
+    {
+        parent::__construct($container);
+
+        $this->assignView(
+            'pagetitle',
+            t('Change password') . ' - ' . $this->container->conf->get('general.title', 'Shaarli')
+        );
+    }
+
+    /**
+     * GET /admin/password - Displays the change password template
+     */
+    public function index(Request $request, Response $response): Response
+    {
+        return $response->write($this->render(TemplatePage::CHANGE_PASSWORD));
+    }
+
+    /**
+     * POST /admin/password - Change admin password - existing and new passwords need to be provided.
+     */
+    public function change(Request $request, Response $response): Response
+    {
+        $this->checkToken($request);
+
+        if ($this->container->conf->get('security.open_shaarli', false)) {
+            throw new OpenShaarliPasswordException();
+        }
+
+        $oldPassword = $request->getParam('oldpassword');
+        $newPassword = $request->getParam('setpassword');
+
+        if (empty($newPassword) || empty($oldPassword)) {
+            $this->saveErrorMessage(t('You must provide the current and new password to change it.'));
+
+            return $response
+                ->withStatus(400)
+                ->write($this->render(TemplatePage::CHANGE_PASSWORD))
+            ;
+        }
+
+        // Make sure old password is correct.
+        $oldHash = sha1(
+            $oldPassword .
+            $this->container->conf->get('credentials.login') .
+            $this->container->conf->get('credentials.salt')
+        );
+
+        if ($oldHash !== $this->container->conf->get('credentials.hash')) {
+            $this->saveErrorMessage(t('The old password is not correct.'));
+
+            return $response
+                ->withStatus(400)
+                ->write($this->render(TemplatePage::CHANGE_PASSWORD))
+            ;
+        }
+
+        // Save new password
+        // Salt renders rainbow-tables attacks useless.
+        $this->container->conf->set('credentials.salt', sha1(uniqid('', true) . '_' . mt_rand()));
+        $this->container->conf->set(
+            'credentials.hash',
+            sha1(
+                $newPassword
+                . $this->container->conf->get('credentials.login')
+                . $this->container->conf->get('credentials.salt')
+            )
+        );
+
+        try {
+            $this->container->conf->write($this->container->loginManager->isLoggedIn());
+        } catch (Throwable $e) {
+            throw new ShaarliFrontException($e->getMessage(), 500, $e);
+        }
+
+        $this->saveSuccessMessage(t('Your password has been changed'));
+
+        return $response->write($this->render(TemplatePage::CHANGE_PASSWORD));
+    }
+}

application/front/controller/admin/PluginsController.php

@@ -0,0 +1,85 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Front\Controller\Admin;
+
+use Exception;
+use Shaarli\Render\TemplatePage;
+use Slim\Http\Request;
+use Slim\Http\Response;
+
+/**
+ * Class PluginsController
+ *
+ * Slim controller used to handle Shaarli plugins configuration page (display + save new config).
+ */
+class PluginsController extends ShaarliAdminController
+{
+    /**
+     * GET /admin/plugins - Displays the configuration page
+     */
+    public function index(Request $request, Response $response): Response
+    {
+        $pluginMeta = $this->container->pluginManager->getPluginsMeta();
+
+        // Split plugins into 2 arrays: ordered enabled plugins and disabled.
+        $enabledPlugins = array_filter($pluginMeta, function ($v) {
+            return ($v['order'] ?? false) !== false;
+        });
+        $enabledPlugins = load_plugin_parameter_values($enabledPlugins, $this->container->conf->get('plugins', []));
+        uasort(
+            $enabledPlugins,
+            function ($a, $b) {
+                return $a['order'] - $b['order'];
+            }
+        );
+        $disabledPlugins = array_filter($pluginMeta, function ($v) {
+            return ($v['order'] ?? false) === false;
+        });
+
+        $this->assignView('enabledPlugins', $enabledPlugins);
+        $this->assignView('disabledPlugins', $disabledPlugins);
+        $this->assignView(
+            'pagetitle',
+            t('Plugin Administration') . ' - ' . $this->container->conf->get('general.title', 'Shaarli')
+        );
+
+        return $response->write($this->render(TemplatePage::PLUGINS_ADMIN));
+    }
+
+    /**
+     * POST /admin/plugins - Update Shaarli's configuration
+     */
+    public function save(Request $request, Response $response): Response
+    {
+        $this->checkToken($request);
+
+        try {
+            $parameters = $request->getParams() ?? [];
+
+            $this->executePageHooks('save_plugin_parameters', $parameters);
+
+            if (isset($parameters['parameters_form'])) {
+                unset($parameters['parameters_form']);
+                unset($parameters['token']);
+                foreach ($parameters as $param => $value) {
+                    $this->container->conf->set('plugins.' . $param, escape($value));
+                }
+            } else {
+                $this->container->conf->set('general.enabled_plugins', save_plugin_config($parameters));
+            }
+
+            $this->container->conf->write($this->container->loginManager->isLoggedIn());
+            $this->container->history->updateSettings();
+
+            $this->saveSuccessMessage(t('Setting successfully saved.'));
+        } catch (Exception $e) {
+            $this->saveErrorMessage(
+                t('Error while saving plugin configuration: ') . PHP_EOL . $e->getMessage()
+            );
+        }
+
+        return $this->redirect($response, '/admin/plugins');
+    }
+}

application/front/controller/admin/ServerController.php

@@ -0,0 +1,101 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Front\Controller\Admin;
+
+use Shaarli\Helper\ApplicationUtils;
+use Shaarli\Helper\FileUtils;
+use Slim\Http\Request;
+use Slim\Http\Response;
+
+/**
+ * Slim controller used to handle Server administration page, and actions.
+ */
+class ServerController extends ShaarliAdminController
+{
+    /** @var string Cache type - main - by default pagecache/ and tmp/ */
+    protected const CACHE_MAIN = 'main';
+
+    /** @var string Cache type - thumbnails - by default cache/ */
+    protected const CACHE_THUMB = 'thumbnails';
+
+    /**
+     * GET /admin/server - Display page Server administration
+     */
+    public function index(Request $request, Response $response): Response
+    {
+        $releaseUrl = ApplicationUtils::$GITHUB_URL . '/releases/';
+        if ($this->container->conf->get('updates.check_updates', true)) {
+            $latestVersion = 'v' . ApplicationUtils::getVersion(
+                ApplicationUtils::$GIT_RAW_URL . '/release/' . ApplicationUtils::$VERSION_FILE
+            );
+            $releaseUrl .= 'tag/' . $latestVersion;
+        } else {
+            $latestVersion = t('Check disabled');
+        }
+
+        $currentVersion = ApplicationUtils::getVersion('./shaarli_version.php');
+        $currentVersion = $currentVersion === 'dev' ? $currentVersion : 'v' . $currentVersion;
+        $phpEol = new \DateTimeImmutable(ApplicationUtils::getPhpEol(PHP_VERSION));
+
+        $permissions = array_merge(
+            ApplicationUtils::checkResourcePermissions($this->container->conf),
+            ApplicationUtils::checkDatastoreMutex()
+        );
+
+        $this->assignView('php_version', PHP_VERSION);
+        $this->assignView('php_eol', format_date($phpEol, false));
+        $this->assignView('php_has_reached_eol', $phpEol < new \DateTimeImmutable());
+        $this->assignView('php_extensions', ApplicationUtils::getPhpExtensionsRequirement());
+        $this->assignView('permissions', $permissions);
+        $this->assignView('release_url', $releaseUrl);
+        $this->assignView('latest_version', $latestVersion);
+        $this->assignView('current_version', $currentVersion);
+        $this->assignView('thumbnails_mode', $this->container->conf->get('thumbnails.mode'));
+        $this->assignView('index_url', index_url($this->container->environment));
+        $this->assignView('client_ip', client_ip_id($this->container->environment));
+        $this->assignView('trusted_proxies', $this->container->conf->get('security.trusted_proxies', []));
+
+        $this->assignView(
+            'pagetitle',
+            t('Server administration') . ' - ' . $this->container->conf->get('general.title', 'Shaarli')
+        );
+
+        return $response->write($this->render('server'));
+    }
+
+    /**
+     * GET /admin/clear-cache?type={$type} - Action to trigger cache folder clearing (either main or thumbnails).
+     */
+    public function clearCache(Request $request, Response $response): Response
+    {
+        $exclude = ['.htaccess'];
+
+        if ($request->getQueryParam('type') === static::CACHE_THUMB) {
+            $folders = [$this->container->conf->get('resource.thumbnails_cache')];
+
+            $this->saveWarningMessage(
+                t('Thumbnails cache has been cleared.') . ' ' .
+                '<a href="' . $this->container->basePath . '/admin/thumbnails">' .
+                    t('Please synchronize them.') .
+                '</a>'
+            );
+        } else {
+            $folders = [
+                $this->container->conf->get('resource.page_cache'),
+                $this->container->conf->get('resource.raintpl_tmp'),
+            ];
+
+            $this->saveSuccessMessage(t('Shaarli\'s cache folder has been cleared!'));
+        }
+
+        // Make sure that we don't delete root cache folder
+        $folders = array_map('realpath', array_values(array_filter(array_map('trim', $folders))));
+        foreach ($folders as $folder) {
+            FileUtils::clearFolder($folder, false, $exclude);
+        }
+
+        return $this->redirect($response, '/admin/server');
+    }
+}

application/front/controller/admin/SessionFilterController.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Front\Controller\Admin;
+
+use Shaarli\Bookmark\BookmarkFilter;
+use Shaarli\Security\SessionManager;
+use Slim\Http\Request;
+use Slim\Http\Response;
+
+/**
+ * Class SessionFilterController
+ *
+ * Slim controller used to handle filters stored in the user session, such as visibility, etc.
+ */
+class SessionFilterController extends ShaarliAdminController
+{
+    /**
+     * GET /admin/visibility: allows to display only public or only private bookmarks in linklist
+     */
+    public function visibility(Request $request, Response $response, array $args): Response
+    {
+        if (false === $this->container->loginManager->isLoggedIn()) {
+            return $this->redirectFromReferer($request, $response, ['visibility']);
+        }
+
+        $newVisibility = $args['visibility'] ?? null;
+        if (false === in_array($newVisibility, [BookmarkFilter::$PRIVATE, BookmarkFilter::$PUBLIC], true)) {
+            $newVisibility = null;
+        }
+
+        $currentVisibility = $this->container->sessionManager->getSessionParameter(SessionManager::KEY_VISIBILITY);
+
+        // Visibility not set or not already expected value, set expected value, otherwise reset it
+        if ($newVisibility !== null && (null === $currentVisibility || $currentVisibility !== $newVisibility)) {
+            // See only public bookmarks
+            $this->container->sessionManager->setSessionParameter(
+                SessionManager::KEY_VISIBILITY,
+                $newVisibility
+            );
+        } else {
+            $this->container->sessionManager->deleteSessionParameter(SessionManager::KEY_VISIBILITY);
+        }
+
+        return $this->redirectFromReferer($request, $response, ['visibility']);
+    }
+}

application/front/controller/admin/ShaareAddController.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Front\Controller\Admin;
+
+use Shaarli\Formatter\BookmarkMarkdownFormatter;
+use Shaarli\Render\TemplatePage;
+use Slim\Http\Request;
+use Slim\Http\Response;
+
+class ShaareAddController extends ShaarliAdminController
+{
+    /**
+     * GET /admin/add-shaare - Displays the form used to create a new bookmark from an URL
+     */
+    public function addShaare(Request $request, Response $response): Response
+    {
+        $tags = $this->container->bookmarkService->bookmarksCountPerTag();
+        if ($this->container->conf->get('formatter') === 'markdown') {
+            $tags[BookmarkMarkdownFormatter::NO_MD_TAG] = 1;
+        }
+
+        $this->assignView(
+            'pagetitle',
+            t('Shaare a new link') . ' - ' . $this->container->conf->get('general.title', 'Shaarli')
+        );
+        $this->assignView('tags', $tags);
+        $this->assignView('default_private_links', $this->container->conf->get('privacy.default_private_links', false));
+        $this->assignView('async_metadata', $this->container->conf->get('general.enable_async_metadata', true));
+
+        return $response->write($this->render(TemplatePage::ADDLINK));
+    }
+}

application/front/controller/admin/ShaareManageController.php

@@ -0,0 +1,287 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Front\Controller\Admin;
+
+use Shaarli\Bookmark\Exception\BookmarkNotFoundException;
+use Slim\Http\Request;
+use Slim\Http\Response;
+
+/**
+ * Class PostBookmarkController
+ *
+ * Slim controller used to handle Shaarli create or edit bookmarks.
+ */
+class ShaareManageController extends ShaarliAdminController
+{
+    /**
+     * GET /admin/shaare/delete - Delete one or multiple bookmarks (depending on `id` query parameter).
+     */
+    public function deleteBookmark(Request $request, Response $response): Response
+    {
+        $this->checkToken($request);
+
+        $ids = escape(trim($request->getParam('id') ?? ''));
+        if (empty($ids) || strpos($ids, ' ') !== false) {
+            // multiple, space-separated ids provided
+            $ids = array_values(array_filter(preg_split('/\s+/', $ids), 'ctype_digit'));
+        } else {
+            $ids = [$ids];
+        }
+
+        // assert at least one id is given
+        if (0 === count($ids)) {
+            $this->saveErrorMessage(t('Invalid bookmark ID provided.'));
+
+            return $this->redirectFromReferer($request, $response, [], ['delete-shaare']);
+        }
+
+        $formatter = $this->container->formatterFactory->getFormatter('raw');
+        $count = 0;
+        foreach ($ids as $id) {
+            try {
+                $bookmark = $this->container->bookmarkService->get((int) $id);
+            } catch (BookmarkNotFoundException $e) {
+                $this->saveErrorMessage(sprintf(
+                    t('Bookmark with identifier %s could not be found.'),
+                    $id
+                ));
+
+                continue;
+            }
+
+            $data = $formatter->format($bookmark);
+            $this->executePageHooks('delete_link', $data);
+            $this->container->bookmarkService->remove($bookmark, false);
+            ++$count;
+        }
+
+        if ($count > 0) {
+            $this->container->bookmarkService->save();
+        }
+
+        // If we are called from the bookmarklet, we must close the popup:
+        if ($request->getParam('source') === 'bookmarklet') {
+            return $response->write('<script>self.close();</script>');
+        }
+
+        if ($request->getParam('source') === 'batch') {
+            return $response->withStatus(204);
+        }
+
+        // Don't redirect to permalink after deletion.
+        return $this->redirectFromReferer($request, $response, ['shaare/']);
+    }
+
+    /**
+     * GET /admin/shaare/visibility
+     *
+     * Change visibility (public/private) of one or multiple bookmarks (depending on `id` query parameter).
+     */
+    public function changeVisibility(Request $request, Response $response): Response
+    {
+        $this->checkToken($request);
+
+        $ids = trim(escape($request->getParam('id') ?? ''));
+        if (empty($ids) || strpos($ids, ' ') !== false) {
+            // multiple, space-separated ids provided
+            $ids = array_values(array_filter(preg_split('/\s+/', $ids), 'ctype_digit'));
+        } else {
+            // only a single id provided
+            $ids = [$ids];
+        }
+
+        // assert at least one id is given
+        if (0 === count($ids)) {
+            $this->saveErrorMessage(t('Invalid bookmark ID provided.'));
+
+            return $this->redirectFromReferer($request, $response, [], ['change_visibility']);
+        }
+
+        // assert that the visibility is valid
+        $visibility = $request->getParam('newVisibility');
+        if (null === $visibility || false === in_array($visibility, ['public', 'private'], true)) {
+            $this->saveErrorMessage(t('Invalid visibility provided.'));
+
+            return $this->redirectFromReferer($request, $response, [], ['change_visibility']);
+        } else {
+            $isPrivate = $visibility === 'private';
+        }
+
+        $formatter = $this->container->formatterFactory->getFormatter('raw');
+        $count = 0;
+
+        foreach ($ids as $id) {
+            try {
+                $bookmark = $this->container->bookmarkService->get((int) $id);
+            } catch (BookmarkNotFoundException $e) {
+                $this->saveErrorMessage(sprintf(
+                    t('Bookmark with identifier %s could not be found.'),
+                    $id
+                ));
+
+                continue;
+            }
+
+            $bookmark->setPrivate($isPrivate);
+
+            // To preserve backward compatibility with 3rd parties, plugins still use arrays
+            $data = $formatter->format($bookmark);
+            $this->executePageHooks('save_link', $data);
+            $bookmark->fromArray($data, $this->container->conf->get('general.tags_separator', ' '));
+
+            $this->container->bookmarkService->set($bookmark, false);
+            ++$count;
+        }
+
+        if ($count > 0) {
+            $this->container->bookmarkService->save();
+        }
+
+        return $this->redirectFromReferer($request, $response, ['/visibility'], ['change_visibility']);
+    }
+
+    /**
+     * GET /admin/shaare/{id}/pin - Pin or unpin a bookmark.
+     */
+    public function pinBookmark(Request $request, Response $response, array $args): Response
+    {
+        $this->checkToken($request);
+
+        $id = $args['id'] ?? '';
+        try {
+            if (false === ctype_digit($id)) {
+                throw new BookmarkNotFoundException();
+            }
+            $bookmark = $this->container->bookmarkService->get((int) $id);  // Read database
+        } catch (BookmarkNotFoundException $e) {
+            $this->saveErrorMessage(sprintf(
+                t('Bookmark with identifier %s could not be found.'),
+                $id
+            ));
+
+            return $this->redirectFromReferer($request, $response, ['/pin'], ['pin']);
+        }
+
+        $formatter = $this->container->formatterFactory->getFormatter('raw');
+
+        $bookmark->setSticky(!$bookmark->isSticky());
+
+        // To preserve backward compatibility with 3rd parties, plugins still use arrays
+        $data = $formatter->format($bookmark);
+        $this->executePageHooks('save_link', $data);
+        $bookmark->fromArray($data, $this->container->conf->get('general.tags_separator', ' '));
+
+        $this->container->bookmarkService->set($bookmark);
+
+        return $this->redirectFromReferer($request, $response, ['/pin'], ['pin']);
+    }
+
+    /**
+     * GET /admin/shaare/private/{hash} - Attach a private key to given bookmark, then redirect to the sharing URL.
+     */
+    public function sharePrivate(Request $request, Response $response, array $args): Response
+    {
+        $this->checkToken($request);
+
+        $hash = $args['hash'] ?? '';
+        $bookmark = $this->container->bookmarkService->findByHash($hash);
+
+        if ($bookmark->isPrivate() !== true) {
+            return $this->redirect($response, '/shaare/' . $hash);
+        }
+
+        if (empty($bookmark->getAdditionalContentEntry('private_key'))) {
+            $privateKey = bin2hex(random_bytes(16));
+            $bookmark->setAdditionalContentEntry('private_key', $privateKey);
+            $this->container->bookmarkService->set($bookmark);
+        }
+
+        return $this->redirect(
+            $response,
+            '/shaare/' . $hash . '?key=' . $bookmark->getAdditionalContentEntry('private_key')
+        );
+    }
+
+    /**
+     * POST /admin/shaare/update-tags
+     *
+     * Bulk add or delete a tags on one or multiple bookmarks.
+     */
+    public function addOrDeleteTags(Request $request, Response $response): Response
+    {
+        $this->checkToken($request);
+
+        $ids = trim(escape($request->getParam('id') ?? ''));
+        if (empty($ids) || strpos($ids, ' ') !== false) {
+            // multiple, space-separated ids provided
+            $ids = array_values(array_filter(preg_split('/\s+/', $ids), 'ctype_digit'));
+        } else {
+            // only a single id provided
+            $ids = [$ids];
+        }
+
+        // assert at least one id is given
+        if (0 === count($ids)) {
+            $this->saveErrorMessage(t('Invalid bookmark ID provided.'));
+
+            return $this->redirectFromReferer($request, $response, ['/updateTag'], []);
+        }
+
+        // assert that the action is valid
+        $action = $request->getParam('action');
+        if (!in_array($action, ['add', 'delete'], true)) {
+            $this->saveErrorMessage(t('Invalid action provided.'));
+
+            return $this->redirectFromReferer($request, $response, ['/updateTag'], []);
+        }
+
+        // assert that the tag name is valid
+        $tagString = trim($request->getParam('tag'));
+        if (empty($tagString)) {
+            $this->saveErrorMessage(t('Invalid tag name provided.'));
+
+            return $this->redirectFromReferer($request, $response, ['/updateTag'], []);
+        }
+
+        $tags = tags_str2array($tagString, $this->container->conf->get('general.tags_separator', ' '));
+        $formatter = $this->container->formatterFactory->getFormatter('raw');
+        $count = 0;
+
+        foreach ($ids as $id) {
+            try {
+                $bookmark = $this->container->bookmarkService->get((int) $id);
+            } catch (BookmarkNotFoundException $e) {
+                $this->saveErrorMessage(sprintf(
+                    t('Bookmark with identifier %s could not be found.'),
+                    $id
+                ));
+
+                continue;
+            }
+
+            foreach ($tags as $tag) {
+                if ($action === 'add') {
+                    $bookmark->addTag($tag);
+                } else {
+                    $bookmark->deleteTag($tag);
+                }
+            }
+
+            // To preserve backward compatibility with 3rd parties, plugins still use arrays
+            $data = $formatter->format($bookmark);
+            $this->executePageHooks('save_link', $data);
+            $bookmark->fromArray($data, $this->container->conf->get('general.tags_separator', ' '));
+
+            $this->container->bookmarkService->set($bookmark, false);
+            ++$count;
+        }
+
+        if ($count > 0) {
+            $this->container->bookmarkService->save();
+        }
+
+        return $this->redirectFromReferer($request, $response, ['/updateTag'], []);
+    }
+}

application/front/controller/admin/ShaarePublishController.php

@@ -0,0 +1,274 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Front\Controller\Admin;
+
+use Shaarli\Bookmark\Bookmark;
+use Shaarli\Bookmark\Exception\BookmarkNotFoundException;
+use Shaarli\Formatter\BookmarkFormatter;
+use Shaarli\Formatter\BookmarkMarkdownFormatter;
+use Shaarli\Render\TemplatePage;
+use Shaarli\Thumbnailer;
+use Slim\Http\Request;
+use Slim\Http\Response;
+
+class ShaarePublishController extends ShaarliAdminController
+{
+    /**
+     * @var BookmarkFormatter[] Statically cached instances of formatters
+     */
+    protected $formatters = [];
+
+    /**
+     * @var array Statically cached bookmark's tags counts
+     */
+    protected $tags;
+
+    /**
+     * GET /admin/shaare - Displays the bookmark form for creation.
+     *                     Note that if the URL is found in existing bookmarks, then it will be in edit mode.
+     */
+    public function displayCreateForm(Request $request, Response $response): Response
+    {
+        $url = cleanup_url($request->getParam('post'));
+        $link = $this->buildLinkDataFromUrl($request, $url);
+
+        return $this->displayForm($link, $link['linkIsNew'], $request, $response);
+    }
+
+    /**
+     * POST /admin/shaare-batch - Displays multiple creation/edit forms from bulk add in add-link page.
+     */
+    public function displayCreateBatchForms(Request $request, Response $response): Response
+    {
+        $urls = array_map('cleanup_url', explode(PHP_EOL, $request->getParam('urls')));
+
+        $links = [];
+        foreach ($urls as $url) {
+            if (empty($url)) {
+                continue;
+            }
+            $link = $this->buildLinkDataFromUrl($request, $url);
+            $data = $this->buildFormData($link, $link['linkIsNew'], $request);
+            $data['token'] = $this->container->sessionManager->generateToken();
+            $data['source'] = 'batch';
+
+            $this->executePageHooks('render_editlink', $data, TemplatePage::EDIT_LINK);
+
+            $links[] = $data;
+        }
+
+        $this->assignView('links', $links);
+        $this->assignView('batch_mode', true);
+        $this->assignView('async_metadata', $this->container->conf->get('general.enable_async_metadata', true));
+
+        return $response->write($this->render(TemplatePage::EDIT_LINK_BATCH));
+    }
+
+    /**
+     * GET /admin/shaare/{id} - Displays the bookmark form in edition mode.
+     */
+    public function displayEditForm(Request $request, Response $response, array $args): Response
+    {
+        $id = $args['id'] ?? '';
+        try {
+            if (false === ctype_digit($id)) {
+                throw new BookmarkNotFoundException();
+            }
+            $bookmark = $this->container->bookmarkService->get((int) $id);  // Read database
+        } catch (BookmarkNotFoundException $e) {
+            $this->saveErrorMessage(sprintf(
+                t('Bookmark with identifier %s could not be found.'),
+                $id
+            ));
+
+            return $this->redirect($response, '/');
+        }
+
+        $formatter = $this->getFormatter('raw');
+        $link = $formatter->format($bookmark);
+
+        return $this->displayForm($link, false, $request, $response);
+    }
+
+    /**
+     * POST /admin/shaare
+     */
+    public function save(Request $request, Response $response): Response
+    {
+        $this->checkToken($request);
+
+        // lf_id should only be present if the link exists.
+        $id = $request->getParam('lf_id') !== null ? intval(escape($request->getParam('lf_id'))) : null;
+        if (null !== $id && true === $this->container->bookmarkService->exists($id)) {
+            // Edit
+            $bookmark = $this->container->bookmarkService->get($id);
+        } else {
+            // New link
+            $bookmark = new Bookmark();
+        }
+
+        $bookmark->setTitle($request->getParam('lf_title'));
+        $bookmark->setDescription($request->getParam('lf_description'));
+        $bookmark->setUrl($request->getParam('lf_url'), $this->container->conf->get('security.allowed_protocols', []));
+        $bookmark->setPrivate(filter_var($request->getParam('lf_private'), FILTER_VALIDATE_BOOLEAN));
+        $bookmark->setTagsString(
+            $request->getParam('lf_tags'),
+            $this->container->conf->get('general.tags_separator', ' ')
+        );
+
+        if (
+            $this->container->conf->get('thumbnails.mode', Thumbnailer::MODE_NONE) !== Thumbnailer::MODE_NONE
+            && true !== $this->container->conf->get('general.enable_async_metadata', true)
+            && $bookmark->shouldUpdateThumbnail()
+        ) {
+            $bookmark->setThumbnail($this->container->thumbnailer->get($bookmark->getUrl()));
+        }
+        $this->container->bookmarkService->addOrSet($bookmark, false);
+
+        // To preserve backward compatibility with 3rd parties, plugins still use arrays
+        $formatter = $this->getFormatter('raw');
+        $data = $formatter->format($bookmark);
+        $this->executePageHooks('save_link', $data);
+
+        $bookmark->fromArray($data, $this->container->conf->get('general.tags_separator', ' '));
+        $this->container->bookmarkService->set($bookmark);
+
+        // If we are called from the bookmarklet, we must close the popup:
+        if ($request->getParam('source') === 'bookmarklet') {
+            return $response->write('<script>self.close();</script>');
+        } elseif ($request->getParam('source') === 'batch') {
+            return $response;
+        }
+
+        if (!empty($request->getParam('returnurl'))) {
+            $this->container->environment['HTTP_REFERER'] = $request->getParam('returnurl');
+        }
+
+        return $this->redirectFromReferer(
+            $request,
+            $response,
+            ['/admin/add-shaare', '/admin/shaare'],
+            ['addlink', 'post', 'edit_link'],
+            $bookmark->getShortUrl()
+        );
+    }
+
+    /**
+     * Helper function used to display the shaare form whether it's a new or existing bookmark.
+     *
+     * @param array $link data used in template, either from parameters or from the data store
+     */
+    protected function displayForm(array $link, bool $isNew, Request $request, Response $response): Response
+    {
+        $data = $this->buildFormData($link, $isNew, $request);
+
+        $this->executePageHooks('render_editlink', $data, TemplatePage::EDIT_LINK);
+
+        foreach ($data as $key => $value) {
+            $this->assignView($key, $value);
+        }
+
+        $editLabel = false === $isNew ? t('Edit') . ' ' : '';
+        $this->assignView(
+            'pagetitle',
+            $editLabel . t('Shaare') . ' - ' . $this->container->conf->get('general.title', 'Shaarli')
+        );
+
+        return $response->write($this->render(TemplatePage::EDIT_LINK));
+    }
+
+    protected function buildLinkDataFromUrl(Request $request, string $url): array
+    {
+        // Check if URL is not already in database (in this case, we will edit the existing link)
+        $bookmark = $this->container->bookmarkService->findByUrl($url);
+        if (null === $bookmark) {
+            // Get shaare data if it was provided in URL (e.g.: by the bookmarklet).
+            $title = $request->getParam('title');
+            $description = $request->getParam('description');
+            $tags = $request->getParam('tags');
+            if ($request->getParam('private') !== null) {
+                $private = filter_var($request->getParam('private'), FILTER_VALIDATE_BOOLEAN);
+            } else {
+                $private = $this->container->conf->get('privacy.default_private_links', false);
+            }
+
+            // If this is an HTTP(S) link, we try go get the page to extract
+            // the title (otherwise we will to straight to the edit form.)
+            if (
+                true !== $this->container->conf->get('general.enable_async_metadata', true)
+                && empty($title)
+                && strpos(get_url_scheme($url) ?: '', 'http') !== false
+            ) {
+                $metadata = $this->container->metadataRetriever->retrieve($url);
+            }
+
+            if (empty($url)) {
+                $metadata['title'] = $this->container->conf->get('general.default_note_title', t('Note: '));
+            }
+
+            return [
+                'title' => $title ?? $metadata['title'] ?? '',
+                'url' => $url ?? '',
+                'description' => $description ?? $metadata['description'] ?? '',
+                'tags' => $tags ?? $metadata['tags'] ?? '',
+                'private' => $private,
+                'linkIsNew' => true,
+            ];
+        }
+
+        $formatter = $this->getFormatter('raw');
+        $link = $formatter->format($bookmark);
+        $link['linkIsNew'] = false;
+
+        return $link;
+    }
+
+    protected function buildFormData(array $link, bool $isNew, Request $request): array
+    {
+        $link['tags'] = $link['tags'] !== null && strlen($link['tags']) > 0
+            ? $link['tags'] . $this->container->conf->get('general.tags_separator', ' ')
+            : $link['tags']
+        ;
+
+        return escape([
+            'link' => $link,
+            'link_is_new' => $isNew,
+            'http_referer' => $this->container->environment['HTTP_REFERER'] ?? '',
+            'source' => $request->getParam('source') ?? '',
+            'tags' => $this->getTags(),
+            'default_private_links' => $this->container->conf->get('privacy.default_private_links', false),
+            'async_metadata' => $this->container->conf->get('general.enable_async_metadata', true),
+            'retrieve_description' => $this->container->conf->get('general.retrieve_description', false),
+        ]);
+    }
+
+    /**
+     * Memoize formatterFactory->getFormatter() calls.
+     */
+    protected function getFormatter(string $type): BookmarkFormatter
+    {
+        if (!array_key_exists($type, $this->formatters) || $this->formatters[$type] === null) {
+            $this->formatters[$type] = $this->container->formatterFactory->getFormatter($type);
+        }
+
+        return $this->formatters[$type];
+    }
+
+    /**
+     * Memoize bookmarkService->bookmarksCountPerTag() calls.
+     */
+    protected function getTags(): array
+    {
+        if ($this->tags === null) {
+            $this->tags = $this->container->bookmarkService->bookmarksCountPerTag();
+
+            if ($this->container->conf->get('formatter') === 'markdown') {
+                $this->tags[BookmarkMarkdownFormatter::NO_MD_TAG] = 1;
+            }
+        }
+
+        return $this->tags;
+    }
+}

application/front/controller/admin/ShaarliAdminController.php

@@ -0,0 +1,71 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Front\Controller\Admin;
+
+use Shaarli\Front\Controller\Visitor\ShaarliVisitorController;
+use Shaarli\Front\Exception\WrongTokenException;
+use Shaarli\Security\SessionManager;
+use Slim\Http\Request;
+
+/**
+ * Class ShaarliAdminController
+ *
+ * All admin controllers (for logged in users) MUST extend this abstract class.
+ * It makes sure that the user is properly logged in, and otherwise throw an exception
+ * which will redirect to the login page.
+ *
+ * @package Shaarli\Front\Controller\Admin
+ */
+abstract class ShaarliAdminController extends ShaarliVisitorController
+{
+    /**
+     * Any persistent action to the config or data store must check the XSRF token validity.
+     */
+    protected function checkToken(Request $request): bool
+    {
+        if (!$this->container->sessionManager->checkToken($request->getParam('token'))) {
+            throw new WrongTokenException();
+        }
+
+        return true;
+    }
+
+    /**
+     * Save a SUCCESS message in user session, which will be displayed on any template page.
+     */
+    protected function saveSuccessMessage(string $message): void
+    {
+        $this->saveMessage(SessionManager::KEY_SUCCESS_MESSAGES, $message);
+    }
+
+    /**
+     * Save a WARNING message in user session, which will be displayed on any template page.
+     */
+    protected function saveWarningMessage(string $message): void
+    {
+        $this->saveMessage(SessionManager::KEY_WARNING_MESSAGES, $message);
+    }
+
+    /**
+     * Save an ERROR message in user session, which will be displayed on any template page.
+     */
+    protected function saveErrorMessage(string $message): void
+    {
+        $this->saveMessage(SessionManager::KEY_ERROR_MESSAGES, $message);
+    }
+
+    /**
+     * Use the sessionManager to save the provided message using the proper type.
+     *
+     * @param string $type successes/warnings/errors
+     */
+    protected function saveMessage(string $type, string $message): void
+    {
+        $messages = $this->container->sessionManager->getSessionParameter($type) ?? [];
+        $messages[] = $message;
+
+        $this->container->sessionManager->setSessionParameter($type, $messages);
+    }
+}

application/front/controller/admin/ThumbnailsController.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Front\Controller\Admin;
+
+use Shaarli\Bookmark\Exception\BookmarkNotFoundException;
+use Shaarli\Render\TemplatePage;
+use Slim\Http\Request;
+use Slim\Http\Response;
+
+/**
+ * Class ToolsController
+ *
+ * Slim controller used to handle thumbnails update.
+ */
+class ThumbnailsController extends ShaarliAdminController
+{
+    /**
+     * GET /admin/thumbnails - Display thumbnails update page
+     */
+    public function index(Request $request, Response $response): Response
+    {
+        $ids = [];
+        foreach ($this->container->bookmarkService->search()->getBookmarks() as $bookmark) {
+            // A note or not HTTP(S)
+            if ($bookmark->isNote() || !startsWith(strtolower($bookmark->getUrl()), 'http')) {
+                continue;
+            }
+
+            $ids[] = $bookmark->getId();
+        }
+
+        $this->assignView('ids', $ids);
+        $this->assignView(
+            'pagetitle',
+            t('Thumbnails update') . ' - ' . $this->container->conf->get('general.title', 'Shaarli')
+        );
+
+        return $response->write($this->render(TemplatePage::THUMBNAILS));
+    }
+
+    /**
+     * PATCH /admin/shaare/{id}/thumbnail-update - Route for AJAX calls
+     */
+    public function ajaxUpdate(Request $request, Response $response, array $args): Response
+    {
+        $id = $args['id'] ?? '';
+
+        if (false === ctype_digit($id)) {
+            return $response->withStatus(400);
+        }
+
+        try {
+            $bookmark = $this->container->bookmarkService->get((int) $id);
+        } catch (BookmarkNotFoundException $e) {
+            return $response->withStatus(404);
+        }
+
+        $bookmark->setThumbnail($this->container->thumbnailer->get($bookmark->getUrl()));
+        $this->container->bookmarkService->set($bookmark);
+
+        return $response->withJson($this->container->formatterFactory->getFormatter('raw')->format($bookmark));
+    }
+}