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

Merge remote-tracking branch 'commu/latest' into myShaarli_commu

Browse source
This commit is contained in:
Knah Tsaeb 2017-11-03 16:24:12 +01:00
commit 8732a436eb
355 changed files with 56041 additions and 2598 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

38
.gitattributes vendored Normal file
View file

@ -0,0 +1,38 @@
# 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
# Exclude from Git archives
.gitattributes export-ignore
.github export-ignore
.gitignore export-ignore
.travis.yml export-ignore
doc/**/*.json export-ignore
doc/**/*.md export-ignore
docker/ export-ignore
Doxyfile export-ignore
Makefile export-ignore
mkdocs.yml export-ignore
phpunit.xml export-ignore
tests/ export-ignore

15
.github/mailmap vendored Normal file
View file

@ -0,0 +1,15 @@
ArthurHoaro <arthur@hoa.ro>
Florian Eula <eula.florian@gmail.com> feula
Florian Eula <eula.florian@gmail.com> <mr.pikzen@gmail.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>
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>

29
.gitignore vendored
View file

@ -1,4 +1,4 @@
# Ignore data/, tmp/, cache/ and pagecache/
# Shaarli runtime resources
data
tmp
cache
@ -8,3 +8,30 @@ pagecache
.settings
.buildpath
.project
# Raintpl generated pages
*.rtpl.php
# 3rd-party dependencies
vendor/
# Release archives
*.tar.gz
*.zip
# Development and test resources
coverage
doxygen
sandbox
phpmd.html
# User plugin configuration
plugins/*/config.php
# HTML documentation
doc/html/
# 3rd party themes
tpl/*
!tpl/default
!tpl/vintage

4
.htaccess Normal file
View file

@ -0,0 +1,4 @@
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^ index.php [QSA,L]

19
.travis.yml Normal file
View file

@ -0,0 +1,19 @@
sudo: false
dist: trusty
language: php
cache:
directories:
- $HOME/.composer/cache
php:
- 7.1
- 7.0
- 5.6
- 5.5
install:
- composer self-update
- composer install --prefer-dist
- locale -a
script:
- make clean
- make check_permissions
- make all_tests

46
AUTHORS Normal file
View file

@ -0,0 +1,46 @@
537 ArthurHoaro <arthur@hoa.ro>
252 VirtualTam <virtualtam@flibidi.net>
148 nodiscc <nodiscc@gmail.com>
56 Sébastien Sauvage <sebsauvage@sebsauvage.net>
15 Florian Eula <eula.florian@gmail.com>
13 Emilien Klein <emilien@klein.st>
12 Nicolas Danelon <hi@nicolasmd.com.ar>
9 Willi Eggeling <thewilli@gmail.com>
8 Christophe HENRY <christophe.henry@sbgodin.fr>
6 B. van Berkum <dev@dotmpe.com>
5 Lucas Cimon <lucas.cimon@gmail.com>
4 Alexandre Alapetite <alexandre@alapetite.fr>
4 David Sferruzza <david.sferruzza@gmail.com>
3 Teromene <teromene@teromene.fr>
3 kalvn <kalvnthereal@gmail.com>
2 Chris Kuethe <chris.kuethe@gmail.com>
2 Knah Tsaeb <Knah-Tsaeb@knah-tsaeb.org>
2 Mathieu Chabanon <git@matchab.fr>
2 Miloš Jovanović <mjovanovic@gmail.com>
2 Qwerty <champlywood@free.fr>
2 Stephen Muth <smuth4@gmail.com>
2 Timo Van Neerden <fire@lehollandaisvolant.net>
2 julienCXX <software@chmodplusx.eu>
2 philipp-r <philipp-r@users.noreply.github.com>
1 Adrien Oliva <adrien.oliva@yapbreak.fr>
1 Alexis J <alexis@effingo.be>
1 BoboTiG <bobotig@gmail.com>
1 Bronco <bronco@warriordudimanche.net>
1 D Low <daniellowtw@gmail.com>
1 Dimtion <zizou.xena@gmail.com>
1 Fanch <fanch-github@qth.fr>
1 Felix Bartels <felix@host-consultants.de>
1 Felix Kästner <github.com-fpunktk@fpunktk.de>
1 Florian Voigt <flvoigt@me.com>
1 Gary Marigliano <gmarigliano93@gmail.com>
1 Guillaume Virlet <github@virlet.org>
1 Jonathan Druart <jonathan.druart@gmail.com>
1 Julien Pivotto <roidelapluie@inuits.eu>
1 Kevin Canévet <kevin@streamroot.io>
1 Knah Tsaeb <knah-tsaeb@knah-tsaeb.org>
1 Lionel Martin <renarddesmers@gmail.com>
1 Mark Gerarts <mark.gerarts@gmail.com>
1 Marsup <marsup@gmail.com>
1 Sbgodin <Sbgodin@users.noreply.github.com>
1 TsT <tst2005@gmail.com>
1 dimtion <zizou.xena@gmail.com>

1094
CHANGELOG.md Normal file
View file

File diff suppressed because it is too large Load diff

78
CONTRIBUTING.md Normal file
View file

@ -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

773
COPYING
View file

@ -1,6 +1,57 @@
Shaarli is distributed under the zlib/libpng License:
Files: *
License: zlib/libpng
Copyright: (c) 2011-2015 Sébastien SAUVAGE <sebsauvage@sebsauvage.net>
(c) 2011-2017 The Shaarli Community, see AUTHORS
Copyright (c) 2011 Sébastien SAUVAGE (sebsauvage.net)
Files: inc/reset.css
License: BSD (http://opensource.org/licenses/BSD-3-Clause)
Copyright: (c) 2010, Yahoo! Inc.
Files: images/calendar.png, images/edit_icon.png, images/feed-icon-14x14.png, images/private.png, images/private_16x16.png, images/private_16x16_active.png, images/tag_blue.png
License: CC-BY (http://creativecommons.org/licenses/by/3.0/)
Copyright: (c) 2014 Yusuke Kamiyamane
Source: http://p.yusukekamiyamane.com/
Files: images/delete_icon.png
License: CC-BY (http://creativecommons.org/licenses/by/3.0/)
Copyright: (c) 2014 Designmodo
Source: http://designmodo.com/linecons-free/
Files: images/floral_left.png, images/floral_right.png, images/squiggle.png, images/squiggle_closing.png
Licence: Public Domain
Source: https://openclipart.org/people/j4p4n/j4p4n_ornimental_bookend_-_left.svg
Files: images/Paper_texture_v5_by_bashcorpo_w1000.jpg
Licence: Public Domain
Source: http://bashcorpo.deviantart.com/art/Grungy-paper-texture-v-5-22966998
Files: images/logo.png
License: zlib/libpng
Copyright: (c) 2011-2014 idleman idleman@idleman.fr
Files: inc/blazy*.js
License: MIT License (http://opensource.org/licenses/MIT)
Copyright: (C) Bjoern Klinggaard - @bklinggaard - http://dinbror.dk/blazy
Files: inc/rain.tpl.class.php
Copyright: 2011-2012, Federico Ulfo <rainelemental@gmail.com>
2011-2012, The Rain Team <hello@raintm.com>
License: LGPL-3+ (https://www.gnu.org/licenses/lgpl-3.0.txt)
Files: inc/awesomplete*
License: MIT License (http://opensource.org/licenses/MIT)
Copyright: (C) 2015 Lea Verou - https://github.com/LeaVerou/awesomplete
Files: plugins/wallabag/wallabag.png
License: MIT License (http://opensource.org/licenses/MIT)
Copyright: (C) 2015 Nicolas Lœuillet - https://github.com/wallabag/wallabag
Files: tpl/default/sad_star.png
License: MIT License (http://opensource.org/licenses/MIT)
Copyright: (C) 2015 kalvn - https://github.com/kalvn/Shaarli-Material
----------------------------------------------------
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 +70,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.

2376
Doxyfile Normal file
View file

File diff suppressed because it is too large Load diff

215
Makefile Normal file
View file

@ -0,0 +1,215 @@
# The personal, minimalist, super-fast, database free, bookmarking service.
# Makefile for PHP code analysis & testing, documentation and release generation
# Prerequisites:
# - install Composer, either:
# - from your distro's package manager;
# - from the official website (https://getcomposer.org/download/);
# - install/update test dependencies:
# $ composer install # 1st setup
# $ composer update
# - install Xdebug for PHPUnit code coverage reports:
# - see http://xdebug.org/docs/install
# - enable in php.ini
BIN = vendor/bin
PHP_SOURCE = index.php application tests plugins
PHP_COMMA_SOURCE = index.php,application,tests,plugins
all: static_analysis_summary 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 $*
##
# Concise status of the project
# These targets are non-blocking: || exit 0
##
static_analysis_summary: code_sniffer_source copy_paste mess_detector_summary
@echo
##
# 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
##
code_sniffer: code_sniffer_full
### - errors filtered by coding standard: PEAR, PSR1, PSR2, Zend...
PHPCS_%:
@$(BIN)/phpcs $(PHP_SOURCE) --report-full --report-width=200 --standard=$*
### - errors by Git author
code_sniffer_blame:
@$(BIN)/phpcs $(PHP_SOURCE) --report-gitblame
### - all errors/warnings
code_sniffer_full:
@$(BIN)/phpcs $(PHP_SOURCE) --report-full --report-width=200
### - errors grouped by kind
code_sniffer_source:
@$(BIN)/phpcs $(PHP_SOURCE) --report-source || exit 0
##
# PHP Copy/Paste Detector
# Detects code redundancy
# Documentation: https://github.com/sebastianbergmann/phpcpd
##
copy_paste:
@echo "-----------------------"
@echo "PHP COPY/PASTE DETECTOR"
@echo "-----------------------"
@$(BIN)/phpcpd $(PHP_SOURCE) || exit 0
@echo
##
# PHP Mess Detector
# Detects PHP syntax errors, sorted by category
# Rules documentation: http://phpmd.org/rules/index.html
##
MESS_DETECTOR_RULES = cleancode,codesize,controversial,design,naming,unusedcode
mess_title:
@echo "-----------------"
@echo "PHP MESS DETECTOR"
@echo "-----------------"
### - all warnings
mess_detector: mess_title
@$(BIN)/phpmd $(PHP_COMMA_SOURCE) text $(MESS_DETECTOR_RULES) | sed 's_.*\/__'
### - all warnings + HTML output contains links to PHPMD's documentation
mess_detector_html:
@$(BIN)/phpmd $(PHP_COMMA_SOURCE) html $(MESS_DETECTOR_RULES) \
--reportfile phpmd.html || exit 0
### - warnings grouped by message, sorted by descending frequency order
mess_detector_grouped: mess_title
@$(BIN)/phpmd $(PHP_SOURCE) text $(MESS_DETECTOR_RULES) \
| cut -f 2 | sort | uniq -c | sort -nr
### - summary: number of warnings by rule set
mess_detector_summary: mess_title
@for rule in $$(echo $(MESS_DETECTOR_RULES) | tr ',' ' '); do \
warnings=$$($(BIN)/phpmd $(PHP_COMMA_SOURCE) text $$rule | wc -l); \
printf "$$warnings\t$$rule\n"; \
done;
##
# Checks source file & script permissions
##
check_permissions:
@echo "----------------------"
@echo "Check file permissions"
@echo "----------------------"
@for file in `git ls-files`; 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:
@echo "-------"
@echo "PHPUNIT"
@echo "-------"
@mkdir -p sandbox coverage
@$(BIN)/phpunit --coverage-php coverage/main.cov --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
@$(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
##
# 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 {} +
### generate a release tarball and include 3rd-party dependencies
release_tar: composer_dependencies htmldoc
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/
gzip $(ARCHIVE_VERSION).tar
### generate a release zip and include 3rd-party dependencies
release_zip: composer_dependencies htmldoc
git archive --prefix=$(ARCHIVE_PREFIX) -o $(ARCHIVE_VERSION).zip -9 HEAD
mkdir -p $(ARCHIVE_PREFIX)/{doc,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/
rm -rf $(ARCHIVE_PREFIX)
##
# Targets for repository and documentation maintenance
##
### remove all unversioned files
clean:
@git clean -df
@rm -rf sandbox
### generate the AUTHORS file from Git commit information
authors:
@cp .github/mailmap .mailmap
@git shortlog -sne > AUTHORS
@rm .mailmap
### generate Doxygen documentation
doxygen: clean
@rm -rf doxygen
@( cat Doxyfile ; echo "PROJECT_NUMBER=`git describe`" ) | doxygen -
### generate HTML documentation from Markdown pages with MkDocs
htmldoc:
python3 -m venv venv/
bash -c 'source venv/bin/activate; \
pip install mkdocs; \
mkdocs build'
find doc/html/ -type f -exec chmod a-x '{}' \;
rm -r venv

110
README.md
View file

@ -1,95 +1,37 @@
![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.
It is designed to be personal (single-user), fast and handy.
_Do you want to share the links you discover?_
_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.8.4-blue.svg)](https://github.com/shaarli/Shaarli/releases/tag/v0.8.4)
[![](https://img.shields.io/travis/shaarli/Shaarli/stable.svg?label=stable)](https://travis-ci.org/shaarli/Shaarli)
&bull;
[![](https://img.shields.io/badge/latest-v0.9.1-blue.svg)](https://github.com/shaarli/Shaarli/releases/tag/v0.9.1)
[![](https://img.shields.io/travis/shaarli/Shaarli/latest.svg?label=latest)](https://travis-ci.org/shaarli/Shaarli)
&bull;
[![](https://img.shields.io/badge/master-v0.9.x-blue.svg)](https://github.com/shaarli/Shaarli)
[![](https://img.shields.io/travis/shaarli/Shaarli.svg?label=master)](https://travis-ci.org/shaarli/Shaarli)
Features:
[![Join the chat at https://gitter.im/shaarli/Shaarli](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/shaarli/Shaarli)
[![Bountysource](https://www.bountysource.com/badge/team?team_id=19583&style=bounties_received)](https://www.bountysource.com/teams/shaarli/issues)
[![Docker repository](https://img.shields.io/docker/pulls/shaarli/shaarli.svg)](https://hub.docker.com/r/shaarli/shaarli/)
* Minimalist design (simple is beautiful)
* **FAST**
* Dead-simple installation: Drop the files, open the page. No database required.
* 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)
## Quickstart
More information on the project page:
http://sebsauvage.net/wiki/doku.php?id=php:shaarli
- [Documentation](https://shaarli.readthedocs.io)
- [Change log](CHANGELOG.md)
- [Bugs/Feature requests/Discussion](https://github.com/shaarli/Shaarli/issues/)
![my Shaarli logo](http://img.knah-tsaeb.org/photos/shaarli/logo_fullsize.png)
### Demo
myShaarli Features :
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.
* Markdown support (web+RSS+Atom)
* 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
Login: `demo`; Password: `demo`
More information on the project page:
https://forge.leslibres.org/Knah-Tsaeb/MyShaarli
### License
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.
------------------------------------------------------------------------------
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.

13
application/.htaccess Normal file
View file

@ -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>

239
application/ApplicationUtils.php Normal file
View file

@ -0,0 +1,239 @@
<?php
/**
* Shaarli (application) utilities
*/
class ApplicationUtils
{
/**
* @var string File containing the current version
*/
public static $VERSION_FILE = 'shaarli_version.php';
private static $GIT_URL = 'https://raw.githubusercontent.com/shaarli/Shaarli';
private static $GIT_BRANCHES = array('latest', 'stable');
private static $VERSION_START_TAG = '<?php /* ';
private static $VERSION_END_TAG = ' */ ?>';
/**
* Gets the latest version code from the Git repository
*
* The code is read from the raw content of the version file on the Git server.
*
* @param string $url URL to reach to get the latest version.
* @param int $timeout Timeout to check the URL (in seconds).
*
* @return mixed the version code from the repository if available, else 'false'
*/
public static function getLatestGitVersionCode($url, $timeout=2)
{
list($headers, $data) = get_http_response($url, $timeout);
if (strpos($headers[0], '200 OK') === false) {
error_log('Failed to retrieve ' . $url);
return false;
}
return $data;
}
/**
* Retrieve the version from a remote URL or a file.
*
* @param string $remote URL or file to fetch.
* @param int $timeout For URLs fetching.
*
* @return bool|string The version or false if it couldn't be retrieved.
*/
public static function getVersion($remote, $timeout = 2)
{
if (startsWith($remote, 'http')) {
if (($data = static::getLatestGitVersionCode($remote, $timeout)) === false) {
return false;
}
} else {
if (! is_file($remote)) {
return false;
}
$data = file_get_contents($remote);
}
return str_replace(
array(self::$VERSION_START_TAG, self::$VERSION_END_TAG, PHP_EOL),
array('', '', ''),
$data
);
}
/**
* Checks if a new Shaarli version has been published on the Git repository
*
* Updates checks are run periodically, according to the following criteria:
* - the update checks are enabled (install, global config);
* - the user is logged in (or this is an open instance);
* - the last check is older than a given interval;
* - the check is non-blocking if the HTTPS connection to Git fails;
* - in case of failure, the update file's modification date is updated,
* to avoid intempestive connection attempts.
*
* @param string $currentVersion the current version code
* @param string $updateFile the file where to store the latest version code
* @param int $checkInterval the minimum interval between update checks (in seconds
* @param bool $enableCheck whether to check for new versions
* @param bool $isLoggedIn whether the user is logged in
* @param string $branch check update for the given branch
*
* @throws Exception an invalid branch has been set for update checks
*
* @return mixed the new version code if available and greater, else 'false'
*/
public static function checkUpdate($currentVersion,
$updateFile,
$checkInterval,
$enableCheck,
$isLoggedIn,
$branch='stable')
{
// Do not check versions for visitors
// Do not check if the user doesn't want to
// Do not check with dev version
if (! $isLoggedIn || empty($enableCheck) || $currentVersion === 'dev') {
return false;
}
if (is_file($updateFile) && (filemtime($updateFile) > time() - $checkInterval)) {
// Shaarli has checked for updates recently - skip HTTP query
$latestKnownVersion = file_get_contents($updateFile);
if (version_compare($latestKnownVersion, $currentVersion) == 1) {
return $latestKnownVersion;
}
return false;
}
if (! in_array($branch, self::$GIT_BRANCHES)) {
throw new Exception(
'Invalid branch selected for updates: "' . $branch . '"'
);
}
// Late Static Binding allows overriding within tests
// See http://php.net/manual/en/language.oop5.late-static-bindings.php
$latestVersion = static::getVersion(
self::$GIT_URL . '/' . $branch . '/' . self::$VERSION_FILE
);
if (! $latestVersion) {
// Only update the file's modification date
file_put_contents($updateFile, $currentVersion);
return false;
}
// Update the file's content and modification date
file_put_contents($updateFile, $latestVersion);
if (version_compare($latestVersion, $currentVersion) == 1) {
return $latestVersion;
}
return false;
}
/**
* Checks the PHP version to ensure Shaarli can run
*
* @param string $minVersion minimum PHP required version
* @param string $curVersion current PHP version (use PHP_VERSION)
*
* @throws Exception the PHP version is not supported
*/
public static function checkPHPVersion($minVersion, $curVersion)
{
if (version_compare($curVersion, $minVersion) < 0) {
throw new Exception(
'Your PHP version is obsolete!'
.' Shaarli requires at least PHP '.$minVersion.', and thus cannot run.'
.' Your PHP version has known security vulnerabilities and should be'
.' updated as soon as possible.'
);
}
}
/**
* Checks Shaarli has the proper access permissions to its resources
*
* @param ConfigManager $conf Configuration Manager instance.
*
* @return array A list of the detected configuration issues
*/
public static function checkResourcePermissions($conf)
{
$errors = array();
$rainTplDir = rtrim($conf->get('resource.raintpl_tpl'), '/');
// Check script and template directories are readable
foreach (array(
'application',
'inc',
'plugins',
$rainTplDir,
$rainTplDir.'/'.$conf->get('resource.theme'),
) as $path) {
if (! is_readable(realpath($path))) {
$errors[] = '"'.$path.'" directory is not readable';
}
}
// Check cache and data directories are readable and writable
foreach (array(
$conf->get('resource.thumbnails_cache'),
$conf->get('resource.data_dir'),
$conf->get('resource.page_cache'),
$conf->get('resource.raintpl_tmp'),
) as $path) {
if (! is_readable(realpath($path))) {
$errors[] = '"'.$path.'" directory is not readable';
}
if (! is_writable(realpath($path))) {
$errors[] = '"'.$path.'" directory is not writable';
}
}
// Check configuration files are readable and writable
foreach (array(
$conf->getConfigFileExt(),
$conf->get('resource.datastore'),
$conf->get('resource.ban_file'),
$conf->get('resource.log'),
$conf->get('resource.update_check'),
) as $path) {
if (! is_file(realpath($path))) {
# the file may not exist yet
continue;
}
if (! is_readable(realpath($path))) {
$errors[] = '"'.$path.'" file is not readable';
}
if (! is_writable(realpath($path))) {
$errors[] = '"'.$path.'" file is not writable';
}
}
return $errors;
}
/**
* Returns a salted hash representing the current Shaarli version.
*
* Useful for assets browser cache.
*
* @param string $currentVersion of Shaarli
* @param string $salt User personal salt, also used for the authentication
*
* @return string version hash
*/
public static function getVersionHash($currentVersion, $salt)
{
return hash_hmac('sha256', $currentVersion, $salt);
}
}

34
application/Base64Url.php Normal file
View file

@ -0,0 +1,34 @@
<?php
namespace Shaarli;
/**
* URL-safe Base64 operations
*
* @see https://en.wikipedia.org/wiki/Base64#URL_applications
*/
class Base64Url
{
/**
* Base64Url-encodes data
*
* @param string $data Data to encode
*
* @return string Base64Url-encoded data
*/
public static function encode($data) {
return rtrim(strtr(base64_encode($data), '+/', '-_'), '=');
}
/**
* Decodes Base64Url-encoded data
*
* @param string $data Data to decode
*
* @return string Decoded data
*/
public static function decode($data) {
return base64_decode(str_pad(strtr($data, '-_', '+/'), strlen($data) % 4, '=', STR_PAD_RIGHT));
}
}

38
application/Cache.php Normal file
View file

@ -0,0 +1,38 @@
<?php
/**
* Cache utilities
*/
/**
* Purges all cached pages
*
* @param string $pageCacheDir page cache directory
*
* @return mixed an error string if the directory is missing
*/
function purgeCachedPages($pageCacheDir)
{
if (! is_dir($pageCacheDir)) {
$error = 'Cannot purge '.$pageCacheDir.': no directory';
error_log($error);
return $error;
}
array_map('unlink', glob($pageCacheDir.'/*.cache'));
}
/**
* Invalidates caches when the database is changed or the user logs out.
*
* @param string $pageCacheDir page cache directory
*/
function invalidateCaches($pageCacheDir)
{
// Purge cache attached to session.
if (isset($_SESSION['tags'])) {
unset($_SESSION['tags']);
}
// Purge page cache shared by sessions.
purgeCachedPages($pageCacheDir);
}

59
application/CachedPage.php Normal file
View file

@ -0,0 +1,59 @@
<?php
/**
* Simple cache system, mainly for the RSS/ATOM feeds
*/
class CachedPage
{
// Directory containing page caches
private $cacheDir;
// Should this URL be cached (boolean)?
private $shouldBeCached;
// Name of the cache file for this URL
private $filename;
/**
* 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
*/
public function __construct($cacheDir, $url, $shouldBeCached)
{
// TODO: check write access to the cache directory
$this->cacheDir = $cacheDir;
$this->filename = $this->cacheDir.'/'.sha1($url).'.cache';
$this->shouldBeCached = $shouldBeCached;
}
/**
* 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 file_get_contents($this->filename);
}
return null;
}
/**
* 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);
}
}

296
application/FeedBuilder.php Normal file
View file

@ -0,0 +1,296 @@
<?php
/**
* 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 links to display in a feed by default.
*/
public static $DEFAULT_NB_LINKS = 50;
/**
* @var LinkDB instance.
*/
protected $linkDB;
/**
* @var string RSS or ATOM feed.
*/
protected $feedType;
/**
* @var array $_SERVER.
*/
protected $serverInfo;
/**
* @var array $_GET.
*/
protected $userInput;
/**
* @var boolean True if the user is currently logged in, false otherwise.
*/
protected $isLoggedIn;
/**
* @var boolean Use permalinks instead of direct links 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 LinkDB $linkDB LinkDB instance.
* @param string $feedType Type of feed.
* @param array $serverInfo $_SERVER.
* @param array $userInput $_GET.
* @param boolean $isLoggedIn True if the user is currently logged in, false otherwise.
*/
public function __construct($linkDB, $feedType, $serverInfo, $userInput, $isLoggedIn)
{
$this->linkDB = $linkDB;
$this->feedType = $feedType;
$this->serverInfo = $serverInfo;
$this->userInput = $userInput;
$this->isLoggedIn = $isLoggedIn;
}
/**
* Build data for feed templates.
*
* @return array Formatted data for feeds templates.
*/
public function buildData()
{
// Search for untagged links
if (isset($this->userInput['searchtags']) && empty($this->userInput['searchtags'])) {
$this->userInput['searchtags'] = false;
}
// Optionally filter the results:
$linksToDisplay = $this->linkDB->filterSearch($this->userInput);
$nblinksToDisplay = $this->getNbLinks(count($linksToDisplay));
// Can't use array_keys() because $link is a LinkDB instance and not a real array.
$keys = array();
foreach ($linksToDisplay as $key => $value) {
$keys[] = $key;
}
$pageaddr = escape(index_url($this->serverInfo));
$linkDisplayed = array();
for ($i = 0; $i < $nblinksToDisplay && $i < count($keys); $i++) {
$linkDisplayed[$keys[$i]] = $this->buildItem($linksToDisplay[$keys[$i]], $pageaddr);
}
$data['language'] = $this->getTypeLanguage();
$data['last_update'] = $this->getLatestDateFormatted();
$data['show_dates'] = !$this->hideDates || $this->isLoggedIn;
// Remove leading slash from REQUEST_URI.
$data['self_link'] = escape(server_url($this->serverInfo))
. escape($this->serverInfo['REQUEST_URI']);
$data['index_url'] = $pageaddr;
$data['usepermalinks'] = $this->usePermalinks === true;
$data['links'] = $linkDisplayed;
return $data;
}
/**
* Build a feed item (one per shaare).
*
* @param array $link Single link array extracted from LinkDB.
* @param string $pageaddr Index URL.
*
* @return array Link array with feed attributes.
*/
protected function buildItem($link, $pageaddr)
{
$link['guid'] = $pageaddr .'?'. $link['shorturl'];
// Check for both signs of a note: starting with ? and 7 chars long.
if ($link['url'][0] === '?' && strlen($link['url']) === 7) {
$link['url'] = $pageaddr . $link['url'];
}
if ($this->usePermalinks === true) {
$permalink = '<a href="'. $link['url'] .'" title="Direct link">Direct link</a>';
} else {
$permalink = '<a href="'. $link['guid'] .'" title="Permalink">Permalink</a>';
}
$link['description'] = format_description($link['description'], '', $pageaddr);
$link['description'] .= PHP_EOL .'<br>&#8212; '. $permalink;
$pubDate = $link['created'];
$link['pub_iso_date'] = $this->getIsoDate($pubDate);
// atom:entry elements MUST contain exactly one atom:updated element.
if (!empty($link['updated'])) {
$upDate = $link['updated'];
$link['up_iso_date'] = $this->getIsoDate($upDate, DateTime::ATOM);
} else {
$link['up_iso_date'] = $this->getIsoDate($pubDate, DateTime::ATOM);;
}
// Save the more recent item.
if (empty($this->latestDate) || $this->latestDate < $pubDate) {
$this->latestDate = $pubDate;
}
if (!empty($upDate) && $this->latestDate < $upDate) {
$this->latestDate = $upDate;
}
$taglist = array_filter(explode(' ', $link['tags']), 'strlen');
uasort($taglist, 'strcasecmp');
$link['taglist'] = $taglist;
return $link;
}
/**
* Set this to true to use permalinks instead of direct links.
*
* @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);
}
/**
* Get the language according to the feed type, based on the locale:
*
* - RSS format: en-us (default: 'en-en').
* - ATOM format: fr (default: 'en').
*
* @return string The language.
*/
public function getTypeLanguage()
{
// Use the locale do define the language, if available.
if (! empty($this->locale) && preg_match('/^\w{2}[_\-]\w{2}/', $this->locale)) {
$length = ($this->feedType == self::$FEED_RSS) ? 5 : 2;
return str_replace('_', '-', substr($this->locale, 0, $length));
}
return ($this->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.
*
* @return string Formatted date.
*/
protected function getLatestDateFormatted()
{
if (empty($this->latestDate) || !$this->latestDate instanceof DateTime) {
return '';
}
$type = ($this->feedType == self::$FEED_RSS) ? DateTime::RSS : DateTime::ATOM;
return $this->latestDate->format($type);
}
/**
* Get ISO date from DateTime according to feed type.
*
* @param DateTime $date Date to format.
* @param string|bool $format Force format.
*
* @return string Formatted date.
*/
protected function getIsoDate(DateTime $date, $format = false)
{
if ($format !== false) {
return $date->format($format);
}
if ($this->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 links (max parameter).
*
* @param int $max maximum number of links to display.
*
* @return int number of links to display.
*/
public function getNbLinks($max)
{
if (empty($this->userInput['nb'])) {
return self::$DEFAULT_NB_LINKS;
}
if ($this->userInput['nb'] == 'all') {
return $max;
}
$intNb = intval($this->userInput['nb']);
if (! is_int($intNb) || $intNb == 0) {
return self::$DEFAULT_NB_LINKS;
}
return $intNb;
}
}

82
application/FileUtils.php Normal file
View file

@ -0,0 +1,82 @@
<?php
require_once 'exceptions/IOException.php';
/**
* Class FileUtils
*
* Utility class for file manipulation.
*/
class FileUtils
{
/**
* @var string
*/
protected static $phpPrefix = '<?php /* ';
/**
* @var string
*/
protected static $phpSuffix = ' */ ?>';
/**
* Write data into a file (Shaarli database format).
* The data is stored in a PHP file, as a comment, in compressed base64 format.
*
* The file will be created if it doesn't exist.
*
* @param string $file File path.
* @param mixed $content Content to write.
*
* @return int|bool Number of bytes written or false if it fails.
*
* @throws IOException The destination file can't be written.
*/
public static function writeFlatDB($file, $content)
{
if (is_file($file) && !is_writeable($file)) {
// The datastore exists but is not writeable
throw new IOException($file);
} else if (!is_file($file) && !is_writeable(dirname($file))) {
// The datastore does not exist and its parent directory is not writeable
throw new IOException(dirname($file));
}
return file_put_contents(
$file,
self::$phpPrefix.base64_encode(gzdeflate(serialize($content))).self::$phpSuffix
);
}
/**
* Read data from a file containing Shaarli database format content.
*
* If the file isn't readable or doesn't exist, default data will be returned.
*
* @param string $file File path.
* @param mixed $default The default value to return if the file isn't readable.
*
* @return mixed The content unserialized, or default if the file isn't readable, or false if it fails.
*/
public static function readFlatDB($file, $default = null)
{
// Note that gzinflate is faster than gzuncompress.
// See: http://www.php.net/manual/en/function.gzdeflate.php#96439
if (! is_readable($file)) {
return $default;
}
$data = file_get_contents($file);
if ($data == '') {
return $default;
}
return unserialize(
gzinflate(
base64_decode(
substr($data, strlen(self::$phpPrefix), -strlen(self::$phpSuffix))
)
)
);
}
}

200
application/History.php Normal file
View file

@ -0,0 +1,200 @@
<?php
/**
* 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.
*
* 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.
*/
const CREATED = 'CREATED';
/**
* @var string Action key: a link has been updated.
*/
const UPDATED = 'UPDATED';
/**
* @var string Action key: a link has been deleted.
*/
const DELETED = 'DELETED';
/**
* @var string Action key: settings have been updated.
*/
const SETTINGS = 'SETTINGS';
/**
* @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 rentention 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 array $link Link data.
*/
public function addLink($link)
{
$this->addEvent(self::CREATED, $link['id']);
}
/**
* Add Event: update existing link.
*
* @param array $link Link data.
*/
public function updateLink($link)
{
$this->addEvent(self::UPDATED, $link['id']);
}
/**
* Add Event: delete existing link.
*
* @param array $link Link data.
*/
public function deleteLink($link)
{
$this->addEvent(self::DELETED, $link['id']);
}
/**
* Add Event: settings updated.
*/
public function updateSettings()
{
$this->addEvent(self::SETTINGS);
}
/**
* 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('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('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;
}
}

431
application/HttpUtils.php Normal file
View file

@ -0,0 +1,431 @@
<?php
/**
* GET an HTTP URL to retrieve its content
* Uses the cURL library or a fallback method
*
* @param string $url URL to get (http://...)
* @param int $timeout network timeout (in seconds)
* @param int $maxBytes maximum downloaded bytes (default: 4 MiB)
*
* @return array HTTP response headers, downloaded content
*
* Output format:
* [0] = associative array containing HTTP response headers
* [1] = URL content (downloaded data)
*
* Example:
* list($headers, $data) = get_http_response('http://sebauvage.net/');
* if (strpos($headers[0], '200 OK') !== false) {
* echo 'Data type: '.htmlspecialchars($headers['Content-Type']);
* } else {
* echo 'There was an error: '.htmlspecialchars($headers[0]);
* }
*
* @see https://secure.php.net/manual/en/ref.curl.php
* @see https://secure.php.net/manual/en/functions.anonymous.php
* @see https://secure.php.net/manual/en/function.preg-split.php
* @see https://secure.php.net/manual/en/function.explode.php
* @see http://stackoverflow.com/q/17641073
* @see http://stackoverflow.com/q/9183178
* @see http://stackoverflow.com/q/1462720
*/
function get_http_response($url, $timeout = 30, $maxBytes = 4194304)
{
$urlObj = new Url($url);
$cleanUrl = $urlObj->idnToAscii();
if (!filter_var($cleanUrl, FILTER_VALIDATE_URL) || !$urlObj->isHttp()) {
return array(array(0 => 'Invalid HTTP Url'), false);
}
$userAgent =
'Mozilla/5.0 (X11; Fedora; Linux x86_64; rv:45.0)'
. ' Gecko/20100101 Firefox/45.0';
$acceptLanguage =
substr(setlocale(LC_COLLATE, 0), 0, 2) . ',en-US;q=0.7,en;q=0.3';
$maxRedirs = 3;
if (!function_exists('curl_init')) {
return get_http_response_fallback(
$cleanUrl,
$timeout,
$maxBytes,
$userAgent,
$acceptLanguage,
$maxRedirs
);
}
$ch = curl_init($cleanUrl);
if ($ch === false) {
return array(array(0 => 'curl_init() error'), false);
}
// General cURL settings
curl_setopt($ch, CURLOPT_AUTOREFERER, true);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt(
$ch,
CURLOPT_HTTPHEADER,
array('Accept-Language: ' . $acceptLanguage)
);
curl_setopt($ch, CURLOPT_MAXREDIRS, $maxRedirs);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, $timeout);
curl_setopt($ch, CURLOPT_USERAGENT, $userAgent);
// Max download size management
curl_setopt($ch, CURLOPT_BUFFERSIZE, 1024);
curl_setopt($ch, CURLOPT_NOPROGRESS, false);
curl_setopt($ch, CURLOPT_PROGRESSFUNCTION,
function($arg0, $arg1, $arg2, $arg3, $arg4 = 0) use ($maxBytes)
{
if (version_compare(phpversion(), '5.5', '<')) {
// PHP version lower than 5.5
// Callback has 4 arguments
$downloaded = $arg1;
} else {
// Callback has 5 arguments
$downloaded = $arg2;
}
// Non-zero return stops downloading
return ($downloaded > $maxBytes) ? 1 : 0;
}
);
$response = curl_exec($ch);
$errorNo = curl_errno($ch);
$errorStr = curl_error($ch);
$headSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
curl_close($ch);
if ($response === false) {
if ($errorNo == CURLE_COULDNT_RESOLVE_HOST) {
/*
* Workaround to match fallback method behaviour
* Removing this would require updating
* GetHttpUrlTest::testGetInvalidRemoteUrl()
*/
return array(false, false);
}
return array(array(0 => 'curl_exec() error: ' . $errorStr), false);
}
// Formatting output like the fallback method
$rawHeaders = substr($response, 0, $headSize);
// Keep only headers from latest redirection
$rawHeadersArrayRedirs = explode("\r\n\r\n", trim($rawHeaders));
$rawHeadersLastRedir = end($rawHeadersArrayRedirs);
$content = substr($response, $headSize);
$headers = array();
foreach (preg_split('~[\r\n]+~', $rawHeadersLastRedir) as $line) {
if (empty($line) || ctype_space($line)) {
continue;
}
$splitLine = explode(': ', $line, 2);
if (count($splitLine) > 1) {
$key = $splitLine[0];
$value = $splitLine[1];
if (array_key_exists($key, $headers)) {
if (!is_array($headers[$key])) {
$headers[$key] = array(0 => $headers[$key]);
}
$headers[$key][] = $value;
} else {
$headers[$key] = $value;
}
} else {
$headers[] = $splitLine[0];
}
}
return array($headers, $content);
}
/**
* GET an HTTP URL to retrieve its content (fallback method)
*
* @param string $cleanUrl URL to get (http://... valid and in ASCII form)
* @param int $timeout network timeout (in seconds)
* @param int $maxBytes maximum downloaded bytes
* @param string $userAgent "User-Agent" header
* @param string $acceptLanguage "Accept-Language" header
* @param int $maxRedr maximum amount of redirections followed
*
* @return array HTTP response headers, downloaded content
*
* Output format:
* [0] = associative array containing HTTP response headers
* [1] = URL content (downloaded data)
*
* @see http://php.net/manual/en/function.file-get-contents.php
* @see http://php.net/manual/en/function.stream-context-create.php
* @see http://php.net/manual/en/function.get-headers.php
*/
function get_http_response_fallback(
$cleanUrl,
$timeout,
$maxBytes,
$userAgent,
$acceptLanguage,
$maxRedr
) {
$options = array(
'http' => array(
'method' => 'GET',
'timeout' => $timeout,
'user_agent' => $userAgent,
'header' => "Accept: */*\r\n"
. 'Accept-Language: ' . $acceptLanguage
)
);
stream_context_set_default($options);
list($headers, $finalUrl) = get_redirected_headers($cleanUrl, $maxRedr);
if (! $headers || strpos($headers[0], '200 OK') === false) {
$options['http']['request_fulluri'] = true;
stream_context_set_default($options);
list($headers, $finalUrl) = get_redirected_headers($cleanUrl, $maxRedr);
}
if (! $headers) {
return array($headers, false);
}
try {
// TODO: catch Exception in calling code (thumbnailer)
$context = stream_context_create($options);
$content = file_get_contents($finalUrl, false, $context, -1, $maxBytes);
} catch (Exception $exc) {
return array(array(0 => 'HTTP Error'), $exc->getMessage());
}
return array($headers, $content);
}
/**
* Retrieve HTTP headers, following n redirections (temporary and permanent ones).
*
* @param string $url initial URL to reach.
* @param int $redirectionLimit max redirection follow.
*
* @return array HTTP headers, or false if it failed.
*/
function get_redirected_headers($url, $redirectionLimit = 3)
{
$headers = get_headers($url, 1);
if (!empty($headers['location']) && empty($headers['Location'])) {
$headers['Location'] = $headers['location'];
}
// Headers found, redirection found, and limit not reached.
if ($redirectionLimit-- > 0
&& !empty($headers)
&& (strpos($headers[0], '301') !== false || strpos($headers[0], '302') !== false)
&& !empty($headers['Location'])) {
$redirection = is_array($headers['Location']) ? end($headers['Location']) : $headers['Location'];
if ($redirection != $url) {
$redirection = getAbsoluteUrl($url, $redirection);
return get_redirected_headers($redirection, $redirectionLimit);
}
}
return array($headers, $url);
}
/**
* Get an absolute URL from a complete one, and another absolute/relative URL.
*
* @param string $originalUrl The original complete URL.
* @param string $newUrl The new one, absolute or relative.
*
* @return string Final URL:
* - $newUrl if it was already an absolute URL.
* - if it was relative, absolute URL from $originalUrl path.
*/
function getAbsoluteUrl($originalUrl, $newUrl)
{
$newScheme = parse_url($newUrl, PHP_URL_SCHEME);
// Already an absolute URL.
if (!empty($newScheme)) {
return $newUrl;
}
$parts = parse_url($originalUrl);
$final = $parts['scheme'] .'://'. $parts['host'];
$final .= (!empty($parts['port'])) ? $parts['port'] : '';
$final .= '/';
if ($newUrl[0] != '/') {
$final .= substr(ltrim($parts['path'], '/'), 0, strrpos($parts['path'], '/'));
}
$final .= ltrim($newUrl, '/');
return $final;
}
/**
* Returns the server's base URL: scheme://domain.tld[:port]
*
* @param array $server the $_SERVER array
*
* @return string the server's base URL
*
* @see http://www.ietf.org/rfc/rfc7239.txt
* @see http://www.ietf.org/rfc/rfc6648.txt
* @see http://stackoverflow.com/a/3561399
* @see http://stackoverflow.com/q/452375
*/
function server_url($server)
{
$scheme = 'http';
$port = '';
// Shaarli is served behind a proxy
if (isset($server['HTTP_X_FORWARDED_PROTO'])) {
// Keep forwarded scheme
if (strpos($server['HTTP_X_FORWARDED_PROTO'], ',') !== false) {
$schemes = explode(',', $server['HTTP_X_FORWARDED_PROTO']);
$scheme = trim($schemes[0]);
} else {
$scheme = $server['HTTP_X_FORWARDED_PROTO'];
}
if (isset($server['HTTP_X_FORWARDED_PORT'])) {
// Keep forwarded port
if (strpos($server['HTTP_X_FORWARDED_PORT'], ',') !== false) {
$ports = explode(',', $server['HTTP_X_FORWARDED_PORT']);
$port = trim($ports[0]);
} else {
$port = $server['HTTP_X_FORWARDED_PORT'];
}
if (($scheme == 'http' && $port != '80')
|| ($scheme == 'https' && $port != '443')
) {
$port = ':' . $port;
} else {
$port = '';
}
}
if (isset($server['HTTP_X_FORWARDED_HOST'])) {
// Keep forwarded host
if (strpos($server['HTTP_X_FORWARDED_HOST'], ',') !== false) {
$hosts = explode(',', $server['HTTP_X_FORWARDED_HOST']);
$host = trim($hosts[0]);
} else {
$host = $server['HTTP_X_FORWARDED_HOST'];
}
} else {
$host = $server['SERVER_NAME'];
}
return $scheme.'://'.$host.$port;
}
// SSL detection
if ((! empty($server['HTTPS']) && strtolower($server['HTTPS']) == 'on')
|| (isset($server['SERVER_PORT']) && $server['SERVER_PORT'] == '443')) {
$scheme = 'https';
}
// Do not append standard port values
if (($scheme == 'http' && $server['SERVER_PORT'] != '80')
|| ($scheme == 'https' && $server['SERVER_PORT'] != '443')) {
$port = ':'.$server['SERVER_PORT'];
}
return $scheme.'://'.$server['SERVER_NAME'].$port;
}
/**
* Returns the absolute URL of the current script, without the query
*
* If the resource is "index.php", then it is removed (for better-looking URLs)
*
* @param array $server the $_SERVER array
*
* @return string the absolute URL of the current script, without the query
*/
function index_url($server)
{
$scriptname = $server['SCRIPT_NAME'];
if (endsWith($scriptname, 'index.php')) {
$scriptname = substr($scriptname, 0, -9);
}
return server_url($server) . $scriptname;
}
/**
* Returns the absolute URL of the current script, with the query
*
* If the resource is "index.php", then it is removed (for better-looking URLs)
*
* @param array $server the $_SERVER array
*
* @return string the absolute URL of the current script, with the query
*/
function page_url($server)
{
if (! empty($server['QUERY_STRING'])) {
return index_url($server).'?'.$server['QUERY_STRING'];
}
return index_url($server);
}
/**
* Retrieve the initial IP forwarded by the reverse proxy.
*
* Inspired from: https://github.com/zendframework/zend-http/blob/master/src/PhpEnvironment/RemoteAddress.php
*
* @param array $server $_SERVER array which contains HTTP headers.
* @param array $trustedIps List of trusted IP from the configuration.
*
* @return string|bool The forwarded IP, or false if none could be extracted.
*/
function getIpAddressFromProxy($server, $trustedIps)
{
$forwardedIpHeader = 'HTTP_X_FORWARDED_FOR';
if (empty($server[$forwardedIpHeader])) {
return false;
}
$ips = preg_split('/\s*,\s*/', $server[$forwardedIpHeader]);
$ips = array_diff($ips, $trustedIps);
if (empty($ips)) {
return false;
}
return array_pop($ips);
}
/**
* Returns true if Shaarli's currently browsed in HTTPS.
* Supports reverse proxies (if the headers are correctly set).
*
* @param array $server $_SERVER.
*
* @return bool true if HTTPS, false otherwise.
*/
function is_https($server)
{
if (isset($server['HTTP_X_FORWARDED_PORT'])) {
// Keep forwarded port
if (strpos($server['HTTP_X_FORWARDED_PORT'], ',') !== false) {
$ports = explode(',', $server['HTTP_X_FORWARDED_PORT']);
$port = trim($ports[0]);
} else {
$port = $server['HTTP_X_FORWARDED_PORT'];
}
if ($port == '443') {
return true;
}
}
return ! empty($server['HTTPS']);
}

21
application/Languages.php Normal file
View file

@ -0,0 +1,21 @@
<?php
/**
* Wrapper function for translation which match the API
* of gettext()/_() and ngettext().
*
* Not doing translation for now.
*
* @param string $text Text to translate.
* @param string $nText The plural message ID.
* @param int $nb The number of items for plural forms.
*
* @return String Text translated.
*/
function t($text, $nText = '', $nb = 0) {
if (empty($nText)) {
return $text;
}
$actualForm = $nb > 1 ? $nText : $text;
return sprintf($actualForm, $nb);
}

567
application/LinkDB.php Normal file
View file

@ -0,0 +1,567 @@
<?php
/**
* Data storage for links.
*
* This object behaves like an associative array.
*
* Example:
* $myLinks = new LinkDB();
* echo $myLinks[350]['title'];
* foreach ($myLinks as $link)
* echo $link['title'].' at url '.$link['url'].'; description:'.$link['description'];
*
* Available keys:
* - id: primary key, incremental integer identifier (persistent)
* - description: description of the entry
* - created: creation date of this entry, DateTime object.
* - updated: last modification date of this entry, DateTime object.
* - private: Is this link private? 0=no, other value=yes
* - tags: tags attached to this entry (separated by spaces)
* - title Title of the link
* - url URL of the link. Used for displayable links (no redirector, relative, etc.).
* Can be absolute or relative.
* Relative URLs are permalinks (e.g.'?m-ukcw')
* - real_url Absolute processed URL.
* - shorturl Permalink smallhash
*
* Implements 3 interfaces:
* - ArrayAccess: behaves like an associative array;
* - Countable: there is a count() method;
* - Iterator: usable in foreach () loops.
*
* ID mechanism:
* ArrayAccess is implemented in a way that will allow to access a link
* with the unique identifier ID directly with $link[ID].
* Note that it's not the real key of the link array attribute.
* This mechanism is in place to have persistent link IDs,
* even though the internal array is reordered by date.
* Example:
* - DB: link #1 (2010-01-01) link #2 (2016-01-01)
* - Order: #2 #1
* - Import links containing: link #3 (2013-01-01)
* - New DB: link #1 (2010-01-01) link #2 (2016-01-01) link #3 (2013-01-01)
* - Real order: #2 #3 #1
*/
class LinkDB implements Iterator, Countable, ArrayAccess
{
// Links are stored as a PHP serialized string
private $datastore;
// Link date storage format
const LINK_DATE_FORMAT = 'Ymd_His';
// List of links (associative array)
// - key: link date (e.g. "20110823_124546"),
// - value: associative array (keys: title, description...)
private $links;
// List of all recorded URLs (key=url, value=link offset)
// for fast reserve search (url-->link offset)
private $urls;
/**
* @var array List of all links IDS mapped with their array offset.
* Map: id->offset.
*/
protected $ids;
// List of offset keys (for the Iterator interface implementation)
private $keys;
// Position in the $this->keys array (for the Iterator interface)
private $position;
// Is the user logged in? (used to filter private links)
private $loggedIn;
// Hide public links
private $hidePublicLinks;
// link redirector set in user settings.
private $redirector;
/**
* Set this to `true` to urlencode link behind redirector link, `false` to leave it untouched.
*
* Example:
* anonym.to needs clean URL while dereferer.org needs urlencoded URL.
*
* @var boolean $redirectorEncode parameter: true or false
*/
private $redirectorEncode;
/**
* Creates a new LinkDB
*
* Checks if the datastore exists; else, attempts to create a dummy one.
*
* @param string $datastore datastore file path.
* @param boolean $isLoggedIn is the user logged in?
* @param boolean $hidePublicLinks if true all links are private.
* @param string $redirector link redirector set in user settings.
* @param boolean $redirectorEncode Enable urlencode on redirected urls (default: true).
*/
public function __construct(
$datastore,
$isLoggedIn,
$hidePublicLinks,
$redirector = '',
$redirectorEncode = true
)
{
$this->datastore = $datastore;
$this->loggedIn = $isLoggedIn;
$this->hidePublicLinks = $hidePublicLinks;
$this->redirector = $redirector;
$this->redirectorEncode = $redirectorEncode === true;
$this->check();
$this->read();
}
/**
* Countable - Counts elements of an object
*/
public function count()
{
return count($this->links);
}
/**
* ArrayAccess - Assigns a value to the specified offset
*/
public function offsetSet($offset, $value)
{
// TODO: use exceptions instead of "die"
if (!$this->loggedIn) {
die('You are not authorized to add a link.');
}
if (!isset($value['id']) || empty($value['url'])) {
die('Internal Error: A link should always have an id and URL.');
}
if (($offset !== null && ! is_int($offset)) || ! is_int($value['id'])) {
die('You must specify an integer as a key.');
}
if ($offset !== null && $offset !== $value['id']) {
die('Array offset and link ID must be equal.');
}
// If the link exists, we reuse the real offset, otherwise new entry
$existing = $this->getLinkOffset($offset);
if ($existing !== null) {
$offset = $existing;
} else {
$offset = count($this->links);
}
$this->links[$offset] = $value;
$this->urls[$value['url']] = $offset;
$this->ids[$value['id']] = $offset;
}
/**
* ArrayAccess - Whether or not an offset exists
*/
public function offsetExists($offset)
{
return array_key_exists($this->getLinkOffset($offset), $this->links);
}
/**
* ArrayAccess - Unsets an offset
*/
public function offsetUnset($offset)
{
if (!$this->loggedIn) {
// TODO: raise an exception
die('You are not authorized to delete a link.');
}
$realOffset = $this->getLinkOffset($offset);
$url = $this->links[$realOffset]['url'];
unset($this->urls[$url]);
unset($this->ids[$realOffset]);
unset($this->links[$realOffset]);
}
/**
* ArrayAccess - Returns the value at specified offset
*/
public function offsetGet($offset)
{
$realOffset = $this->getLinkOffset($offset);
return isset($this->links[$realOffset]) ? $this->links[$realOffset] : null;
}
/**
* Iterator - Returns the current element
*/
public function current()
{
return $this[$this->keys[$this->position]];
}
/**
* Iterator - Returns the key of the current element
*/
public function key()
{
return $this->keys[$this->position];
}
/**
* Iterator - Moves forward to next element
*/
public function next()
{
++$this->position;
}
/**
* Iterator - Rewinds the Iterator to the first element
*
* Entries are sorted by date (latest first)
*/
public function rewind()
{
$this->keys = array_keys($this->ids);
$this->position = 0;
}
/**
* Iterator - Checks if current position is valid
*/
public function valid()
{
return isset($this->keys[$this->position]);
}
/**
* Checks if the DB directory and file exist
*
* If no DB file is found, creates a dummy DB.
*/
private function check()
{
if (file_exists($this->datastore)) {
return;
}
// Create a dummy database for example
$this->links = array();
$link = array(
'id' => 1,
'title'=>' Shaarli: the personal, minimalist, super-fast, no-database delicious clone',
'url'=>'https://shaarli.readthedocs.io',
'description'=>'Welcome to Shaarli! This is your first public bookmark. To edit or delete me, you must first login.
To learn how to use Shaarli, consult the link "Help/documentation" at the bottom of this page.
You use the community supported version of the original Shaarli project, by Sebastien Sauvage.',
'private'=>0,
'created'=> new DateTime(),
'tags'=>'opensource software'
);
$link['shorturl'] = link_small_hash($link['created'], $link['id']);
$this->links[1] = $link;
$link = array(
'id' => 0,
'title'=>'My secret stuff... - Pastebin.com',
'url'=>'http://sebsauvage.net/paste/?8434b27936c09649#bR7XsXhoTiLcqCpQbmOpBi3rq2zzQUC5hBI7ZT1O3x8=',
'description'=>'Shhhh! I\'m a private link only YOU can see. You can delete me too.',
'private'=>1,
'created'=> new DateTime('1 minute ago'),
'tags'=>'secretstuff',
);
$link['shorturl'] = link_small_hash($link['created'], $link['id']);
$this->links[0] = $link;
// Write database to disk
$this->write();
}
/**
* Reads database from disk to memory
*/
private function read()
{
// Public links are hidden and user not logged in => nothing to show
if ($this->hidePublicLinks && !$this->loggedIn) {
$this->links = array();
return;
}
$this->links = FileUtils::readFlatDB($this->datastore, []);
$toremove = array();
foreach ($this->links as $key => &$link) {
if (! $this->loggedIn && $link['private'] != 0) {
// Transition for not upgraded databases.
$toremove[] = $key;
continue;
}
// Sanitize data fields.
sanitizeLink($link);
// Remove private tags if the user is not logged in.
if (! $this->loggedIn) {
$link['tags'] = preg_replace('/(^|\s+)\.[^($|\s)]+\s*/', ' ', $link['tags']);
}
// Do not use the redirector for internal links (Shaarli note URL starting with a '?').
if (!empty($this->redirector) && !startsWith($link['url'], '?')) {
$link['real_url'] = $this->redirector;
if ($this->redirectorEncode) {
$link['real_url'] .= urlencode(unescape($link['url']));
} else {
$link['real_url'] .= $link['url'];
}
}
else {
$link['real_url'] = $link['url'];
}
// To be able to load links before running the update, and prepare the update
if (! isset($link['created'])) {
$link['id'] = $link['linkdate'];
$link['created'] = DateTime::createFromFormat(self::LINK_DATE_FORMAT, $link['linkdate']);
if (! empty($link['updated'])) {
$link['updated'] = DateTime::createFromFormat(self::LINK_DATE_FORMAT, $link['updated']);
}
$link['shorturl'] = smallHash($link['linkdate']);
}
}
// If user is not logged in, filter private links.
foreach ($toremove as $offset) {
unset($this->links[$offset]);
}
$this->reorder();
}
/**
* Saves the database from memory to disk
*
* @throws IOException the datastore is not writable
*/
private function write()
{
FileUtils::writeFlatDB($this->datastore, $this->links);
}
/**
* Saves the database from memory to disk
*
* @param string $pageCacheDir page cache directory
*/
public function save($pageCacheDir)
{
if (!$this->loggedIn) {
// TODO: raise an Exception instead
die('You are not authorized to change the database.');
}
$this->write();
invalidateCaches($pageCacheDir);
}
/**
* Returns the link for a given URL, or False if it does not exist.
*
* @param string $url URL to search for
*
* @return mixed the existing link if it exists, else 'false'
*/
public function getLinkFromUrl($url)
{
if (isset($this->urls[$url])) {
return $this->links[$this->urls[$url]];
}
return false;
}
/**
* Returns the shaare corresponding to a smallHash.
*
* @param string $request QUERY_STRING server parameter.
*
* @return array $filtered array containing permalink data.
*
* @throws LinkNotFoundException if the smallhash is malformed or doesn't match any link.
*/
public function filterHash($request)
{
$request = substr($request, 0, 6);
$linkFilter = new LinkFilter($this->links);
return $linkFilter->filter(LinkFilter::$FILTER_HASH, $request);
}
/**
* Returns the list of articles for a given day.
*
* @param string $request day to filter. Format: YYYYMMDD.
*
* @return array list of shaare found.
*/
public function filterDay($request) {
$linkFilter = new LinkFilter($this->links);
return $linkFilter->filter(LinkFilter::$FILTER_DAY, $request);
}
/**
* Filter links according to search parameters.
*
* @param array $filterRequest Search request content. Supported keys:
* - searchtags: list of tags
* - searchterm: term search
* @param bool $casesensitive Optional: Perform case sensitive filter
* @param string $visibility return only all/private/public links
* @param string $untaggedonly return only untagged links
*
* @return array filtered links, all links if no suitable filter was provided.
*/
public function filterSearch($filterRequest = array(), $casesensitive = false, $visibility = 'all', $untaggedonly = false)
{
// Filter link database according to parameters.
$searchtags = isset($filterRequest['searchtags']) ? escape($filterRequest['searchtags']) : '';
$searchterm = isset($filterRequest['searchterm']) ? escape($filterRequest['searchterm']) : '';
// Search tags + fullsearch - blank string parameter will return all links.
$type = LinkFilter::$FILTER_TAG | LinkFilter::$FILTER_TEXT; // == "vuotext"
$request = [$searchtags, $searchterm];
$linkFilter = new LinkFilter($this);
return $linkFilter->filter($type, $request, $casesensitive, $visibility, $untaggedonly);
}
/**
* Returns the list tags appearing in the links with the given tags
* @param $filteringTags: tags selecting the links to consider
* @param $visibility: process only all/private/public links
* @return: a tag=>linksCount array
*/
public function linksCountPerTag($filteringTags = [], $visibility = 'all')
{
$links = empty($filteringTags) ? $this->links : $this->filterSearch(['searchtags' => $filteringTags], false, $visibility);
$tags = array();
$caseMapping = array();
foreach ($links as $link) {
foreach (preg_split('/\s+/', $link['tags'], 0, PREG_SPLIT_NO_EMPTY) as $tag) {
if (empty($tag)) {
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)]]++;
}
}
// Sort tags by usage (most used tag first)
arsort($tags);
return $tags;
}
/**
* Rename or delete a tag across all links.
*
* @param string $from Tag to rename
* @param string $to New tag. If none is provided, the from tag will be deleted
*
* @return array|bool List of altered links or false on error
*/
public function renameTag($from, $to)
{
if (empty($from)) {
return false;
}
$delete = empty($to);
// True for case-sensitive tag search.
$linksToAlter = $this->filterSearch(['searchtags' => $from], true);
foreach($linksToAlter as $key => &$value)
{
$tags = preg_split('/\s+/', trim($value['tags']));
if (($pos = array_search($from, $tags)) !== false) {
if ($delete) {
unset($tags[$pos]); // Remove tag.
} else {
$tags[$pos] = trim($to);
}
$value['tags'] = trim(implode(' ', array_unique($tags)));
$this[$value['id']] = $value;
}
}
return $linksToAlter;
}
/**
* Returns the list of days containing articles (oldest first)
* Output: An array containing days (in format YYYYMMDD).
*/
public function days()
{
$linkDays = array();
foreach ($this->links as $link) {
$linkDays[$link['created']->format('Ymd')] = 0;
}
$linkDays = array_keys($linkDays);
sort($linkDays);
return $linkDays;
}
/**
* Reorder links by creation date (newest first).
*
* Also update the urls and ids mapping arrays.
*
* @param string $order ASC|DESC
*/
public function reorder($order = 'DESC')
{
$order = $order === 'ASC' ? -1 : 1;
// Reorder array by dates.
usort($this->links, function($a, $b) use ($order) {
return $a['created'] < $b['created'] ? 1 * $order : -1 * $order;
});
$this->urls = array();
$this->ids = array();
foreach ($this->links as $key => $link) {
$this->urls[$link['url']] = $key;
$this->ids[$link['id']] = $key;
}
}
/**
* Return the next key for link creation.
* E.g. If the last ID is 597, the next will be 598.
*
* @return int next ID.
*/
public function getNextId()
{
if (!empty($this->ids)) {
return max(array_keys($this->ids)) + 1;
}
return 0;
}
/**
* Returns a link offset in links array from its unique ID.
*
* @param int $id Persistent ID of a link.
*
* @return int Real offset in local array, or null if doesn't exist.
*/
protected function getLinkOffset($id)
{
if (isset($this->ids[$id])) {
return $this->ids[$id];
}
return null;
}
}

448
application/LinkFilter.php Normal file
View file

@ -0,0 +1,448 @@
<?php
/**
* Class LinkFilter.
*
* Perform search and filter operation on link data list.
*/
class LinkFilter
{
/**
* @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 $FILTER_DAY = 'FILTER_DAY';
/**
* @var string Allowed characters for hashtags (regex syntax).
*/
public static $HASHTAG_CHARS = '\p{Pc}\p{N}\p{L}\p{Mn}';
/**
* @var LinkDB all available links.
*/
private $links;
/**
* @param LinkDB $links initialization.
*/
public function __construct($links)
{
$this->links = $links;
}
/**
* Filter links 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 links
* @param string $untaggedonly Optional: return only untagged links. Applies only if $type includes FILTER_TAG
*
* @return array filtered link list.
*/
public function filter($type, $request, $casesensitive = false, $visibility = 'all', $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->links;
}
if (!empty($request[0])) {
$filtered = (new LinkFilter($filtered))->filterTags($request[0], $casesensitive, $visibility);
}
if (!empty($request[1])) {
$filtered = (new LinkFilter($filtered))->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);
}
case self::$FILTER_DAY:
return $this->filterDay($request);
default:
return $this->noFilter($visibility);
}
}
/**
* Unknown filter, but handle private only.
*
* @param string $visibility Optional: return only all/private/public links
*
* @return array filtered links.
*/
private function noFilter($visibility = 'all')
{
if ($visibility === 'all') {
return $this->links;
}
$out = array();
foreach ($this->links as $key => $value) {
if ($value['private'] && $visibility === 'private') {
$out[$key] = $value;
} else if (! $value['private'] && $visibility === 'public') {
$out[$key] = $value;
}
}
return $out;
}
/**
* Returns the shaare corresponding to a smallHash.
*
* @param string $smallHash permalink hash.
*
* @return array $filtered array containing permalink data.
*
* @throws LinkNotFoundException if the smallhash doesn't match any link.
*/
private function filterSmallHash($smallHash)
{
$filtered = array();
foreach ($this->links as $key => $l) {
if ($smallHash == $l['shorturl']) {
// Yes, this is ugly and slow
$filtered[$key] = $l;
return $filtered;
}
}
if (empty($filtered)) {
throw new LinkNotFoundException();
}
return $filtered;
}
/**
* Returns the list of links 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 links.
*
* @return array search results.
*/
private function filterFulltext($searchterms, $visibility = 'all')
{
if (empty($searchterms)) {
return $this->noFilter($visibility);
}
$filtered = array();
$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 = array();
$andSearch = array();
foreach ($explodedSearchAnd as $needle) {
if ($needle[0] == '-' && strlen($needle) > 1) {
$excludeSearch[] = substr($needle, 1);
} else {
$andSearch[] = $needle;
}
}
$keys = array('title', 'description', 'url', 'tags');
// Iterate over every stored link.
foreach ($this->links as $id => $link) {
// ignore non private links when 'privatonly' is on.
if ($visibility !== 'all') {
if (! $link['private'] && $visibility === 'private') {
continue;
} else if ($link['private'] && $visibility === 'public') {
continue;
}
}
// Concatenate link fields to search across fields.
// Adds a '\' separator for exact search terms.
$content = '';
foreach ($keys as $key) {
$content .= mb_convert_case($link[$key], MB_CASE_LOWER, 'UTF-8') . '\\';
}
// Be optimistic
$found = true;
// First, we look for exact term search
for ($i = 0; $i < count($exactSearch) && $found; $i++) {
$found = strpos($content, $exactSearch[$i]) !== false;
}
// Iterate over keywords, if keyword is not found,
// no need to check for the others. We want all or nothing.
for ($i = 0; $i < count($andSearch) && $found; $i++) {
$found = strpos($content, $andSearch[$i]) !== false;
}
// Exclude terms.
for ($i = 0; $i < count($excludeSearch) && $found; $i++) {
$found = strpos($content, $excludeSearch[$i]) === false;
}
if ($found) {
$filtered[$id] = $link;
}
}
return $filtered;
}
/**
* generate a regex fragment out of a tag
* @param string $tag to to generate regexs from. may start with '-' to negate, contain '*' as wildcard
* @return string generated regex fragment
*/
private static function tag2regex($tag)
{
$len = strlen($tag);
if(!$len || $tag === "-" || $tag === "*"){
// nothing to search, return empty regex
return '';
}
if($tag[0] === "-") {
// query is negated
$i = 1; // use offset to start after '-' character
$regex = '(?!'; // create negative lookahead
} else {
$i = 0; // start at first character
$regex = '(?='; // use positive lookahead
}
$regex .= '.*(?:^| )'; // before tag may only be a space or the beginning
// iterate over string, separating it into placeholder and content
for(; $i < $len; $i++){
if($tag[$i] === '*'){
// placeholder found
$regex .= '[^ ]*?';
} 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.
$regex .= preg_quote(substr($tag, $i, $offset - $i + 1), '/');
// move $i on
$i = $offset;
}
}
$regex .= '(?:$| ))'; // after the tag may only be a space or the end
return $regex;
}
/**
* Returns the list of links 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 $tags list of tags separated by commas or blank spaces.
* @param bool $casesensitive ignore case if false.
* @param string $visibility Optional: return only all/private/public links.
*
* @return array filtered links.
*/
public function filterTags($tags, $casesensitive = false, $visibility = 'all')
{
// 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 = preg_split('/(?:\s+)|,/', $inputTags, -1, PREG_SPLIT_NO_EMPTY);
}
if(!count($inputTags)){
// no input tags
return $this->noFilter($visibility);
}
// build regex from all tags
$re = '/^' . implode(array_map("self::tag2regex", $inputTags)) . '.*$/';
if(!$casesensitive) {
// make regex case insensitive
$re .= 'i';
}
// create resulting array
$filtered = array();
// iterate over each link
foreach ($this->links as $key => $link) {
// check level of visibility
// ignore non private links when 'privateonly' is on.
if ($visibility !== 'all') {
if (! $link['private'] && $visibility === 'private') {
continue;
} else if ($link['private'] && $visibility === 'public') {
continue;
}
}
$search = $link['tags']; // build search string, start with tags of current link
if(strlen(trim($link['description'])) && strpos($link['description'], '#') !== false){
// description given and at least one possible tag found
$descTags = array();
// find all tags in the form of #tag in the description
preg_match_all(
'/(?<![' . self::$HASHTAG_CHARS . '])#([' . self::$HASHTAG_CHARS . ']+?)\b/sm',
$link['description'],
$descTags
);
if(count($descTags[1])){
// there were some tags in the description, add them to the search string
$search .= ' ' . implode(' ', $descTags[1]);
}
};
// match regular expression with search string
if(!preg_match($re, $search)){
// this entry does _not_ match our regex
continue;
}
$filtered[$key] = $link;
}
return $filtered;
}
/**
* Return only links without any tag.
*
* @param string $visibility return only all/private/public links.
*
* @return array filtered links.
*/
public function filterUntagged($visibility)
{
$filtered = [];
foreach ($this->links as $key => $link) {
if ($visibility !== 'all') {
if (! $link['private'] && $visibility === 'private') {
continue;
} else if ($link['private'] && $visibility === 'public') {
continue;
}
}
if (empty(trim($link['tags']))) {
$filtered[$key] = $link;
}
}
return $filtered;
}
/**
* Returns the list of articles for a given day, chronologically sorted
*
* Day must be in the form 'YYYYMMDD' (e.g. '20120125'), e.g.
* print_r($mydb->filterDay('20120125'));
*
* @param string $day day to filter.
*
* @return array all link matching given day.
*
* @throws Exception if date format is invalid.
*/
public function filterDay($day)
{
if (! checkDateFormat('Ymd', $day)) {
throw new Exception('Invalid date format');
}
$filtered = array();
foreach ($this->links as $key => $l) {
if ($l['created']->format('Ymd') == $day) {
$filtered[$key] = $l;
}
}
// sort by date ASC
return array_reverse($filtered, true);
}
/**
* 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 array filtered tags string.
*/
public static function tagsStrToArray($tags, $casesensitive)
{
// 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);
}
}
class LinkNotFoundException extends Exception
{
protected $message = 'The link you are trying to reach does not exist or has been deleted.';
}

186
application/LinkUtils.php Normal file
View file

@ -0,0 +1,186 @@
<?php
/**
* 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;
}
/**
* Determine charset from downloaded page.
* Priority:
* 1. HTTP headers (Content type).
* 2. HTML content page (tag <meta charset>).
* 3. Use a default charset (default: UTF-8).
*
* @param array $headers HTTP headers array.
* @param string $htmlContent HTML content where to look for charset.
* @param string $defaultCharset Default charset to apply if other methods failed.
*
* @return string Determined charset.
*/
function get_charset($headers, $htmlContent, $defaultCharset = 'utf-8')
{
if ($charset = headers_extract_charset($headers)) {
return $charset;
}
if ($charset = html_extract_charset($htmlContent)) {
return $charset;
}
return $defaultCharset;
}
/**
* Extract charset from HTTP headers if it's defined.
*
* @param array $headers HTTP headers array.
*
* @return bool|string Charset string if found (lowercase), false otherwise.
*/
function headers_extract_charset($headers)
{
if (! empty($headers['Content-Type']) && strpos($headers['Content-Type'], 'charset=') !== false) {
preg_match('/charset="?([^; ]+)/i', $headers['Content-Type'], $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;
}
/**
* Count private links in given linklist.
*
* @param array|Countable $links Linklist.
*
* @return int Number of private links.
*/
function count_private($links)
{
$cpt = 0;
foreach ($links as $link) {
if ($link['private']) {
$cpt += 1;
}
}
return $cpt;
}
/**
* In a string, converts URLs to clickable links.
*
* @param string $text input string.
* @param string $redirector if a redirector is set, use it to gerenate links.
*
* @return string returns $text with all links converted to HTML links.
*
* @see Function inspired from http://www.php.net/manual/en/function.preg-replace.php#85722
*/
function text2clickable($text, $redirector = '')
{
$regex = '!(((?:https?|ftp|file)://|apt:|magnet:)\S+[a-z0-9\(\)]/?)!si';
if (empty($redirector)) {
return preg_replace($regex, '<a href="$1">$1</a>', $text);
}
// Redirector is set, urlencode the final URL.
return preg_replace_callback(
$regex,
function ($matches) use ($redirector) {
return '<a href="' . $redirector . urlencode($matches[1]) .'">'. $matches[1] .'</a>';
},
$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 = '')
{
/*
* 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}]+)/mui';
$replacement = '$1<a href="'. $indexUrl .'?addtag=$2" title="Hashtag $2">#$2</a>';
return preg_replace($regex, $replacement, $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 $redirector if a redirector is set, use it to gerenate links.
* @param string $indexUrl URL to Shaarli's index.
*
* @return string formatted description.
*/
function format_description($description, $redirector = '', $indexUrl = '') {
return nl2br(space2nbsp(hashtag_autolink(text2clickable($description, $redirector), $indexUrl)));
}
/**
* 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(LinkDB::LINK_DATE_FORMAT) . $id);
}

211
application/NetscapeBookmarkUtils.php Normal file
View file

@ -0,0 +1,211 @@
<?php
use Psr\Log\LogLevel;
use Shaarli\Config\ConfigManager;
use Shaarli\NetscapeBookmarkParser\NetscapeBookmarkParser;
use Katzgrau\KLogger\Logger;
/**
* Utilities to import and export bookmarks using the Netscape format
* TODO: Not static, use a container.
*/
class NetscapeBookmarkUtils
{
/**
* Filters links and adds Netscape-formatted fields
*
* Added fields:
* - timestamp link addition date, using the Unix epoch format
* - taglist comma-separated tag list
*
* @param LinkDB $linkDb Link datastore
* @param string $selection Which links to export: (all|private|public)
* @param bool $prependNoteUrl Prepend note permalinks with the server's URL
* @param string $indexUrl Absolute URL of the Shaarli index page
*
* @throws Exception Invalid export selection
*
* @return array The links to be exported, with additional fields
*/
public static function filterAndFormat($linkDb, $selection, $prependNoteUrl, $indexUrl)
{
// see tpl/export.html for possible values
if (! in_array($selection, array('all', 'public', 'private'))) {
throw new Exception('Invalid export selection: "'.$selection.'"');
}
$bookmarkLinks = array();
foreach ($linkDb as $link) {
if ($link['private'] != 0 && $selection == 'public') {
continue;
}
if ($link['private'] == 0 && $selection == 'private') {
continue;
}
$date = $link['created'];
$link['timestamp'] = $date->getTimestamp();
$link['taglist'] = str_replace(' ', ',', $link['tags']);
if (startsWith($link['url'], '?') && $prependNoteUrl) {
$link['url'] = $indexUrl . $link['url'];
}
$bookmarkLinks[] = $link;
}
return $bookmarkLinks;
}
/**
* Generates an import status summary
*
* @param string $filename name of the file to import
* @param int $filesize size of the file to import
* @param int $importCount how many links were imported
* @param int $overwriteCount how many links were overwritten
* @param int $skipCount how many links were skipped
*
* @return string Summary of the bookmark import status
*/
private static function importStatus(
$filename,
$filesize,
$importCount=0,
$overwriteCount=0,
$skipCount=0
)
{
$status = 'File '.$filename.' ('.$filesize.' bytes) ';
if ($importCount == 0 && $overwriteCount == 0 && $skipCount == 0) {
$status .= 'has an unknown file format. Nothing was imported.';
} else {
$status .= 'was successfully processed: '.$importCount.' links imported, ';
$status .= $overwriteCount.' links overwritten, ';
$status .= $skipCount.' links skipped.';
}
return $status;
}
/**
* Imports Web bookmarks from an uploaded Netscape bookmark dump
*
* @param array $post Server $_POST parameters
* @param array $files Server $_FILES parameters
* @param LinkDB $linkDb Loaded LinkDB instance
* @param ConfigManager $conf instance
* @param History $history History instance
*
* @return string Summary of the bookmark import status
*/
public static function import($post, $files, $linkDb, $conf, $history)
{
$filename = $files['filetoupload']['name'];
$filesize = $files['filetoupload']['size'];
$data = file_get_contents($files['filetoupload']['tmp_name']);
if (strpos($data, '<!DOCTYPE NETSCAPE-Bookmark-file-1>') === false) {
return self::importStatus($filename, $filesize);
}
// Overwrite existing links?
$overwrite = ! empty($post['overwrite']);
// Add tags to all imported links?
if (empty($post['default_tags'])) {
$defaultTags = array();
} else {
$defaultTags = preg_split(
'/[\s,]+/',
escape($post['default_tags'])
);
}
// links are imported as public by default
$defaultPrivacy = 0;
$parser = new NetscapeBookmarkParser(
true, // nested tag support
$defaultTags, // additional user-specified tags
strval(1 - $defaultPrivacy), // defaultPub = 1 - defaultPrivacy
$conf->get('resource.data_dir') // log path, will be overridden
);
$logger = new Logger(
$conf->get('resource.data_dir'),
! $conf->get('dev.debug') ? LogLevel::INFO : LogLevel::DEBUG,
[
'prefix' => 'import.',
'extension' => 'log',
]
);
$parser->setLogger($logger);
$bookmarks = $parser->parseString($data);
$importCount = 0;
$overwriteCount = 0;
$skipCount = 0;
foreach ($bookmarks as $bkm) {
$private = $defaultPrivacy;
if (empty($post['privacy']) || $post['privacy'] == 'default') {
// use value from the imported file
$private = $bkm['pub'] == '1' ? 0 : 1;
} else if ($post['privacy'] == 'private') {
// all imported links are private
$private = 1;
} else if ($post['privacy'] == 'public') {
// all imported links are public
$private = 0;
}
$newLink = array(
'title' => $bkm['title'],
'url' => $bkm['uri'],
'description' => $bkm['note'],
'private' => $private,
'tags' => $bkm['tags']
);
$existingLink = $linkDb->getLinkFromUrl($bkm['uri']);
if ($existingLink !== false) {
if ($overwrite === false) {
// Do not overwrite an existing link
$skipCount++;
continue;
}
// Overwrite an existing link, keep its date
$newLink['id'] = $existingLink['id'];
$newLink['created'] = $existingLink['created'];
$newLink['updated'] = new DateTime();
$newLink['shorturl'] = $existingLink['shorturl'];
$linkDb[$existingLink['id']] = $newLink;
$importCount++;
$overwriteCount++;
$history->updateLink($newLink);
continue;
}
// Add a new link - @ used for UNIX timestamps
$newLinkDate = new DateTime('@'.strval($bkm['time']));
$newLinkDate->setTimezone(new DateTimeZone(date_default_timezone_get()));
$newLink['created'] = $newLinkDate;
$newLink['id'] = $linkDb->getNextId();
$newLink['shorturl'] = link_small_hash($newLink['created'], $newLink['id']);
$linkDb[$newLink['id']] = $newLink;
$importCount++;
$history->addLink($newLink);
}
$linkDb->save($conf->get('resource.page_cache'));
return self::importStatus(
$filename,
$filesize,
$importCount,
$overwriteCount,
$skipCount
);
}
}

168
application/PageBuilder.php Normal file
View file

@ -0,0 +1,168 @@
<?php
use Shaarli\Config\ConfigManager;
/**
* This class is in charge of building the final page.
* (This is basically a wrapper around RainTPL which pre-fills some fields.)
* $p = new PageBuilder();
* $p->assign('myfield','myvalue');
* $p->renderPage('mytemplate');
*/
class PageBuilder
{
/**
* @var RainTPL RainTPL instance.
*/
private $tpl;
/**
* @var ConfigManager $conf Configuration Manager instance.
*/
protected $conf;
/**
* @var LinkDB $linkDB instance.
*/
protected $linkDB;
/**
* PageBuilder constructor.
* $tpl is initialized at false for lazy loading.
*
* @param ConfigManager $conf Configuration Manager instance (reference).
* @param LinkDB $linkDB instance.
*/
public function __construct(&$conf, $linkDB = null)
{
$this->tpl = false;
$this->conf = $conf;
$this->linkDB = $linkDB;
}
/**
* Initialize all default tpl tags.
*/
private function initialize()
{
$this->tpl = new RainTPL();
try {
$version = ApplicationUtils::checkUpdate(
SHAARLI_VERSION,
$this->conf->get('resource.update_check'),
$this->conf->get('updates.check_updates_interval'),
$this->conf->get('updates.check_updates'),
isLoggedIn(),
$this->conf->get('updates.check_updates_branch')
);
$this->tpl->assign('newVersion', escape($version));
$this->tpl->assign('versionError', '');
} catch (Exception $exc) {
logm($this->conf->get('resource.log'), $_SERVER['REMOTE_ADDR'], $exc->getMessage());
$this->tpl->assign('newVersion', '');
$this->tpl->assign('versionError', escape($exc->getMessage()));
}
$this->tpl->assign('feedurl', escape(index_url($_SERVER)));
$searchcrits = ''; // Search criteria
if (!empty($_GET['searchtags'])) {
$searchcrits .= '&searchtags=' . urlencode($_GET['searchtags']);
}
if (!empty($_GET['searchterm'])) {
$searchcrits .= '&searchterm=' . urlencode($_GET['searchterm']);
}
$this->tpl->assign('searchcrits', $searchcrits);
$this->tpl->assign('source', index_url($_SERVER));
$this->tpl->assign('version', SHAARLI_VERSION);
$this->tpl->assign(
'version_hash',
ApplicationUtils::getVersionHash(SHAARLI_VERSION, $this->conf->get('credentials.salt'))
);
$this->tpl->assign('scripturl', index_url($_SERVER));
$this->tpl->assign('privateonly', !empty($_SESSION['privateonly'])); // Show only private links?
$this->tpl->assign('untaggedonly', !empty($_SESSION['untaggedonly']));
$this->tpl->assign('pagetitle', $this->conf->get('general.title', 'Shaarli'));
if ($this->conf->exists('general.header_link')) {
$this->tpl->assign('titleLink', $this->conf->get('general.header_link'));
}
$this->tpl->assign('shaarlititle', $this->conf->get('general.title', 'Shaarli'));
$this->tpl->assign('openshaarli', $this->conf->get('security.open_shaarli', false));
$this->tpl->assign('showatom', $this->conf->get('feed.show_atom', true));
$this->tpl->assign('feed_type', $this->conf->get('feed.show_atom', true) !== false ? 'atom' : 'rss');
$this->tpl->assign('hide_timestamps', $this->conf->get('privacy.hide_timestamps', false));
$this->tpl->assign('token', getToken($this->conf));
if ($this->linkDB !== null) {
$this->tpl->assign('tags', $this->linkDB->linksCountPerTag());
}
// To be removed with a proper theme configuration.
$this->tpl->assign('conf', $this->conf);
}
/**
* The following assign() method is basically the same as RainTPL (except lazy loading)
*
* @param string $placeholder Template placeholder.
* @param mixed $value Value to assign.
*/
public function assign($placeholder, $value)
{
if ($this->tpl === false) {
$this->initialize();
}
$this->tpl->assign($placeholder, $value);
}
/**
* Assign an array of data to the template builder.
*
* @param array $data Data to assign.
*
* @return false if invalid data.
*/
public function assignAll($data)
{
if ($this->tpl === false) {
$this->initialize();
}
if (empty($data) || !is_array($data)){
return false;
}
foreach ($data as $key => $value) {
$this->assign($key, $value);
}
return true;
}
/**
* Render a specific page (using a template file).
* e.g. $pb->renderPage('picwall');
*
* @param string $page Template filename (without extension).
*/
public function renderPage($page)
{
if ($this->tpl === false) {
$this->initialize();
}
$this->tpl->draw($page);
}
/**
* Render a 404 page (uses the template : tpl/404.tpl)
* usage : $PAGE->render404('The link was deleted')
*
* @param string $message A messate to display what is not found
*/
public function render404($message = 'The page you are trying to reach does not exist or has been deleted.')
{
header($_SERVER['SERVER_PROTOCOL'] . ' 404 Not Found');
$this->tpl->assign('error_message', $message);
$this->renderPage('404');
}
}

242
application/PluginManager.php Normal file
View file

@ -0,0 +1,242 @@
<?php
/**
* Class PluginManager
*
* Use to manage, load and execute plugins.
*/
class PluginManager
{
/**
* List of authorized plugins from configuration file.
* @var array $authorizedPlugins
*/
private $authorizedPlugins;
/**
* List of loaded plugins.
* @var array $loadedPlugins
*/
private $loadedPlugins = array();
/**
* @var ConfigManager Configuration Manager instance.
*/
protected $conf;
/**
* @var array List of plugin errors.
*/
protected $errors;
/**
* Plugins subdirectory.
* @var string $PLUGINS_PATH
*/
public static $PLUGINS_PATH = 'plugins';
/**
* Plugins meta files extension.
* @var string $META_EXT
*/
public static $META_EXT = 'meta';
/**
* Constructor.
*
* @param ConfigManager $conf Configuration Manager instance.
*/
public function __construct(&$conf)
{
$this->conf = $conf;
$this->errors = array();
}
/**
* Load plugins listed in $authorizedPlugins.
*
* @param array $authorizedPlugins Names of plugin authorized to be loaded.
*
* @return void
*/
public function load($authorizedPlugins)
{
$this->authorizedPlugins = $authorizedPlugins;
$dirs = glob(self::$PLUGINS_PATH . '/*', GLOB_ONLYDIR);
$dirnames = array_map('basename', $dirs);
foreach ($this->authorizedPlugins as $plugin) {
$index = array_search($plugin, $dirnames);
// plugin authorized, but its folder isn't listed
if ($index === false) {
continue;
}
try {
$this->loadPlugin($dirs[$index], $plugin);
}
catch (PluginFileNotFoundException $e) {
error_log($e->getMessage());
}
}
}
/**
* Execute all plugins registered hook.
*
* @param string $hook name of the hook to trigger.
* @param array $data list of data to manipulate passed by reference.
* @param array $params additional parameters such as page target.
*
* @return void
*/
public function executeHooks($hook, &$data, $params = array())
{
if (!empty($params['target'])) {
$data['_PAGE_'] = $params['target'];
}
if (isset($params['loggedin'])) {
$data['_LOGGEDIN_'] = $params['loggedin'];
}
foreach ($this->loadedPlugins as $plugin) {
$hookFunction = $this->buildHookName($hook, $plugin);
if (function_exists($hookFunction)) {
$data = call_user_func($hookFunction, $data, $this->conf);
}
}
}
/**
* Load a single plugin from its files.
* Call the init function if it exists, and collect errors.
* Add them in $loadedPlugins if successful.
*
* @param string $dir plugin's directory.
* @param string $pluginName plugin's name.
*
* @return void
* @throws PluginFileNotFoundException - plugin files not found.
*/
private function loadPlugin($dir, $pluginName)
{
if (!is_dir($dir)) {
throw new PluginFileNotFoundException($pluginName);
}
$pluginFilePath = $dir . '/' . $pluginName . '.php';
if (!is_file($pluginFilePath)) {
throw new PluginFileNotFoundException($pluginName);
}
$conf = $this->conf;
include_once $pluginFilePath;
$initFunction = $pluginName . '_init';
if (function_exists($initFunction)) {
$errors = call_user_func($initFunction, $this->conf);
if (!empty($errors)) {
$this->errors = array_merge($this->errors, $errors);
}
}
$this->loadedPlugins[] = $pluginName;
}
/**
* Construct normalize hook name for a specific plugin.
*
* Format:
* hook_<plugin_name>_<hook_name>
*
* @param string $hook hook name.
* @param string $pluginName plugin name.
*
* @return string - plugin's hook name.
*/
public function buildHookName($hook, $pluginName)
{
return 'hook_' . $pluginName . '_' . $hook;
}
/**
* Retrieve plugins metadata from *.meta (INI) files into an array.
* Metadata contains:
* - plugin description [description]
* - parameters split with ';' [parameters]
*
* Respects plugins order from settings.
*
* @return array plugins metadata.
*/
public function getPluginsMeta()
{
$metaData = array();
$dirs = glob(self::$PLUGINS_PATH . '/*', GLOB_ONLYDIR | GLOB_MARK);
// Browse all plugin directories.
foreach ($dirs as $pluginDir) {
$plugin = basename($pluginDir);
$metaFile = $pluginDir . $plugin . '.' . self::$META_EXT;
if (!is_file($metaFile) || !is_readable($metaFile)) {
continue;
}
$metaData[$plugin] = parse_ini_file($metaFile);
$metaData[$plugin]['order'] = array_search($plugin, $this->authorizedPlugins);
// Read parameters and format them into an array.
if (isset($metaData[$plugin]['parameters'])) {
$params = explode(';', $metaData[$plugin]['parameters']);
} else {
$params = array();
}
$metaData[$plugin]['parameters'] = array();
foreach ($params as $param) {
if (empty($param)) {
continue;
}
$metaData[$plugin]['parameters'][$param]['value'] = '';
// Optional parameter description in parameter.PARAM_NAME=
if (isset($metaData[$plugin]['parameter.'. $param])) {
$metaData[$plugin]['parameters'][$param]['desc'] = $metaData[$plugin]['parameter.'. $param];
}
}
}
return $metaData;
}
/**
* Return the list of encountered errors.
*
* @return array List of errors (empty array if none exists).
*/
public function getErrors()
{
return $this->errors;
}
}
/**
* Class PluginFileNotFoundException
*
* Raise when plugin files can't be found.
*/
class PluginFileNotFoundException extends Exception
{
/**
* Construct exception with plugin name.
* Generate message.
*
* @param string $pluginName name of the plugin not found
*/
public function __construct($pluginName)
{
$this->message = 'Plugin "'. $pluginName .'" files not found.';
}
}

159
application/Router.php Normal file
View file

@ -0,0 +1,159 @@
<?php
/**
* Class Router
*
* (only displayable pages here)
*/
class Router
{
public static $PAGE_LOGIN = 'login';
public static $PAGE_PICWALL = 'picwall';
public static $PAGE_TAGCLOUD = 'tagcloud';
public static $PAGE_TAGLIST = 'taglist';
public static $PAGE_DAILY = 'daily';
public static $PAGE_FEED_ATOM = 'atom';
public static $PAGE_FEED_RSS = 'rss';
public static $PAGE_TOOLS = 'tools';
public static $PAGE_CHANGEPASSWORD = 'changepasswd';
public static $PAGE_CONFIGURE = 'configure';
public static $PAGE_CHANGETAG = 'changetag';
public static $PAGE_ADDLINK = 'addlink';
public static $PAGE_EDITLINK = 'edit_link';
public static $PAGE_DELETELINK = 'delete_link';
public static $PAGE_EXPORT = 'export';
public static $PAGE_IMPORT = 'import';
public static $PAGE_OPENSEARCH = 'opensearch';
public static $PAGE_LINKLIST = 'linklist';
public static $PAGE_PLUGINSADMIN = 'pluginadmin';
public static $PAGE_SAVE_PLUGINSADMIN = 'save_pluginadmin';
public static $GET_TOKEN = 'token';
/**
* Reproducing renderPage() if hell, to avoid regression.
*
* This highlights how bad this needs to be rewrite,
* but let's focus on plugins for now.
*
* @param string $query $_SERVER['QUERY_STRING'].
* @param array $get $_SERVER['GET'].
* @param bool $loggedIn true if authenticated user.
*
* @return string page found.
*/
public static function findPage($query, $get, $loggedIn)
{
$loggedIn = ($loggedIn === true) ? true : false;
if (empty($query) && !isset($get['edit_link']) && !isset($get['post'])) {
return self::$PAGE_LINKLIST;
}
if (startsWith($query, 'do='. self::$PAGE_LOGIN) && $loggedIn === false) {
return self::$PAGE_LOGIN;
}
if (startsWith($query, 'do='. self::$PAGE_PICWALL)) {
return self::$PAGE_PICWALL;
}
if (startsWith($query, 'do='. self::$PAGE_TAGCLOUD)) {
return self::$PAGE_TAGCLOUD;
}
if (startsWith($query, 'do='. self::$PAGE_TAGLIST)) {
return self::$PAGE_TAGLIST;
}
if (startsWith($query, 'do='. self::$PAGE_OPENSEARCH)) {
return self::$PAGE_OPENSEARCH;
}
if (startsWith($query, 'do='. self::$PAGE_DAILY)) {
return self::$PAGE_DAILY;
}
if (startsWith($query, 'do='. self::$PAGE_FEED_ATOM)) {
return self::$PAGE_FEED_ATOM;
}
if (startsWith($query, 'do='. self::$PAGE_FEED_RSS)) {
return self::$PAGE_FEED_RSS;
}
// At this point, only loggedin pages.
if (!$loggedIn) {
return self::$PAGE_LINKLIST;
}
if (startsWith($query, 'do='. self::$PAGE_TOOLS)) {
return self::$PAGE_TOOLS;
}
if (startsWith($query, 'do='. self::$PAGE_CHANGEPASSWORD)) {
return self::$PAGE_CHANGEPASSWORD;
}
if (startsWith($query, 'do='. self::$PAGE_CONFIGURE)) {
return self::$PAGE_CONFIGURE;
}
if (startsWith($query, 'do='. self::$PAGE_CHANGETAG)) {
return self::$PAGE_CHANGETAG;
}
if (startsWith($query, 'do='. self::$PAGE_ADDLINK)) {
return self::$PAGE_ADDLINK;
}
if (isset($get['edit_link']) || isset($get['post'])) {
return self::$PAGE_EDITLINK;
}
if (isset($get['delete_link'])) {
return self::$PAGE_DELETELINK;
}
if (startsWith($query, 'do='. self::$PAGE_EXPORT)) {
return self::$PAGE_EXPORT;
}
if (startsWith($query, 'do='. self::$PAGE_IMPORT)) {
return self::$PAGE_IMPORT;
}
if (startsWith($query, 'do='. self::$PAGE_PLUGINSADMIN)) {
return self::$PAGE_PLUGINSADMIN;
}
if (startsWith($query, 'do='. self::$PAGE_SAVE_PLUGINSADMIN)) {
return self::$PAGE_SAVE_PLUGINSADMIN;
}
if (startsWith($query, 'do='. self::$GET_TOKEN)) {
return self::$GET_TOKEN;
}
return self::$PAGE_LINKLIST;
}
}

34
application/ThemeUtils.php Normal file
View file

@ -0,0 +1,34 @@
<?php
namespace Shaarli;
/**
* Class ThemeUtils
*
* Utility functions related to theme management.
*
* @package Shaarli
*/
class ThemeUtils
{
/**
* Get a list of available themes.
*
* It will return the name of any directory present in the template folder.
*
* @param string $tplDir Templates main directory.
*
* @return array List of theme names.
*/
public static function getThemes($tplDir)
{
$tplDir = rtrim($tplDir, '/');
$allTheme = glob($tplDir.'/*', GLOB_ONLYDIR);
$themes = [];
foreach ($allTheme as $value) {
$themes[] = str_replace($tplDir.'/', '', $value);
}
return $themes;
}
}

91
application/TimeZone.php Normal file
View file

@ -0,0 +1,91 @@
<?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()
);
}

532
application/Updater.php Normal file
View file

@ -0,0 +1,532 @@
<?php
use Shaarli\Config\ConfigJson;
use Shaarli\Config\ConfigPhp;
use Shaarli\Config\ConfigManager;
/**
* Class Updater.
* Used to update stuff when a new Shaarli's version is reached.
* Update methods are ran only once, and the stored in a JSON file.
*/
class Updater
{
/**
* @var array Updates which are already done.
*/
protected $doneUpdates;
/**
* @var LinkDB instance.
*/
protected $linkDB;
/**
* @var ConfigManager $conf Configuration Manager instance.
*/
protected $conf;
/**
* @var bool True if the user is logged in, false otherwise.
*/
protected $isLoggedIn;
/**
* @var ReflectionMethod[] List of current class methods.
*/
protected $methods;
/**
* Object constructor.
*
* @param array $doneUpdates Updates which are already done.
* @param LinkDB $linkDB LinkDB instance.
* @param ConfigManager $conf Configuration Manager instance.
* @param boolean $isLoggedIn True if the user is logged in.
*/
public function __construct($doneUpdates, $linkDB, $conf, $isLoggedIn)
{
$this->doneUpdates = $doneUpdates;
$this->linkDB = $linkDB;
$this->conf = $conf;
$this->isLoggedIn = $isLoggedIn;
// Retrieve all update methods.
$class = new ReflectionClass($this);
$this->methods = $class->getMethods();
}
/**
* Run all new updates.
* Update methods have to start with 'updateMethod' and return true (on success).
*
* @return array An array containing ran updates.
*
* @throws UpdaterException If something went wrong.
*/
public function update()
{
$updatesRan = array();
// If the user isn't logged in, exit without updating.
if ($this->isLoggedIn !== true) {
return $updatesRan;
}
if ($this->methods === null) {
throw new UpdaterException('Couldn\'t retrieve Updater class methods.');
}
foreach ($this->methods as $method) {
// Not an update method or already done, pass.
if (! startsWith($method->getName(), 'updateMethod')
|| in_array($method->getName(), $this->doneUpdates)
) {
continue;
}
try {
$method->setAccessible(true);
$res = $method->invoke($this);
// Update method must return true to be considered processed.
if ($res === true) {
$updatesRan[] = $method->getName();
}
} catch (Exception $e) {
throw new UpdaterException($method, $e);
}
}
$this->doneUpdates = array_merge($this->doneUpdates, $updatesRan);
return $updatesRan;
}
/**
* @return array Updates methods already processed.
*/
public function getDoneUpdates()
{
return $this->doneUpdates;
}
/**
* Move deprecated options.php to config.php.
*
* Milestone 0.9 (old versioning) - shaarli/Shaarli#41:
* options.php is not supported anymore.
*/
public function updateMethodMergeDeprecatedConfigFile()
{
if (is_file($this->conf->get('resource.data_dir') . '/options.php')) {
include $this->conf->get('resource.data_dir') . '/options.php';
// Load GLOBALS into config
$allowedKeys = array_merge(ConfigPhp::$ROOT_KEYS);
$allowedKeys[] = 'config';
foreach ($GLOBALS as $key => $value) {
if (in_array($key, $allowedKeys)) {
$this->conf->set($key, $value);
}
}
$this->conf->write($this->isLoggedIn);
unlink($this->conf->get('resource.data_dir').'/options.php');
}
return true;
}
/**
* Move old configuration in PHP to the new config system in JSON format.
*
* Will rename 'config.php' into 'config.save.php' and create 'config.json.php'.
* It will also convert legacy setting keys to the new ones.
*/
public function updateMethodConfigToJson()
{
// JSON config already exists, nothing to do.
if ($this->conf->getConfigIO() instanceof ConfigJson) {
return true;
}
$configPhp = new ConfigPhp();
$configJson = new ConfigJson();
$oldConfig = $configPhp->read($this->conf->getConfigFile() . '.php');
rename($this->conf->getConfigFileExt(), $this->conf->getConfigFile() . '.save.php');
$this->conf->setConfigIO($configJson);
$this->conf->reload();
$legacyMap = array_flip(ConfigPhp::$LEGACY_KEYS_MAPPING);
foreach (ConfigPhp::$ROOT_KEYS as $key) {
$this->conf->set($legacyMap[$key], $oldConfig[$key]);
}
// Set sub config keys (config and plugins)
$subConfig = array('config', 'plugins');
foreach ($subConfig as $sub) {
foreach ($oldConfig[$sub] as $key => $value) {
if (isset($legacyMap[$sub .'.'. $key])) {
$configKey = $legacyMap[$sub .'.'. $key];
} else {
$configKey = $sub .'.'. $key;
}
$this->conf->set($configKey, $value);
}
}
try{
$this->conf->write($this->isLoggedIn);
return true;
} catch (IOException $e) {
error_log($e->getMessage());
return false;
}
}
/**
* Escape settings which have been manually escaped in every request in previous versions:
* - general.title
* - general.header_link
* - redirector.url
*
* @return bool true if the update is successful, false otherwise.
*/
public function updateMethodEscapeUnescapedConfig()
{
try {
$this->conf->set('general.title', escape($this->conf->get('general.title')));
$this->conf->set('general.header_link', escape($this->conf->get('general.header_link')));
$this->conf->set('redirector.url', escape($this->conf->get('redirector.url')));
$this->conf->write($this->isLoggedIn);
} catch (Exception $e) {
error_log($e->getMessage());
return false;
}
return true;
}
/**
* Update the database to use the new ID system, which replaces linkdate primary keys.
* Also, creation and update dates are now DateTime objects (done by LinkDB).
*
* Since this update is very sensitve (changing the whole database), the datastore will be
* automatically backed up into the file datastore.<datetime>.php.
*
* LinkDB also adds the field 'shorturl' with the precedent format (linkdate smallhash),
* which will be saved by this method.
*
* @return bool true if the update is successful, false otherwise.
*/
public function updateMethodDatastoreIds()
{
// up to date database
if (isset($this->linkDB[0])) {
return true;
}
$save = $this->conf->get('resource.data_dir') .'/datastore.'. date('YmdHis') .'.php';
copy($this->conf->get('resource.datastore'), $save);
$links = array();
foreach ($this->linkDB as $offset => $value) {
$links[] = $value;
unset($this->linkDB[$offset]);
}
$links = array_reverse($links);
$cpt = 0;
foreach ($links as $l) {
unset($l['linkdate']);
$l['id'] = $cpt;
$this->linkDB[$cpt++] = $l;
}
$this->linkDB->save($this->conf->get('resource.page_cache'));
$this->linkDB->reorder();
return true;
}
/**
* Rename tags starting with a '-' to work with tag exclusion search.
*/
public function updateMethodRenameDashTags()
{
$linklist = $this->linkDB->filterSearch();
foreach ($linklist as $key => $link) {
$link['tags'] = preg_replace('/(^| )\-/', '$1', $link['tags']);
$link['tags'] = implode(' ', array_unique(LinkFilter::tagsStrToArray($link['tags'], true)));
$this->linkDB[$key] = $link;
}
$this->linkDB->save($this->conf->get('resource.page_cache'));
return true;
}
/**
* Initialize API settings:
* - api.enabled: true
* - api.secret: generated secret
*/
public function updateMethodApiSettings()
{
if ($this->conf->exists('api.secret')) {
return true;
}
$this->conf->set('api.enabled', true);
$this->conf->set(
'api.secret',
generate_api_secret(
$this->conf->get('credentials.login'),
$this->conf->get('credentials.salt')
)
);
$this->conf->write($this->isLoggedIn);
return true;
}
/**
* New setting: theme name. If the default theme is used, nothing to do.
*
* If the user uses a custom theme, raintpl_tpl dir is updated to the parent directory,
* and the current theme is set as default in the theme setting.
*
* @return bool true if the update is successful, false otherwise.
*/
public function updateMethodDefaultTheme()
{
// raintpl_tpl isn't the root template directory anymore.
// We run the update only if this folder still contains the template files.
$tplDir = $this->conf->get('resource.raintpl_tpl');
$tplFile = $tplDir . '/linklist.html';
if (! file_exists($tplFile)) {
return true;
}
$parent = dirname($tplDir);
$this->conf->set('resource.raintpl_tpl', $parent);
$this->conf->set('resource.theme', trim(str_replace($parent, '', $tplDir), '/'));
$this->conf->write($this->isLoggedIn);
// Dependency injection gore
RainTPL::$tpl_dir = $tplDir;
return true;
}
/**
* Move the file to inc/user.css to data/user.css.
*
* Note: Due to hardcoded paths, it's not unit testable. But one line of code should be fine.
*
* @return bool true if the update is successful, false otherwise.
*/
public function updateMethodMoveUserCss()
{
if (! is_file('inc/user.css')) {
return true;
}
return rename('inc/user.css', 'data/user.css');
}
/**
* * `markdown_escape` is a new setting, set to true as default.
*
* If the markdown plugin was already enabled, escaping is disabled to avoid
* breaking existing entries.
*/
public function updateMethodEscapeMarkdown()
{
if ($this->conf->exists('security.markdown_escape')) {
return true;
}
if (in_array('markdown', $this->conf->get('general.enabled_plugins'))) {
$this->conf->set('security.markdown_escape', false);
} else {
$this->conf->set('security.markdown_escape', true);
}
$this->conf->write($this->isLoggedIn);
return true;
}
/**
* Add 'http://' to Piwik URL the setting is set.
*
* @return bool true if the update is successful, false otherwise.
*/
public function updateMethodPiwikUrl()
{
if (! $this->conf->exists('plugins.PIWIK_URL') || startsWith($this->conf->get('plugins.PIWIK_URL'), 'http')) {
return true;
}
$this->conf->set('plugins.PIWIK_URL', 'http://'. $this->conf->get('plugins.PIWIK_URL'));
$this->conf->write($this->isLoggedIn);
return true;
}
/**
* Use ATOM feed as default.
*/
public function updateMethodAtomDefault()
{
if (!$this->conf->exists('feed.show_atom') || $this->conf->get('feed.show_atom') === true) {
return true;
}
$this->conf->set('feed.show_atom', true);
$this->conf->write($this->isLoggedIn);
return true;
}
/**
* Update updates.check_updates_branch setting.
*
* If the current major version digit matches the latest branch
* major version digit, we set the branch to `latest`,
* otherwise we'll check updates on the `stable` branch.
*
* No update required for the dev version.
*
* Note: due to hardcoded URL and lack of dependency injection, this is not unit testable.
*
* FIXME! This needs to be removed when we switch to first digit major version
* instead of the second one since the versionning process will change.
*/
public function updateMethodCheckUpdateRemoteBranch()
{
if (SHAARLI_VERSION === 'dev' || $this->conf->get('updates.check_updates_branch') === 'latest') {
return true;
}
// Get latest branch major version digit
$latestVersion = ApplicationUtils::getLatestGitVersionCode(
'https://raw.githubusercontent.com/shaarli/Shaarli/latest/shaarli_version.php',
5
);
if (preg_match('/(\d+)\.\d+$/', $latestVersion, $matches) === false) {
return false;
}
$latestMajor = $matches[1];
// Get current major version digit
preg_match('/(\d+)\.\d+$/', SHAARLI_VERSION, $matches);
$currentMajor = $matches[1];
if ($currentMajor === $latestMajor) {
$branch = 'latest';
} else {
$branch = 'stable';
}
$this->conf->set('updates.check_updates_branch', $branch);
$this->conf->write($this->isLoggedIn);
return true;
}
/**
* Reset history store file due to date format change.
*/
public function updateMethodResetHistoryFile()
{
if (is_file($this->conf->get('resource.history'))) {
unlink($this->conf->get('resource.history'));
}
return true;
}
}
/**
* Class UpdaterException.
*/
class UpdaterException extends Exception
{
/**
* @var string Method where the error occurred.
*/
protected $method;
/**
* @var Exception The parent exception.
*/
protected $previous;
/**
* Constructor.
*
* @param string $message Force the error message if set.
* @param string $method Method where the error occurred.
* @param Exception|bool $previous Parent exception.
*/
public function __construct($message = '', $method = '', $previous = false)
{
$this->method = $method;
$this->previous = $previous;
$this->message = $this->buildMessage($message);
}
/**
* Build the exception error message.
*
* @param string $message Optional given error message.
*
* @return string The built error message.
*/
private function buildMessage($message)
{
$out = '';
if (! empty($message)) {
$out .= $message . PHP_EOL;
}
if (! empty($this->method)) {
$out .= 'An error occurred while running the update '. $this->method . PHP_EOL;
}
if (! empty($this->previous)) {
$out .= ' '. $this->previous->getMessage();
}
return $out;
}
}
/**
* Read the updates file, and return already done updates.
*
* @param string $updatesFilepath Updates file path.
*
* @return array Already done update methods.
*/
function read_updates_file($updatesFilepath)
{
if (! empty($updatesFilepath) && is_file($updatesFilepath)) {
$content = file_get_contents($updatesFilepath);
if (! empty($content)) {
return explode(';', $content);
}
}
return array();
}
/**
* Write updates file.
*
* @param string $updatesFilepath Updates file path.
* @param array $updates Updates array to write.
*
* @throws Exception Couldn't write version number.
*/
function write_updates_file($updatesFilepath, $updates)
{
if (empty($updatesFilepath)) {
throw new Exception('Updates file path is not set, can\'t write updates.');
}
$res = file_put_contents($updatesFilepath, implode(';', $updates));
if ($res === false) {
throw new Exception('Unable to write updates in '. $updatesFilepath . '.');
}
}

299
application/Url.php Normal file
View file

@ -0,0 +1,299 @@
<?php
/**
* Converts an array-represented URL to a string
*
* Source: http://php.net/manual/en/function.parse-url.php#106731
*
* @see http://php.net/manual/en/function.parse-url.php
*
* @param array $parsedUrl an array-represented URL
*
* @return string the string representation of the URL
*/
function unparse_url($parsedUrl)
{
$scheme = isset($parsedUrl['scheme']) ? $parsedUrl['scheme'].'://' : '';
$host = isset($parsedUrl['host']) ? $parsedUrl['host'] : '';
$port = isset($parsedUrl['port']) ? ':'.$parsedUrl['port'] : '';
$user = isset($parsedUrl['user']) ? $parsedUrl['user'] : '';
$pass = isset($parsedUrl['pass']) ? ':'.$parsedUrl['pass'] : '';
$pass = ($user || $pass) ? "$pass@" : '';
$path = isset($parsedUrl['path']) ? $parsedUrl['path'] : '';
$query = isset($parsedUrl['query']) ? '?'.$parsedUrl['query'] : '';
$fragment = isset($parsedUrl['fragment']) ? '#'.$parsedUrl['fragment'] : '';
return "$scheme$user$pass$host$port$path$query$fragment";
}
/**
* Removes undesired query parameters and fragments
*
* @param string url Url to be cleaned
*
* @return string the string representation of this URL after cleanup
*/
function cleanup_url($url)
{
$obj_url = new Url($url);
return $obj_url->cleanup();
}
/**
* Get URL scheme.
*
* @param string url Url for which the scheme is requested
*
* @return mixed the URL scheme or false if none is provided.
*/
function get_url_scheme($url)
{
$obj_url = new Url($url);
return $obj_url->getScheme();
}
/**
* Adds a trailing slash at the end of URL if necessary.
*
* @param string $url URL to check/edit.
*
* @return string $url URL with a end trailing slash.
*/
function add_trailing_slash($url)
{
return $url . (!endsWith($url, '/') ? '/' : '');
}
/**
* Replace not whitelisted protocols by 'http://' from given URL.
*
* @param string $url URL to clean
* @param array $protocols List of allowed protocols (aside from http(s)).
*
* @return string URL with allowed protocol
*/
function whitelist_protocols($url, $protocols)
{
if (startsWith($url, '?') || startsWith($url, '/')) {
return $url;
}
$protocols = array_merge(['http', 'https'], $protocols);
$protocol = preg_match('#^(\w+):/?/?#', $url, $match);
// Protocol not allowed: we remove it and replace it with http
if ($protocol === 1 && ! in_array($match[1], $protocols)) {
$url = str_replace($match[0], 'http://', $url);
} else if ($protocol !== 1) {
$url = 'http://' . $url;
}
return $url;
}
/**
* URL representation and cleanup utilities
*
* Form
* scheme://[username:password@]host[:port][/path][?query][#fragment]
*
* Examples
* http://username:password@hostname:9090/path?arg1=value1&arg2=value2#anchor
* https://host.name.tld
* https://h2.g2/faq/?vendor=hitchhiker&item=guide&dest=galaxy#answer
*
* @see http://www.faqs.org/rfcs/rfc3986.html
*/
class Url
{
private static $annoyingQueryParams = array(
// Facebook
'action_object_map=',
'action_ref_map=',
'action_type_map=',
'fb_',
'fb=',
'PHPSESSID=',
// Scoop.it
'__scoop',
// Google Analytics & FeedProxy
'utm_',
// ATInternet
'xtor=',
// Other
'campaign_'
);
private static $annoyingFragments = array(
// ATInternet
'xtor=RSS-',
// Misc.
'tk.rss_all'
);
/*
* URL parts represented as an array
*
* @see http://php.net/parse_url
*/
protected $parts;
/**
* Parses a string containing a URL
*
* @param string $url a string containing a URL
*/
public function __construct($url)
{
$url = self::cleanupUnparsedUrl(trim($url));
$this->parts = parse_url($url);
if (!empty($url) && empty($this->parts['scheme'])) {
$this->parts['scheme'] = 'http';
}
}
/**
* Clean up URL before it's parsed.
* ie. handle urlencode, url prefixes, etc.
*
* @param string $url URL to clean.
*
* @return string cleaned URL.
*/
protected static function cleanupUnparsedUrl($url)
{
return self::removeFirefoxAboutReader($url);
}
/**
* Remove Firefox Reader prefix if it's present.
*
* @param string $input url
*
* @return string cleaned url
*/
protected static function removeFirefoxAboutReader($input)
{
$firefoxPrefix = 'about://reader?url=';
if (startsWith($input, $firefoxPrefix)) {
return urldecode(ltrim($input, $firefoxPrefix));
}
return $input;
}
/**
* Returns a string representation of this URL
*/
public function toString()
{
return unparse_url($this->parts);
}
/**
* Removes undesired query parameters
*/
protected function cleanupQuery()
{
if (! isset($this->parts['query'])) {
return;
}
$queryParams = explode('&', $this->parts['query']);
foreach (self::$annoyingQueryParams as $annoying) {
foreach ($queryParams as $param) {
if (startsWith($param, $annoying)) {
$queryParams = array_diff($queryParams, array($param));
continue;
}
}
}
if (count($queryParams) == 0) {
unset($this->parts['query']);
return;
}
$this->parts['query'] = implode('&', $queryParams);
}
/**
* Removes undesired fragments
*/
protected function cleanupFragment()
{
if (! isset($this->parts['fragment'])) {
return;
}
foreach (self::$annoyingFragments as $annoying) {
if (startsWith($this->parts['fragment'], $annoying)) {
unset($this->parts['fragment']);
break;
}
}
}
/**
* Removes undesired query parameters and fragments
*
* @return string the string representation of this URL after cleanup
*/
public function cleanup()
{
$this->cleanupQuery();
$this->cleanupFragment();
return $this->toString();
}
/**
* Converts an URL with an International Domain Name host to a ASCII one.
* This requires PHP-intl. If it's not available, just returns this->cleanup().
*
* @return string converted cleaned up URL.
*/
public function idnToAscii()
{
$out = $this->cleanup();
if (! function_exists('idn_to_ascii') || ! isset($this->parts['host'])) {
return $out;
}
$asciiHost = idn_to_ascii($this->parts['host']);
return str_replace($this->parts['host'], $asciiHost, $out);
}
/**
* Get URL scheme.
*
* @return string the URL scheme or false if none is provided.
*/
public function getScheme() {
if (!isset($this->parts['scheme'])) {
return false;
}
return $this->parts['scheme'];
}
/**
* Get URL host.
*
* @return string the URL host or false if none is provided.
*/
public function getHost() {
if (empty($this->parts['host'])) {
return false;
}
return $this->parts['host'];
}
/**
* Test if the Url is an HTTP one.
*
* @return true is HTTP, false otherwise.
*/
public function isHttp() {
return strpos(strtolower($this->parts['scheme']), 'http') !== false;
}
}

472
application/Utils.php Normal file
View file

@ -0,0 +1,472 @@
<?php
/**
* Shaarli utilities
*/
/**
* Logs a message to a text file
*
* The log format is compatible with fail2ban.
*
* @param string $logFile where to write the logs
* @param string $clientIp the client's remote IPv4/IPv6 address
* @param string $message the message to log
*/
function logm($logFile, $clientIp, $message)
{
file_put_contents(
$logFile,
date('Y/m/d H:i:s').' - '.$clientIp.' - '.strval($message).PHP_EOL,
FILE_APPEND
);
}
/**
* 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)
{
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 escaped.
*/
function escape($input)
{
if (is_bool($input)) {
return $input;
}
if (is_array($input)) {
$out = array();
foreach($input as $key => $value) {
$out[$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 = array())
{
$finalReferer = '?';
// No referer if it contains any value in $loopCriteria.
foreach ($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;
}
/**
* Validate session ID to prevent Full Path Disclosure.
*
* See #298.
* The session ID's format depends on the hash algorithm set in PHP settings
*
* @param string $sessionId Session ID
*
* @return true if valid, false otherwise.
*
* @see http://php.net/manual/en/function.hash-algos.php
* @see http://php.net/manual/en/session.configuration.php
*/
function is_session_id_valid($sessionId)
{
if (empty($sessionId)) {
return false;
}
if (!$sessionId) {
return false;
}
if (!preg_match('/^[a-zA-Z0-9,-]{2,128}$/', $sessionId)) {
return false;
}
return true;
}
/**
* 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 = array('en_US', 'en_US.utf8', 'en_US.UTF-8');
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 DateTime $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 DateTime) {
return false;
}
if (! $intl || ! class_exists('IntlDateFormatter')) {
$format = $time ? '%c' : '%x';
return strftime($format, $date->getTimestamp());
}
$formatter = new IntlDateFormatter(
setlocale(LC_TIME, 0),
IntlDateFormatter::LONG,
$time ? IntlDateFormatter::LONG : IntlDateFormatter::NONE
);
return $formatter->format($date);
}
/**
* 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;
case 'm': $val *= 1024;
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);
}
}

138
application/api/ApiMiddleware.php Normal file
View file

@ -0,0 +1,138 @@
<?php
namespace Shaarli\Api;
use Shaarli\Api\Exceptions\ApiException;
use Shaarli\Api\Exceptions\ApiAuthorizationException;
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;
}
/**
* 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')) {
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');
}
$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 links,
* 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 \LinkDB(
$conf->get('resource.datastore'),
true,
$conf->get('privacy.hide_public_links'),
$conf->get('redirector.url'),
$conf->get('redirector.encode_url')
);
$this->container['db'] = $linkDb;
}
}

137
application/api/ApiUtils.php Normal file
View file

@ -0,0 +1,137 @@
<?php
namespace Shaarli\Api;
use Shaarli\Base64Url;
use Shaarli\Api\Exceptions\ApiAuthorizationException;
/**
* 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.
*
* @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');
}
}
/**
* Format a Link for the REST API.
*
* @param array $link Link 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($link, $indexUrl)
{
$out['id'] = $link['id'];
// Not an internal link
if ($link['url'][0] != '?') {
$out['url'] = $link['url'];
} else {
$out['url'] = $indexUrl . $link['url'];
}
$out['shorturl'] = $link['shorturl'];
$out['title'] = $link['title'];
$out['description'] = $link['description'];
$out['tags'] = preg_split('/\s+/', $link['tags'], -1, PREG_SPLIT_NO_EMPTY);
$out['private'] = $link['private'] == true;
$out['created'] = $link['created']->format(\DateTime::ATOM);
if (! empty($link['updated'])) {
$out['updated'] = $link['updated']->format(\DateTime::ATOM);
} else {
$out['updated'] = '';
}
return $out;
}
/**
* Convert a link given through a request, to a valid link for LinkDB.
*
* 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 $input Request Link.
* @param bool $defaultPrivate Request Link.
*
* @return array Formatted link.
*/
public static function buildLinkFromRequest($input, $defaultPrivate)
{
$input['url'] = ! empty($input['url']) ? cleanup_url($input['url']) : '';
if (isset($input['private'])) {
$private = filter_var($input['private'], FILTER_VALIDATE_BOOLEAN);
} else {
$private = $defaultPrivate;
}
$link = [
'title' => ! empty($input['title']) ? $input['title'] : $input['url'],
'url' => $input['url'],
'description' => ! empty($input['description']) ? $input['description'] : '',
'tags' => ! empty($input['tags']) ? implode(' ', $input['tags']) : '',
'private' => $private,
'created' => new \DateTime(),
];
return $link;
}
/**
* Update link fields using an updated link object.
*
* @param array $oldLink data
* @param array $newLink data
*
* @return array $oldLink updated with $newLink values
*/
public static function updateLink($oldLink, $newLink)
{
foreach (['title', 'url', 'description', 'tags', 'private'] as $field) {
$oldLink[$field] = $newLink[$field];
}
$oldLink['updated'] = new \DateTime();
if (empty($oldLink['url'])) {
$oldLink['url'] = '?' . $oldLink['shorturl'];
}
if (empty($oldLink['title'])) {
$oldLink['title'] = $oldLink['url'];
}
return $oldLink;
}
}

71
application/api/controllers/ApiController.php Normal file
View file

@ -0,0 +1,71 @@
<?php
namespace Shaarli\Api\Controllers;
use Shaarli\Config\ConfigManager;
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 \LinkDB
*/
protected $linkDb;
/**
* @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->linkDb = $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;
}
}

70
application/api/controllers/History.php Normal file
View file

@ -0,0 +1,70 @@
<?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 History 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;
}
else if (ctype_digit($offset)) {
$offset = (int) $offset;
} else {
throw new ApiBadParametersException('Invalid offset');
}
// limit parameter is either a number of links or 'all' for everything.
$limit = $request->getParam('limit');
if (empty($limit)) {
$limit = count($history);
} else if (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);
}
}

42
application/api/controllers/Info.php Normal file
View file

@ -0,0 +1,42 @@
<?php
namespace Shaarli\Api\Controllers;
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' => count($this->linkDb),
'private_counter' => count_private($this->linkDb),
'settings' => array(
'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);
}
}

217
application/api/controllers/Links.php Normal file
View file

@ -0,0 +1,217 @@
<?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 links collection.
*
* @package Api\Controllers
* @see http://shaarli.github.io/api-documentation/#links-links-collection
*/
class Links extends ApiController
{
/**
* @var int Number of links returned if no limit is provided.
*/
public static $DEFAULT_LIMIT = 20;
/**
* Retrieve a list of links, 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');
$links = $this->linkDb->filterSearch(
[
'searchtags' => $request->getParam('searchtags', ''),
'searchterm' => $request->getParam('searchterm', ''),
],
false,
$private
);
// Return links 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;
if ($offset > count($links)) {
return $response->withJson([], 200, $this->jsonStyle);
}
// limit parameter is either a number of links or 'all' for everything.
$limit = $request->getParam('limit');
if (empty($limit)) {
$limit = self::$DEFAULT_LIMIT;
} else if (ctype_digit($limit)) {
$limit = intval($limit);
} else if ($limit === 'all') {
$limit = count($links);
} else {
throw new ApiBadParametersException('Invalid limit');
}
// 'environment' is set by Slim and encapsulate $_SERVER.
$index = index_url($this->ci['environment']);
$out = [];
$cpt = 0;
foreach ($links as $link) {
if (count($out) >= $limit) {
break;
}
if ($cpt++ >= $offset) {
$out[] = ApiUtils::formatLink($link, $index);
}
}
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)
{
if (!isset($this->linkDb[$args['id']])) {
throw new ApiLinkNotFoundException();
}
$index = index_url($this->ci['environment']);
$out = ApiUtils::formatLink($this->linkDb[$args['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 = $request->getParsedBody();
$link = ApiUtils::buildLinkFromRequest($data, $this->conf->get('privacy.default_private_links'));
// duplicate by URL, return 409 Conflict
if (! empty($link['url']) && ! empty($dup = $this->linkDb->getLinkFromUrl($link['url']))) {
return $response->withJson(
ApiUtils::formatLink($dup, index_url($this->ci['environment'])),
409,
$this->jsonStyle
);
}
$link['id'] = $this->linkDb->getNextId();
$link['shorturl'] = link_small_hash($link['created'], $link['id']);
// note: general relative URL
if (empty($link['url'])) {
$link['url'] = '?' . $link['shorturl'];
}
if (empty($link['title'])) {
$link['title'] = $link['url'];
}
$this->linkDb[$link['id']] = $link;
$this->linkDb->save($this->conf->get('resource.page_cache'));
$this->history->addLink($link);
$out = ApiUtils::formatLink($link, index_url($this->ci['environment']));
$redirect = $this->ci->router->relativePathFor('getLink', ['id' => $link['id']]);
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)
{
if (! isset($this->linkDb[$args['id']])) {
throw new ApiLinkNotFoundException();
}
$index = index_url($this->ci['environment']);
$data = $request->getParsedBody();
$requestLink = ApiUtils::buildLinkFromRequest($data, $this->conf->get('privacy.default_private_links'));
// duplicate URL on a different link, return 409 Conflict
if (! empty($requestLink['url'])
&& ! empty($dup = $this->linkDb->getLinkFromUrl($requestLink['url']))
&& $dup['id'] != $args['id']
) {
return $response->withJson(
ApiUtils::formatLink($dup, $index),
409,
$this->jsonStyle
);
}
$responseLink = $this->linkDb[$args['id']];
$responseLink = ApiUtils::updateLink($responseLink, $requestLink);
$this->linkDb[$responseLink['id']] = $responseLink;
$this->linkDb->save($this->conf->get('resource.page_cache'));
$this->history->updateLink($responseLink);
$out = ApiUtils::formatLink($responseLink, $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)
{
if (! isset($this->linkDb[$args['id']])) {
throw new ApiLinkNotFoundException();
}
$link = $this->linkDb[$args['id']];
unset($this->linkDb[(int) $args['id']]);
$this->linkDb->save($this->conf->get('resource.page_cache'));
$this->history->deleteLink($link);
return $response->withStatus(204);
}
}

34
application/api/exceptions/ApiAuthorizationException.php Normal file
View file

@ -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;
}
}

19
application/api/exceptions/ApiBadParametersException.php Normal file
View file

@ -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);
}
}

77
application/api/exceptions/ApiException.php Normal file
View file

@ -0,0 +1,77 @@
<?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.
*/
public abstract 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;
}
}

19
application/api/exceptions/ApiInternalException.php Normal file
View file

@ -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);
}
}

32
application/api/exceptions/ApiLinkNotFoundException.php Normal file
View file

@ -0,0 +1,32 @@
<?php
namespace Shaarli\Api\Exceptions;
use Slim\Http\Response;
/**
* 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);
}
}

34
application/config/ConfigIO.php Normal file
View file

@ -0,0 +1,34 @@
<?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();
}

85
application/config/ConfigJson.php Normal file
View file

@ -0,0 +1,85 @@
<?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($data, true);
if ($data === null) {
$errorCode = json_last_error();
$error = 'An error occurred while parsing JSON configuration file ('. $filepath .'): error code #';
$error .= $errorCode. '<br>➜ <code>' . json_last_error_msg() .'</code>';
if ($errorCode === JSON_ERROR_SYNTAX) {
$error .= '<br>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 (!file_put_contents($filepath, $data)) {
throw new \IOException(
$filepath,
'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 /*'. PHP_EOL;
}
/**
* Get PHP comment closing tags.
*
* Static method for consistency with getPhpHeaders.
*
* @return string PHP comment closing.
*/
public static function getPhpSuffix()
{
return PHP_EOL . '*/ ?>';
}
}

373
application/config/ConfigManager.php Normal file
View file

@ -0,0 +1,373 @@
<?php
namespace Shaarli\Config;
use Shaarli\Config\Exception\MissingFieldConfigException;
use Shaarli\Config\Exception\UnauthorizedConfigException;
/**
* 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 = array('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 string $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('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);
}
}
/**
* 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 \IOException: an error occurred while writing the new config file.
*/
public function write($isLoggedIn)
{
// These fields are required in configuration.
$mandatoryFields = array(
'credentials.login',
'credentials.hash',
'credentials.salt',
'security.session_protection_disabled',
'general.timezone',
'general.title',
'general.header_link',
'privacy.default_private_links',
'redirector.url',
);
// 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;
}
/**
* 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('updates.check_updates', false);
$this->setEmpty('updates.check_updates_branch', 'stable');
$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('thumbnail.enable_thumbnails', true);
$this->setEmpty('thumbnail.enable_localcache', true);
$this->setEmpty('redirector.url', '');
$this->setEmpty('redirector.encode_url', true);
$this->setEmpty('plugins', array());
}
/**
* 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;
}
}

134
application/config/ConfigPhp.php Normal file
View file

@ -0,0 +1,134 @@
<?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 = array(
'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 = array(
'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 array();
}
include $filepath;
$out = array();
foreach (self::$ROOT_KEYS as $key) {
$out[$key] = $GLOBALS[$key];
}
$out['config'] = $GLOBALS['config'];
$out['plugins'] = !empty($GLOBALS['plugins']) ? $GLOBALS['plugins'] : array();
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 \IOException(
$filepath,
'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';
}
}

113
application/config/ConfigPlugin.php Normal file
View file

@ -0,0 +1,113 @@
<?php
use Shaarli\Config\Exception\PluginConfigOrderException;
/**
* 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)
{
// Make sure there are no duplicates in orders.
if (!validate_plugin_order($formData)) {
throw new PluginConfigOrderException();
}
$plugins = array();
$newEnabledPlugins = array();
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 = array();
// 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 = array();
foreach ($formData as $key => $value) {
// No duplicate order allowed.
if (in_array($value, $orders)) {
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;
}

23
application/config/exception/MissingFieldConfigException.php Normal file
View file

@ -0,0 +1,23 @@
<?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 = 'Configuration value is required for '. $this->field;
}
}

17
application/config/exception/PluginConfigOrderException.php Normal file
View file

@ -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 = 'An error occurred while trying to save plugins loading order.';
}
}

18
application/config/exception/UnauthorizedConfigException.php Normal file
View file

@ -0,0 +1,18 @@
<?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 = 'You are not authorized to alter config.';
}
}

22
application/exceptions/IOException.php Normal file
View file

@ -0,0 +1,22 @@
<?php
/**
* 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) ? 'Error accessing' : $message;
$this->message .= ' "' . $this->path .'"';
}
}

13
cache/.htaccess vendored Normal file
View file

@ -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>

41
composer.json Normal file
View file

@ -0,0 +1,41 @@
{
"name": "shaarli/shaarli",
"description": "The personal, minimalist, super-fast, database-free bookmarking service",
"type": "project",
"license": "MIT",
"homepage": "https://github.com/shaarli/Shaarli",
"support": {
"issues": "https://github.com/shaarli/Shaarli/issues",
"wiki": "https://shaarli.readthedocs.io"
},
"keywords": ["bookmark", "link", "share", "web"],
"config": {
"platform": {
"php": "5.5.38"
}
},
"require": {
"php": ">=5.5",
"shaarli/netscape-bookmark-parser": "^2.0",
"erusev/parsedown": "1.6",
"slim/slim": "^3.0",
"pubsubhubbub/publisher": "dev-master"
},
"require-dev": {
"phpmd/phpmd" : "@stable",
"phpunit/phpunit": "4.8.*",
"sebastian/phpcpd": "*",
"squizlabs/php_codesniffer": "2.*",
"phpunit/phpcov": "*"
},
"autoload": {
"psr-4": {
"Shaarli\\": "application",
"Shaarli\\Api\\": "application/api/",
"Shaarli\\Api\\Controllers\\": "application/api/controllers",
"Shaarli\\Api\\Exceptions\\": "application/api/exceptions",
"Shaarli\\Config\\": "application/config/",
"Shaarli\\Config\\Exception\\": "application/config/exception"
}
}
}

2444
composer.lock generated Normal file
View file

File diff suppressed because it is too large Load diff

13
data/.htaccess Normal file
View file

@ -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>

13
doc/md/3rd-party-libraries.md Normal file
View file

@ -0,0 +1,13 @@
## CSS
- Yahoo UI [CSS Reset](http://yuilibrary.com/yui/docs/cssreset/)
- resets default CSS properties for all HTML elements (overriding browsers' default values)
- ensures custom CSS stylessheets will provide the same results on all browsers
## Javascript
- [Awesomeplete](https://leaverou.github.io/awesomplete/) ([GitHub](https://github.com/LeaVerou/awesomplete)) - autocompletion in input forms
- [bLazy](http://dinbror.dk/blazy/) ([GitHub](https://github.com/dinbror/blazy)) - lazy loading for thumbnails
- [qr.js](http://neocotic.com/qr.js/) ([GitHub](https://github.com/neocotic/qr.js)) - QR code generation
## PHP
- [shaarli/netscape-bookmark-parser](https://github.com/shaarli/netscape-bookmark-parser) - Netscape bookmark parser
- [RainTPL](https://github.com/rainphp/raintpl) - HTML templating for PHP

60
doc/md/Backup,-restore,-import-and-export.md Normal file
View file

@ -0,0 +1,60 @@
## Backup and restore the datastore file
Backup the file `data/datastore.php` (by FTP or SSH). Restore by putting the file back in place.
Example command:
```bash
rsync -avzP my.server.com:/var/www/shaarli/data/datastore.php datastore-$(date +%Y-%m-%d_%H%M).php
```
## Export links as...
To export links as an HTML file, under _Tools > Export_, choose:
- _Export all_ to export both public and private links
- _Export public_ to export public links only
- _Export private_ to export private links only
Restore by using the `Import` feature.
- This can be done using the [shaarchiver](https://github.com/nodiscc/shaarchiver) tool.
Example command:
```bash
./export-bookmarks.py --url=https://my.server.com/shaarli --username=myusername --password=mysupersecretpassword --download-dir=./ --type=all
```
## Import links from...
### Diigo
If you export your bookmark from Diigo, make sure you use the Delicious export, not the Netscape export. (Their Netscape export is broken, and they don't seem to be interested in fixing it.)
### Mister Wong
See [this issue](https://github.com/sebsauvage/Shaarli/issues/146) for import tweaks.
### SemanticScuttle
To correctly import the tags from a [SemanticScuttle](http://semanticscuttle.sourceforge.net/) HTML export, edit the HTML file before importing and replace all occurences of `tags=` (lowercase) to `TAGS=` (uppercase).
### Scuttle
Shaarli cannot import data directly from [Scuttle](https://github.com/scronide/scuttle).
However, you can use the third-party [scuttle-to-shaarli](https://github.com/q2apro/scuttle-to-shaarli)
tool to export the Scuttle database to the Netscape HTML format compatible with the Shaarli importer.
## Import Shaarli links to Firefox
- Export your Shaarli links as described above.
- For compatibility reasons, check `Prepend note permalinks with this Shaarli instance's URL (useful to import bookmarks in a web browser)`
- In Firefox, open the bookmark manager (not the sidebar! `Bookmarks menu > Show all bookmarks` or `Ctrl+Shift+B`)
- Select `Import and Backup > Import bookmarks in HTML format`
Your bookmarks will be imported in Firefox, ready to use, with tags and descriptions retained. "Self" (notes) shaares will still point to the Shaarli instance you exported them from, but the note text can be viewed directly in the bookmark properties inside your browser. Depending on the number of bookmarks, the import can take some time.
You may be interested in these Firefox addons to manage links imported from Shaarli
- [Bookmark Deduplicator](https://addons.mozilla.org/en-US/firefox/addon/bookmark-deduplicator/) - provides an easy way to deduplicate your bookmarks
- [TagSieve](https://addons.mozilla.org/en-US/firefox/addon/tagsieve/) - browse your bookmarks by their tags

29
doc/md/Bookmarklet.md Normal file
View file

@ -0,0 +1,29 @@
## Add the sharing button (_bookmarklet_) to your browser
- Open your Shaarli and `Login`
- Click the `Tools` button in the top bar
- Drag the **`✚Shaare link` button**, and drop it to your browser's bookmarks bar.
_This bookmarklet button is compatible with Firefox, Opera, Chrome and Safari. Under Opera, you can't drag'n drop the button: You have to right-click on it and add a bookmark to your personal toolbar._
![](images/bookmarklet.png)
## Share links using the _bookmarklet_
- When you are visiting a webpage you would like to share with Shaarli, click the _bookmarklet_ you just added.
- A window opens.
- You can freely edit title, description, tags... to find it later using the text search or tag filtering.
- You will be able to edit this link later using the ![](https://raw.githubusercontent.com/shaarli/Shaarli/master/images/edit_icon.png) edit button.
- You can also check the “Private” box so that the link is saved but only visible to you.
- Click `Save`.**Voilà! Your link is now shared.**
## Troubleshooting: The bookmarklet doesn't work with a few websites (e.g. Github.com)
Websites which enforce Content Security Policy (CSP), such as github.com, disallow usage of bookmarklets. Unfortunatly, there is nothing Shaarli can do about it.
See [#196](https://github.com/shaarli/Shaarli#196).
There is an open bug for both Firefox and Chromium:
- https://bugzilla.mozilla.org/show_bug.cgi?id=866522
- https://code.google.com/p/chromium/issues/detail?id=233903

23
doc/md/Browsing-and-searching.md Normal file
View file

@ -0,0 +1,23 @@
## Plain text search
Use the `Search text` field to search in _any_ of the fields of all links (Title, URL, Description...)
**Exclude text/tags:** Use the `-` operator before a word or tag (example `-uninteresting`) to prevent entries containing (or tagged) `uninteresting` from showing up in the search results.
**Exact text search:** Use double-quotes (example `"exact search"`) to search for the exact expression.
Both exclude patterns and exact searches can be combined with normal searches (example `"exact search" term otherterm -notthis "very exact" stuff -notagain`)
## Tags search
Use the `Filter by tags` field to restrict displayed links to entries tagged with one or multiple tags (use space to separate tags).
**Hidden tags:** Tags starting with a dot `.` (example `.secret`) are private. They can only be seen and searched when logged in.
Alternatively you can use the `Tag cloud` to discover all tags and click on any of them to display related links.
To search for links that are not tagged, enter `""` in the tag search field.
## Filtering RSS feeds/Picture wall
RSS feeds can also be restricted to only return items matching a text/tag search: see [RSS feeds](RSS feeds).

67
doc/md/Community-&-Related-software.md Normal file
View file

@ -0,0 +1,67 @@
_Unofficial but related work on Shaarli. If you maintain one of these,
please get in touch with us to help us find a way to adapt your work to our fork._
## Community
- [Liens en vrac de sebsauvage](http://sebsauvage.net/links/) - the original Shaarli
- [A large list of Shaarlis](http://porneia.free.fr/pub/links/ou-est-shaarli.html)
- [A list of working Shaarli aggregators](https://raw.githubusercontent.com/Oros42/find_shaarlis/master/annuaires.json)
- [A list of some known Shaarlis](https://github.com/Oros42/shaarlis_list)
- [Adieu Delicious, Diigo et StumbleUpon. Salut Shaarli ! - sebsauvage.net](http://sebsauvage.net/rhaa/index.php?2011/09/16/09/29/58-adieu-delicious-diigo-et-stumbleupon-salut-shaarli-) (fr) _16/09/2011 - the original post about Shaarli_
- [Original ideas/fixme/TODO page](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:ideas)
- [Original discussion page](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:discussion) (fr)
- [Original revisions history](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:history)
- [Shaarli.fr/my](https://www.shaarli.fr/my.php) - Unofficial, unsupported (old fork) hosted Shaarlis provider, courtesy of [DMeloni](https://github.com/DMeloni)
### Articles and social media discussions
- 2016-09-22 - Hacker News - https://news.ycombinator.com/item?id=12552176
- 2015-08-15 - Reddit - [Question about migrating from WordPress to Shaarli.](https://www.reddit.com/r/selfhosted/comments/3h3zwh/question_about_migrating_from_wordpress_to_shaarli/)
- 2015-06-22 - Hacker News - https://news.ycombinator.com/item?id=9755366
- 2015-05-12 - Reddit - [shaarli - Self hosted Bookmarking / Delicious (PHP, MySQL)](https://www.reddit.com/r/selfhosted/comments/35pkkc/shaarli_self_hosted_bookmarking_delicious_php/)
### REST API clients
See [REST API](REST-API) for a list of official and community clients.
### Third party plugins
- [autosave](https://github.com/kalvn/shaarli-plugin-autosave) by [@kalvn](https://github.com/kalvn): Automatically saves data when editing a link to avoid any loss in case of crash or unexpected shutdown.
- [Code Coloration](https://github.com/ArthurHoaro/code-coloration) by [@ArthurHoaro](https://github.com/ArthurHoaro): client side code syntax highlighter.
- [Disqus](https://github.com/kalvn/shaarli-plugin-disqus) by [@kalvn](https://github.com/kalvn): Adds Disqus comment system to your Shaarli.
- [emojione](https://github.com/NerosTie/emojione) by [@NerosTie](https://github.com/NerosTie): Add colorful emojis to your Shaarli.
- [google analytics](https://github.com/ericjuden/Shaarli-Google-Analytics-Plugin) by [@ericjuden](http://github.com/ericjuden): Adds Google Analytics tracking support
- [launch](https://github.com/ArthurHoaro/launch-plugin) - Launch Plugin is a plugin designed to enhance and customize Launch Theme for Shaarli.
- [related](https://github.com/ilesinge/shaarli-related) by [@ilesinge](https://github.com/ilesinge) - Show related links based on the number of identical tags.
- [social](https://github.com/alexisju/social) by [@alexisju](https://github.com/alexisju): share links to social networks.
- [shaarli2twitter](https://github.com/ArthurHoaro/shaarli2twitter) by [@ArthurHoaro](https://github.com/ArthurHoaro) - Automatically tweet your shared links from Shaarli
### Third-party themes
See [Theming](Theming) for a list of community-contributed themes, and an installation guide.
## Integration with other platforms
- [tt-rss-shaarli](https://github.com/jcsaaddupuy/tt-rss-shaarli) - [Tiny-Tiny RSS](http://tt-rss.org/) plugin that adds support for sharing articles with Shaarli
- [octopress-shaarli](https://github.com/ahmet2mir/octopress-shaarli) - Octopress plugin to retrieve Shaarli links on the sidebar
- [Scuttle to Shaarli](https://github.com/q2apro/scuttle-to-shaarli) - Import bookmarks from Scuttle
### Mobile Apps
- [ShaarliOS](https://github.com/mro/ShaarliOS) iOS share extension - see [#308](https://github.com/shaarli/Shaarli/issues/308#issuecomment-184592070) for some promo codes,
- [Shaarli for Android](http://sebsauvage.net/links/?ZAyDzg) - Android application that adds Shaarli as a sharing provider
- [Shaarlier for Android](https://github.com/dimtion/Shaarlier) - Android application to simply add links directly into your Shaarli
### Server apps
- [shaarchiver](https://github.com/nodiscc/shaarchiver) - Archive your Shaarli bookmarks and their content
- [shaarli-river](https://github.com/mknexen/shaarli-river) - An aggregator for shaarlis with many features
- [Shaarlo](https://github.com/DMeloni/shaarlo) - An aggregator for shaarlis with many features (a very popular running instance among French shaarliers: [shaarli.fr](http://shaarli.fr/))
- [Shaarlimages](https://github.com/BoboTiG/shaarlimages) - An image-oriented aggregator for Shaarlis
- [mknexen/shaarli-api](https://github.com/mknexen/shaarli-api) - A REST API for Shaarli
- [Self dead link](https://github.com/qwertygc/shaarli-dev-code/blob/master/self-dead-link.php) - Detect dead links on shaarli. This version use the database of shaarli. [Another version](https://github.com/qwertygc/shaarli-dev-code/blob/master/dead-link.php), can be used for other shaarli instances (but is more resource consuming).
- [Bookmark Archiver](https://github.com/pirate/bookmark-archiver) - Save an archived copy of all websites starred using browser bookmarks/Shaarli/Delicious/Instapaper/Unmark.it/Pocket/Pinboard. Outputs browseable html.
## Alternatives to Shaarli
See the [bookmarks & link sharing](https://github.com/Kickball/awesome-selfhosted/#bookmarks--link-sharing)
section on [awesome-selfhosted](https://github.com/Kickball/awesome-selfhosted/).

28
doc/md/Continuous-integration-tools.md Normal file
View file

@ -0,0 +1,28 @@
## Local development
A [`Makefile`](https://github.com/shaarli/Shaarli/blob/master/Makefile) is available to perform project-related operations:
- Documentation - generate a local HTML copy of the GitHub wiki
- [Static analysis](Static analysis) - check that the code is compliant to PHP conventions
- [Unit tests](Unit tests) - ensure there are no regressions introduced by new commits
## Automatic builds
[Travis CI](http://docs.travis-ci.com/) is a Continuous Integration build server, that runs a build:
- each time a commit is merged to the mainline (`master` branch)
- each time a Pull Request is submitted or updated
A build is composed of several jobs: one for each supported PHP version (see [Server requirements](Server requirements)).
Each build job:
- updates Composer
- installs 3rd-party test dependencies with Composer
- runs [Unit tests](Unit tests)
After all jobs have finished, Travis returns the results to GitHub:
- a status icon represents the result for the `master` branch: [![](https://api.travis-ci.org/shaarli/Shaarli.svg)](https://travis-ci.org/shaarli/Shaarli)
- Pull Requests are updated with the Travis result
- Green: all tests have passed
- Red: some tests failed
- Orange: tests are pending

10
doc/md/Development-guidelines.md Normal file
View file

@ -0,0 +1,10 @@
## Development guidelines
Please have a look at the following pages:
- [Contributing to Shaarli](https://github.com/shaarli/Shaarli/tree/master/CONTRIBUTING.md)
- [Static analysis](Static analysis) - patches should try to stick to the [PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), especially:
- [PSR-1](http://www.php-fig.org/psr/psr-1/) - Basic Coding Standard
- [PSR-2](http://www.php-fig.org/psr/psr-2/) - Coding Style Guide
- [Unit tests](Unit tests)
- [GnuPG signature](GnuPG signature) for tags/releases

34
doc/md/Directory-structure.md Normal file
View file

@ -0,0 +1,34 @@
TODO: This page is out of date
Here is the directory structure of Shaarli and the purpose of the different files:
```bash
index.php # Main program
application/ # Shaarli classes
├── LinkDB.php
└── Utils.php
tests/ # Shaarli unitary & functional tests
├── LinkDBTest.php
├── utils # utilities to ease testing
│ └── ReferenceLinkDB.php
└── UtilsTest.php
COPYING # Shaarli license
inc/ # static assets and 3rd party libraries
├── awesomplete.* # tags autocompletion library
├── blazy.* # picture wall lazy image loading library
├── shaarli.css, reset.css # Shaarli stylesheet.
├── qr.* # qr code generation library
└──rain.tpl.class.php # RainTPL templating library
tpl/ # RainTPL templates for Shaarli. They are used to build the pages.
images/ # Images and icons used in Shaarli
data/ # data storage: bookmark database, configuration, logs, banlist…
├── config.php # Shaarli configuration (login, password, timezone, title…)
├── datastore.php # Your link database (compressed).
├── ipban.php # IP address ban system data
├── lastupdatecheck.txt # Update check timestamp file
└──log.txt # login/IPban log.
cache/ # thumbnails cache
# This directory is automatically created. You can erase it anytime you want.
tmp/ # Temporary directory for compiled RainTPL templates.
# This directory is automatically created. You can erase it anytime you want.
```

98
doc/md/Download-and-Installation.md Normal file
View file

@ -0,0 +1,98 @@
To install Shaarli, simply place the files in a directory under your webserver's
Document Root (or directly at the document root).
Also, please make sure your server meets the [requirements](Server-requirements)
and is properly [configured](Server-configuration).
Several releases are available:
- by downloading full release archives including all dependencies
- by downloading Github archives
- by cloning the Git repository
---
## Latest release (recommended)
### Download as an archive
Get the latest released version from the [releases](https://github.com/shaarli/Shaarli/releases) page.
**Download our *shaarli-full* archive** to include dependencies.
The current latest released version is `v0.9.1`
Or in command lines:
```bash
$ wget https://github.com/shaarli/Shaarli/releases/download/v0.9.1/shaarli-v0.9.1-full.zip
$ unzip shaarli-v0.9.1-full.zip
$ mv Shaarli /path/to/shaarli/
```
In most cases, download Shaarli from the [releases](https://github.com/shaarli/Shaarli/releases) page. Cloning using `git` or downloading Github branches as zip files requires additional steps (see below).|
### Using git
```
$ mkdir -p /path/to/shaarli && cd /path/to/shaarli/
$ git clone -b v0.9 https://github.com/shaarli/Shaarli.git .
$ composer install --no-dev --prefer-dist
```
## Stable version
The stable version has been experienced by Shaarli users, and will receive security updates.
### Download as an archive
As a .zip archive:
```bash
$ wget https://github.com/shaarli/Shaarli/archive/stable.zip
$ unzip stable.zip
$ mv Shaarli-stable /path/to/shaarli/
```
As a .tar.gz archive :
```bash
$ wget https://github.com/shaarli/Shaarli/archive/stable.tar.gz
$ tar xvf stable.tar.gz
$ mv Shaarli-stable /path/to/shaarli/
```
### Clone with Git
[Composer](https://getcomposer.org/) is required to build a functional Shaarli installation when pulling from git.
```bash
$ git clone https://github.com/shaarli/Shaarli.git -b stable /path/to/shaarli/
# install/update third-party dependencies
$ cd /path/to/shaarli/
$ composer install --no-dev --prefer-dist
```
## Development version (mainline)
_Use at your own risk!_
To get the latest changes from the `master` branch:
```bash
# clone the repository
$ git clone https://github.com/shaarli/Shaarli.git -b master /path/to/shaarli/
# install/update third-party dependencies
$ cd /path/to/shaarli
$ composer install --no-dev --prefer-dist
```
## Finish Installation
Once Shaarli is downloaded and files have been placed at the correct location, open it this location your favorite browser.
![install screenshot](http://i.imgur.com/wuMpDSN.png)
Setup your Shaarli installation, and it's ready to use!
## Updating Shaarli
See [Upgrade and Migration](Upgrade-and-migration)

44
doc/md/FAQ.md Normal file
View file

@ -0,0 +1,44 @@
### Why did you create Shaarli ?
I was a StumbleUpon user. Then I got fed up with they big toolbar. I switched to delicious, which was lighter, faster and more beautiful. Until Yahoo bought it. Then the export API broke all the time, delicious became slow and was ditched by Yahoo. I switched to Diigo, which is not bad, but does too much. And Diigo is sslllooooowww and their Firefox extension a bit buggy. And… oh… **their Firefox addon sends to Diigo every single URL you visit** (Don't believe me ? Use [Tamper Data](https://addons.mozilla.org/en-US/firefox/addon/tamper-data/) and open any page).
Enough is enough. Saving simple links should not be a complicated heavy thing. I ditched them all and wrote my own: Shaarli. It's simple, but it does the job and does it well. And my data is not hosted on a foreign server, but on my server.
### Why use Shaarli and not Delicious/Diigo ?
With Shaarli:
- The data is yours: It's hosted on your server.
- Never fear of having your data locked-in.
- Never fear to have your data sold to third party.
- Your private links are not hosted on a third party server.
- You are not tracked by browser addons (like Diigo does)
- You can change the look and feel of the pages if you want.
- You can change the behaviour of the program.
- It's magnitude faster than most bookmarking services.
### What does Shaarli mean?
Shaarli stands for _shaaring_ your _links_.
### My Shaarli is broken!
First of all, ensure that both the [web server](Server-configuration) and [Shaarli](Shaarli-configuration) are correctly configured, and that your installation is [supported](Server-requirements).
If everything looks right but the issue(s) remain(s), please:
- take a look at the [troubleshooting](Troubleshooting) section
- come [chat with us](https://gitter.im/shaarli/Shaarli) on Gitter, we'll be happy to help ;-)
- browse active [issues](https://github.com/shaarli/Shaarli/issues) and [Pull Requests](https://github.com/shaarli/Shaarli/pulls)
- if you find one that is related to the issue, feel free to comment and provide additional details (host/Shaarli setup)
- else, [open a new issue](https://github.com/shaarli/Shaarli/issues/new), and provide information about the problem:
- _what happens?_ - display glitches, invalid data, security flaws...
- _what is your configuration?_ - OS, server version, activated extensions, web browser...
- _is it reproducible?_
### Why not use a real database? Files are slow!
Does browsing [this page](http://sebsauvage.net/links/) feel slow? Try browsing older pages, too.
It's not slow at all, is it? And don't forget the database contains more than 16000 links, and it's on a shared host, with 32000 visitors/day for my website alone. And it's still damn fast. Why?
The data file is only 3.7 Mb. It's read 99% of the time, and is probably already in the operation system disk cache. So generating a page involves no I/O at all most of the time.

25
doc/md/Features.md Normal file
View file

@ -0,0 +1,25 @@
### Main features
Shaarli is intended:
- to share, comment and save interesting links and news
- to bookmark useful/frequent personal links (as private links) and share them between computers
- as a minimal blog/microblog/writing platform (no character limit)
- as a read-it-later list (for example items tagged `readlater`)
- to draft and save articles/ideas
- to keep code snippets
- to keep notes and documentation
- as a shared clipboard between machines
- as a todo list
- to store playlists (e.g. with the `music` or `video` tags)
- to keep extracts/comments from webpages that may disappear
- to keep track of ongoing discussions (for example items tagged `discussion`)
- [to feed RSS aggregators](http://shaarli.chassegnouf.net/?9Efeiw) (planets) with specific tags
- to feed other social networks, blogs... using RSS feeds and external services (dlvr.it, ifttt.com ...)
### Using Shaarli as a blog, notepad, pastebin...
- Go to your Shaarli setup and log in
- Click the `Add Link` button
- To share text only, do not enter any URL in the corresponding input field and click `Add Link`
- Pick a title and enter your article, or note, in the description field; add a few tags; optionally check `Private` then click `Save`
- Voilà! Your article is now published (privately if you selected that option) and accessible using its permalink.

17
doc/md/Firefox-share.md Normal file
View file

@ -0,0 +1,17 @@
### Add Shaarli as a sharing service to Firefox
- Open your Shaarli and `Login`
- Click the `Tools` button in the top bar
- Click the `✚Add to Firefox social` button and accept the activation.
### Sharing links using Firefox share
- Add the sharing service as described above
- When you are visiting a webpage you would like to share with Shaarli,
click the Firefox _Share_ button [images/firefoxshare.png](images/firefoxshare.png)
- You can edit your link before and after saving, just like the bookmarklet above.
_Your Shaarli instance must be hosted on an HTTPS (SSL/TLS secure connection)
enabled server for Firefox Share to work. Firefox Share will not work over
plain HTTP connections._

78
doc/md/GnuPG-signature.md Normal file
View file

@ -0,0 +1,78 @@
## Introduction
### PGP and GPG
[Gnu Privacy Guard](https://gnupg.org/) (GnuPG) is an Open Source implementation of the
[Pretty Good Privacy](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP)
(OpenPGP) specification. Its main purposes are digital authentication, signature and encryption.
It is often used by the [FLOSS](https://en.wikipedia.org/wiki/Free_and_open-source_software) community to verify:
- Linux package signatures: Debian [SecureApt](https://wiki.debian.org/SecureApt), ArchLinux [Master
Keys](https://www.archlinux.org/master-keys/)
- [SCM](https://en.wikipedia.org/wiki/Revision_control) releases & maintainer identity
### Trust
To quote Phil Pennock (the author of the [SKS](https://bitbucket.org/skskeyserver/sks-keyserver/wiki/Home) key server - http://sks.spodhuis.org/):
> You MUST understand that presence of data in the keyserver (pools) in no way connotes trust. Anyone can generate a key, with any name or email address, and upload it. All security and trust comes from evaluating security at the “object level”, via PGP Web-Of-Trust signatures. This keyserver makes it possible to retrieve keys, looking them up via various indices, but the collection of keys in this public pool is KNOWN to contain malicious and fraudulent keys. It is the common expectation of server operators that users understand this and use software which, like all known common OpenPGP implementations, evaluates trust accordingly. This expectation is so common that it is not normally explicitly stated.
Trust can be gained by having your key signed by other people (and signing their key back, too :) ), for instance during [key signing parties](https://en.wikipedia.org/wiki/Key_signing_party), see:
- [The Keysigning party HOWTO](http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html)
- [Web of trust](https://en.wikipedia.org/wiki/Web_of_trust)
## Generate a GPG key
- [Generating a GPG key for Git tagging](http://stackoverflow.com/a/16725717) (StackOverflow)
- [Generating a GPG key](https://help.github.com/articles/generating-a-gpg-key/) (GitHub)
### gpg - provide identity information
```bash
$ gpg --gen-key
gpg (GnuPG) 2.1.6; Copyright (C) 2015 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Note: Use "gpg2 --full-gen-key" for a full featured key generation dialog.
GnuPG needs to construct a user ID to identify your key.
Real name: Marvin the Paranoid Android
Email address: marvin@h2g2.net
You selected this USER-ID:
"Marvin the Paranoid Android <marvin@h2g2.net>"
Change (N)ame, (E)mail, or (O)kay/(Q)uit? o
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
```
### gpg - entropy interlude
At this point, you will:
- be prompted for a secure password to protect your key (the input method will depend on your Desktop Environment and configuration)
- be asked to use your machine's input devices (mouse, keyboard, etc.) to generate random entropy; this step _may take some time_
### gpg - key creation confirmation
```bash
gpg: key A9D53A3E marked as ultimately trusted
public and secret key created and signed.
gpg: checking the trustdb
gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
gpg: depth: 0 valid: 2 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 2u
pub rsa2048/A9D53A3E 2015-07-31
Key fingerprint = AF2A 5381 E54B 2FD2 14C4 A9A3 0E35 ACA4 A9D5 3A3E
uid [ultimate] Marvin the Paranoid Android <marvin@h2g2.net>
sub rsa2048/8C0EACF1 2015-07-31
```
### gpg - submit your public key to a PGP server (Optional)
``` bash
$ gpg --keyserver pgp.mit.edu --send-keys A9D53A3E
gpg: sending key A9D53A3E to hkp server pgp.mit.edu
```
## Create and push a GPG-signed tag
See [Release Shaarli](Release Shaarli).

708
doc/md/Plugin-System.md Normal file
View file

@ -0,0 +1,708 @@
[**I am a developer: ** Developer API](#developer-api)
[**I am a template designer: ** Guide for template designers](#guide-for-template-designer)
---
## Developer API
### What can I do with plugins?
The plugin system let you:
- insert content into specific places across templates.
- alter data before templates rendering.
- alter data before saving new links.
### How can I create a plugin for Shaarli?
First, chose a plugin name, such as `demo_plugin`.
Under `plugin` folder, create a folder named with your plugin name. Then create a <plugin_name>.php file in that folder.
You should have the following tree view:
```
| index.php
| plugins/
|---| demo_plugin/
| |---| demo_plugin.php
```
### Plugin initialization
At the beginning of Shaarli execution, all enabled plugins are loaded. At this point, the plugin system looks for an `init()` function to execute and run it if it exists. This function must be named this way, and takes the `ConfigManager` as parameter.
<plugin_name>_init($conf)
This function can be used to create initial data, load default settings, etc. But also to set *plugin errors*. If the initialization function returns an array of strings, they will be understand as errors, and displayed in the header to logged in users.
### Understanding hooks
A plugin is a set of functions. Each function will be triggered by the plugin system at certain point in Shaarli execution.
These functions need to be named with this pattern:
```
hook_<plugin_name>_<hook_name>($data, $conf)
```
Parameters:
- data: see [$data section](https://shaarli.readthedocs.io/en/master/Plugin-System/#plugins-data)
- conf: the `ConfigManager` instance.
For example, if my plugin want to add data to the header, this function is needed:
hook_demo_plugin_render_header
If this function is declared, and the plugin enabled, it will be called every time Shaarli is rendering the header.
### Plugin's data
#### Parameters
Every hook function has a `$data` parameter. Its content differs for each hooks.
**This parameter needs to be returned every time**, otherwise data is lost.
return $data;
#### Filling templates placeholder
Template placeholders are displayed in template in specific places.
RainTPL displays every element contained in the placeholder's array. These element can be added by plugins.
For example, let's add a value in the placeholder `top_placeholder` which is displayed at the top of my page:
```php
$data['top_placeholder'][] = 'My content';
# OR
array_push($data['top_placeholder'], 'My', 'content');
return $data;
```
#### Data manipulation
When a page is displayed, every variable send to the template engine is passed to plugins before that in `$data`.
The data contained by this array can be altered before template rendering.
For exemple, in linklist, it is possible to alter every title:
```php
// mind the reference if you want $data to be altered
foreach ($data['links'] as &$value) {
// String reverse every title.
$value['title'] = strrev($value['title']);
}
return $data;
```
### Metadata
Every plugin needs a `<plugin_name>.meta` file, which is in fact an `.ini` file (`KEY="VALUE"`), to be listed in plugin administration.
Each file contain two keys:
- `description`: plugin description
- `parameters`: user parameter names, separated by a `;`.
- `parameter.<PARAMETER_NAME>`: add a text description the specified parameter.
> Note: In PHP, `parse_ini_file()` seems to want strings to be between by quotes `"` in the ini file.
### It's not working!
Use `demo_plugin` as a functional example. It covers most of the plugin system features.
If it's still not working, please [open an issue](https://github.com/shaarli/Shaarli/issues/new).
### Hooks
| Hooks | Description |
| ------------- |:-------------:|
| [render_header](#render_header) | Allow plugin to add content in page headers. |
| [render_includes](#render_includes) | Allow plugin to include their own CSS files. |
| [render_footer](#render_footer) | Allow plugin to add content in page footer and include their own JS files. |
| [render_linklist](#render_linklist) | It allows to add content at the begining and end of the page, after every link displayed and to alter link data. |
| [render_editlink](#render_editlink) | Allow to add fields in the form, or display elements. |
| [render_tools](#render_tools) | Allow to add content at the end of the page. |
| [render_picwall](#render_picwall) | Allow to add content at the top and bottom of the page. |
| [render_tagcloud](#render_tagcloud) | Allow to add content at the top and bottom of the page, and after all tags. |
| [render_taglist](#render_taglist) | Allow to add content at the top and bottom of the page, and after all tags. |
| [render_daily](#render_daily) | Allow to add content at the top and bottom of the page, the bottom of each link and to alter data. |
| [render_feed](#render_feed) | Allow to do add tags in RSS and ATOM feeds. |
| [save_link](#save_link) | Allow to alter the link being saved in the datastore. |
| [delete_link](#delete_link) | Allow to do an action before a link is deleted from the datastore. |
#### render_header
Triggered on every page.
Allow plugin to add content in page headers.
##### Data
`$data` is an array containing:
- `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
- `_LOGGEDIN_`: true if user is logged in, false otherwise.
##### Template placeholders
Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
List of placeholders:
- `buttons_toolbar`: after the list of buttons in the header.
![buttons_toolbar_example](http://i.imgur.com/ssJUOrt.png)
- `fields_toolbar`: after search fields in the header.
> Note: This will only be called in linklist.
![fields_toolbar_example](http://i.imgur.com/3GMifI2.png)
#### render_includes
Triggered on every page.
Allow plugin to include their own CSS files.
##### Data
`$data` is an array containing:
- `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
- `_LOGGEDIN_`: true if user is logged in, false otherwise.
##### Template placeholders
Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
List of placeholders:
- `css_files`: called after loading default CSS.
> Note: only add the path of the CSS file. E.g: `plugins/demo_plugin/custom_demo.css`.
#### render_footer
Triggered on every page.
Allow plugin to add content in page footer and include their own JS files.
##### Data
`$data` is an array containing:
- `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
- `_LOGGEDIN_`: true if user is logged in, false otherwise.
##### Template placeholders
Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
List of placeholders:
- `text`: called after the end of the footer text.
- `endofpage`: called at the end of the page.
![text_example](http://i.imgur.com/L5S2YEH.png)
- `js_files`: called at the end of the page, to include custom JS scripts.
> Note: only add the path of the JS file. E.g: `plugins/demo_plugin/custom_demo.js`.
#### render_linklist
Triggered when `linklist` is displayed (list of links, permalink, search, tag filtered, etc.).
It allows to add content at the begining and end of the page, after every link displayed and to alter link data.
##### Data
`$data` is an array containing:
- `_LOGGEDIN_`: true if user is logged in, false otherwise.
- All templates data, including links.
##### Template placeholders
Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
List of placeholders:
- `action_plugin`: next to the button "private only" at the top and bottom of the page.
![action_plugin_example](http://i.imgur.com/Q12PWg0.png)
- `link_plugin`: for every link, between permalink and link URL.
![link_plugin_example](http://i.imgur.com/3oDPhWx.png)
- `plugin_start_zone`: before displaying the template content.
![plugin_start_zone_example](http://i.imgur.com/OVBkGy3.png)
- `plugin_end_zone`: after displaying the template content.
![plugin_end_zone_example](http://i.imgur.com/6IoRuop.png)
#### render_editlink
Triggered when the link edition form is displayed.
Allow to add fields in the form, or display elements.
##### Data
`$data` is an array containing:
- All templates data.
##### Template placeholders
Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
List of placeholders:
- `edit_link_plugin`: after tags field.
![edit_link_plugin_example](http://i.imgur.com/5u17Ens.png)
#### render_tools
Triggered when the "tools" page is displayed.
Allow to add content at the end of the page.
##### Data
`$data` is an array containing:
- All templates data.
##### Template placeholders
Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
List of placeholders:
- `tools_plugin`: at the end of the page.
![tools_plugin_example](http://i.imgur.com/Bqhu9oQ.png)
#### render_picwall
Triggered when picwall is displayed.
Allow to add content at the top and bottom of the page.
##### Data
`$data` is an array containing:
- `_LOGGEDIN_`: true if user is logged in, false otherwise.
- All templates data.
##### Template placeholders
Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
List of placeholders:
- `plugin_start_zone`: before displaying the template content.
- `plugin_end_zone`: after displaying the template content.
![plugin_start_end_zone_example](http://i.imgur.com/tVTQFER.png)
#### render_tagcloud
Triggered when tagcloud is displayed.
Allow to add content at the top and bottom of the page.
##### Data
`$data` is an array containing:
- `_LOGGEDIN_`: true if user is logged in, false otherwise.
- All templates data.
##### Template placeholders
Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
List of placeholders:
- `plugin_start_zone`: before displaying the template content.
- `plugin_end_zone`: after displaying the template content.
For each tag, the following placeholder can be used:
- `tag_plugin`: after each tag
![plugin_start_end_zone_example](http://i.imgur.com/vHmyT3a.png)
#### render_taglist
Triggered when taglist is displayed.
Allow to add content at the top and bottom of the page.
##### Data
`$data` is an array containing:
- `_LOGGEDIN_`: true if user is logged in, false otherwise.
- All templates data.
##### Template placeholders
Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
List of placeholders:
- `plugin_start_zone`: before displaying the template content.
- `plugin_end_zone`: after displaying the template content.
For each tag, the following placeholder can be used:
- `tag_plugin`: after each tag
#### render_daily
Triggered when tagcloud is displayed.
Allow to add content at the top and bottom of the page, the bottom of each link and to alter data.
##### Data
`$data` is an array containing:
- `_LOGGEDIN_`: true if user is logged in, false otherwise.
- All templates data, including links.
##### Template placeholders
Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
List of placeholders:
- `link_plugin`: used at bottom of each link.
![link_plugin_example](http://i.imgur.com/hzhMfSZ.png)
- `plugin_start_zone`: before displaying the template content.
- `plugin_end_zone`: after displaying the template content.
#### render_feed
Triggered when the ATOM or RSS feed is displayed.
Allow to add tags in the feed, either in the header or for each items. Items (links) can also be altered before being rendered.
##### Data
`$data` is an array containing:
- `_LOGGEDIN_`: true if user is logged in, false otherwise.
- `_PAGE_`: containing either `rss` or `atom`.
- All templates data, including links.
##### Template placeholders
Tags can be added in feeds by adding an entry in `$data['<placeholder>']` array.
List of placeholders:
- `feed_plugins_header`: used as a header tag in the feed.
For each links:
- `feed_plugins`: additional tag for every link entry.
#### save_link
Triggered when a link is save (new link or edit).
Allow to alter the link being saved in the datastore.
##### Data
`$data` is an array containing the link being saved:
- id
- title
- url
- shorturl
- description
- private
- tags
- created
- updated
#### delete_link
Triggered when a link is deleted.
Allow to execute any action before the link is actually removed from the datastore
##### Data
`$data` is an array containing the link being saved:
- id
- title
- url
- shorturl
- description
- private
- tags
- created
- updated
## Guide for template designer
### Plugin administration
Your theme must include a plugin administration page: `pluginsadmin.html`.
> Note: repo's template link needs to be added when the PR is merged.
Use the default one as an example.
Aside from classic RainTPL loops, plugins order is handle by JavaScript. You can just include `plugin_admin.js`, only if:
- you're using a table.
- you call orderUp() and orderUp() onclick on arrows.
- you add data-line and data-order to your rows.
Otherwise, you can use your own JS as long as this field is send by the form:
<input type="hidden" name="order_{$key}" value="{$counter}">
### Placeholder system
In order to make plugins work with every custom themes, you need to add variable placeholder in your templates.
It's a RainTPL loop like this:
{loop="$plugin_variable"}
{$value}
{/loop}
You should enable `demo_plugin` for testing purpose, since it uses every placeholder available.
### List of placeholders
**page.header.html**
At the end of the menu:
{loop="$plugins_header.buttons_toolbar"}
{$value}
{/loop}
At the end of file, before clearing floating blocks:
{if="!empty($plugin_errors) && isLoggedIn()"}
<ul class="errors">
{loop="plugin_errors"}
<li>{$value}</li>
{/loop}
</ul>
{/if}
**includes.html**
At the end of the file:
```html
{loop="$plugins_includes.css_files"}
<link type="text/css" rel="stylesheet" href="{$value}#"/>
{/loop}
```
**page.footer.html**
At the end of your footer notes:
```html
{loop="$plugins_footer.text"}
{$value}
{/loop}
```
At the end of file:
```html
{loop="$plugins_footer.js_files"}
<script src="{$value}#"></script>
{/loop}
```
**linklist.html**
After search fields:
```html
{loop="$plugins_header.fields_toolbar"}
{$value}
{/loop}
```
Before displaying the link list (after paging):
```html
{loop="$plugin_start_zone"}
{$value}
{/loop}
```
For every links (icons):
```html
{loop="$value.link_plugin"}
<span>{$value}</span>
{/loop}
```
Before end paging:
```html
{loop="$plugin_end_zone"}
{$value}
{/loop}
```
**linklist.paging.html**
After the "private only" icon:
```html
{loop="$action_plugin"}
{$value}
{/loop}
```
**editlink.html**
After tags field:
```html
{loop="$edit_link_plugin"}
{$value}
{/loop}
```
**tools.html**
After the last tool:
```html
{loop="$tools_plugin"}
{$value}
{/loop}
```
**picwall.html**
Top:
```html
<div id="plugin_zone_start_picwall" class="plugin_zone">
{loop="$plugin_start_zone"}
{$value}
{/loop}
</div>
```
Bottom:
```html
<div id="plugin_zone_end_picwall" class="plugin_zone">
{loop="$plugin_end_zone"}
{$value}
{/loop}
</div>
```
**tagcloud.html**
Top:
```html
<div id="plugin_zone_start_tagcloud" class="plugin_zone">
{loop="$plugin_start_zone"}
{$value}
{/loop}
</div>
```
Bottom:
```html
<div id="plugin_zone_end_tagcloud" class="plugin_zone">
{loop="$plugin_end_zone"}
{$value}
{/loop}
</div>
```
**daily.html**
Top:
```html
<div id="plugin_zone_start_picwall" class="plugin_zone">
{loop="$plugin_start_zone"}
{$value}
{/loop}
</div>
```
After every link:
```html
<div class="dailyEntryFooter">
{loop="$link.link_plugin"}
{$value}
{/loop}
</div>
```
Bottom:
```html
<div id="plugin_zone_end_picwall" class="plugin_zone">
{loop="$plugin_end_zone"}
{$value}
{/loop}
</div>
```
**feed.atom.xml** and **feed.rss.xml**:
In headers tags section:
```xml
{loop="$feed_plugins_header"}
{$value}
{/loop}
```
After each entry:
```xml
{loop="$value.feed_plugins"}
{$value}
{/loop}
```

75
doc/md/Plugins.md Normal file
View file

@ -0,0 +1,75 @@
## Plugin installation
There is a bunch of plugins shipped with Shaarli, where there is nothing to do to install them.
If you want to install a third party plugin:
- Download it.
- Put it in the `plugins` directory in Shaarli's installation folder.
- Make sure you put it correctly:
```
| index.php
| plugins/
|---| custom_plugin/
| |---| custom_plugin.php
| |---| ...
```
* Make sure your webserver can read and write the files in your plugin folder.
## Plugin configuration
In Shaarli's administration page (`Tools` link), go to `Plugin administration`.
Here you can enable and disable all plugins available, and configure them.
![administration screenshot](https://camo.githubusercontent.com/5da68e191969007492ca0fbeb25f3b2357b748cc/687474703a2f2f692e696d6775722e636f6d2f766837544643712e706e67)
## Plugin order
In the plugin administration page, you can move enabled plugins to the top or bottom of the list. The first plugins in the list will be processed first.
This is important in case plugins are depending on each other. Read plugins README details for more information.
**Use case**: The (non existent) plugin `shaares_footer` adds a footer to every shaare in Markdown syntax. It needs to be processed *before* (higher in the list) the Markdown plugin. Otherwise its syntax won't be translated in HTML.
## File mode
Enabled plugin are stored in your `config.php` parameters file, under the `array`:
```php
$GLOBALS['config']['ENABLED_PLUGINS']
```
You can edit them manually here.
Example:
```php
$GLOBALS['config']['ENABLED_PLUGINS'] = array(
'qrcode',
'archiveorg',
'wallabag',
'markdown',
);
```
### Plugin usage
#### Official plugins
Usage of each plugin is documented in it's README file:
* `addlink-toolbar`: Adds the addlink input on the linklist page
* `archiveorg`: For each link, add an Archive.org icon
* [`markdown`](https://github.com/shaarli/Shaarli/blob/master/plugins/markdown/README.md): Render shaare description with Markdown syntax.
* [`playvideos`](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md): Add a button in the toolbar allowing to watch all videos.
* `qrcode`: For each link, add a QRCode icon.
* [`wallabag`](https://github.com/shaarli/Shaarli/blob/master/plugins/wallabag/README.md): For each link, add a Wallabag icon to save it in your instance.
#### Third party plugins
See [Community & related software](https://shaarli.readthedocs.io/en/master/Community-&-Related-software/)

153
doc/md/REST-API.md Normal file
View file

@ -0,0 +1,153 @@
## Usage and Prerequisites
See the [REST API documentation](http://shaarli.github.io/api-documentation/)
for a list of available endpoints and parameters.
Please ensure that your server meets the [requirements](Server-requirements)
and is properly [configured](Server-configuration):
- URL rewriting is enabled (see specific Apache and Nginx sections)
- the server's timezone is properly defined
- the server's clock is synchronized with
[NTP](https://en.wikipedia.org/wiki/Network_Time_Protocol)
The host where the API client is invoked should also be synchronized with NTP,
see [token expiration](#payload).
## Authentication
All requests to Shaarli's API must include a JWT token to verify their authenticity.
This token has to be included as an HTTP header called `Authentication: Bearer <jwt token>`.
JWT resources :
- [jwt.io](https://jwt.io) (including a list of client per language).
- RFC : https://tools.ietf.org/html/rfc7519
- https://float-middle.com/json-web-tokens-jwt-vs-sessions/
- HackerNews thread: https://news.ycombinator.com/item?id=11929267
### Shaarli JWT Token
JWT tokens are composed by three parts, separated by a dot `.` and encoded in base64:
```
[header].[payload].[signature]
```
#### Header
Shaarli only allow one hash algorithm, so the header will always be the same:
```json
{
"typ": "JWT",
"alg": "HS512"
}
```
Encoded in base64, it gives:
```
ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==
```
#### Payload
**Token expiration**
To avoid infinite token validity, JWT tokens must include their creation date
in UNIX timestamp format (timezone independent - UTC) under the key `iat` (issued at).
This token will be valid during **9 minutes**.
```json
{
"iat": 1468663519
}
```
See [RFC reference](https://tools.ietf.org/html/rfc7519#section-4.1.6).
#### Signature
The signature authenticate the token validity. It contains the base64 of the header and the body, separated by a dot `.`, hashed in SHA512 with the API secret available in Shaarli administration page.
Signature example with PHP:
```php
$content = base64_encode($header) . '.' . base64_encode($payload);
$signature = hash_hmac('sha512', $content, $secret);
```
## Clients and examples
### Android, Java, Kotlin
- [Android client example with Kotlin](https://gitlab.com/snippets/1665808)
by [Braincoke](https://github.com/Braincoke)
### Javascript, NodeJS
- [shaarli-client](https://www.npmjs.com/package/shaarli-client)
([source code](https://github.com/laBecasse/shaarli-client))
by [laBecasse](https://github.com/laBecasse)
### PHP
This example uses the [PHP cURL](http://php.net/manual/en/book.curl.php) library.
```php
<?php
$baseUrl = 'https://shaarli.mydomain.net';
$secret = 'thats_my_api_secret';
function base64url_encode($data) {
return rtrim(strtr(base64_encode($data), '+/', '-_'), '=');
}
function generateToken($secret) {
$header = base64url_encode('{
"typ": "JWT",
"alg": "HS512"
}');
$payload = base64url_encode('{
"iat": '. time() .'
}');
$signature = base64url_encode(hash_hmac('sha512', $header .'.'. $payload , $secret, true));
return $header . '.' . $payload . '.' . $signature;
}
function getInfo($baseUrl, $secret) {
$token = generateToken($secret);
$endpoint = rtrim($baseUrl, '/') . '/api/v1/info';
$headers = [
'Content-Type: text/plain; charset=UTF-8',
'Authorization: Bearer ' . $token,
];
$ch = curl_init($endpoint);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_AUTOREFERER, 1);
curl_setopt($ch, CURLOPT_FRESH_CONNECT, 1);
$result = curl_exec($ch);
curl_close($ch);
return $result;
}
var_dump(getInfo($baseUrl, $secret));
```
### Python
See the reference API client:
- [Documentation](http://python-shaarli-client.readthedocs.io/en/latest/) on ReadTheDocs
- [python-shaarli-client](https://github.com/shaarli/python-shaarli-client) on Github

28
doc/md/RSS-feeds.md Normal file
View file

@ -0,0 +1,28 @@
### Feeds options
Feeds are available in ATOM with `?do=atom` and RSS with `do=RSS`.
Options:
- You can use `permalinks` in the feed URL to get permalink to Shaares instead of direct link to shaared URL.
- E.G. `https://my.shaarli.domain/?do=atom&permalinks`.
- You can use `nb` parameter in the feed URL to specify the number of Shaares you want in a feed (default if not specified: `50`). The keyword `all` is available if you want everything.
- `https://my.shaarli.domain/?do=atom&permalinks&nb=42`
- `https://my.shaarli.domain/?do=atom&permalinks&nb=all`
### RSS Feeds or Picture Wall for a specific search/tag
It is possible to filter RSS/ATOM feeds and Picture Wall on a Shaarli to **only display results of a specific search, or for a specific tag**.
For example, if you want to subscribe only to links tagged `photography`:
- Go to the desired Shaarli instance.
- Search for the `photography` tag in the _Filter by tag_ box. Links tagged `photography` are displayed.
- Click on the `RSS Feed` button.
- You are presented with an RSS feed showing only these links. Subscribe to it to receive only updates with this tag.
- The same method **also works for a full-text search** (_Search_ box) **and for the Picture Wall** (want to only see pictures about `nature`?)
- You can also build the URLs manually:
- `https://my.shaarli.domain/?do=rss&searchtags=nature`
- `https://my.shaarli.domain/links/?do=picwall&searchterm=poney`
![](images/rss-filter-1.png) ![](images/rss-filter-2.png)

161
doc/md/Release-Shaarli.md Normal file
View file

@ -0,0 +1,161 @@
See [Git - Maintaining a project - Tagging your
releases](http://git-scm.com/book/en/v2/Distributed-Git-Maintaining-a-Project#Tagging-Your-Releases).
## Prerequisites
This guide assumes that you have:
- a GPG key matching your GitHub authentication credentials
- i.e., the email address identified by the GPG key is the same as the one in your `~/.gitconfig`
- a GitHub fork of Shaarli
- a local clone of your Shaarli fork, with the following remotes:
- `origin` pointing to your GitHub fork
- `upstream` pointing to the main Shaarli repository
- maintainer permissions on the main Shaarli repository, to:
- push the signed tag
- create a new release
- [Composer](https://getcomposer.org/) needs to be installed
- The [venv](https://docs.python.org/3/library/venv.html) Python 3 module needs to be installed for HTML documentation generation.
## GitHub release draft and `CHANGELOG.md`
See http://keepachangelog.com/en/0.3.0/ for changelog formatting.
### GitHub release draft
GitHub allows drafting the release note for the upcoming release, from the [Releases](https://github.com/shaarli/Shaarli/releases) page. This way, the release note can be drafted while contributions are merged to `master`.
### `CHANGELOG.md`
This file should contain the same information as the release note draft for the upcoming version.
Update it to:
- add new entries (additions, fixes, etc.)
- mark the current version as released by setting its date and link
- add a new section for the future unreleased version
```bash
$ cd /path/to/shaarli
$ nano CHANGELOG.md
[...]
## vA.B.C - UNRELEASED
TBA
## [vX.Y.Z](https://github.com/shaarli/Shaarli/releases/tag/vX.Y.Z) - YYYY-MM-DD
[...]
```
## Increment the version code, update docs, create and push a signed tag
### Update the list of Git contributors
```bash
$ make authors
$ git commit -s -m "Update AUTHORS"
```
### Create and merge a Pull Request
This one is pretty straightforward ;-)
### Bump Shaarli version to v0.x branch
```bash
$ git checkout master
$ git fetch upstream
$ git pull upstream master
# IF the branch doesn't exists
$ git checkout -b v0.5
# OR if the branch already exists
$ git checkout v0.5
$ git rebase upstream/master
# Bump shaarli version from dev to 0.5.0, **without the `v`**
$ vim shaarli_version.php
$ git add shaarli_version
$ git commit -s -m "Bump Shaarli version to v0.5.0"
$ git push upstream v0.5
```
### Create and push a signed tag
```bash
# update your local copy
$ git checkout v0.5
$ git fetch upstream
$ git pull upstream v0.5
# create a signed tag
$ git tag -s -m "Release v0.5.0" v0.5.0
# push it to "upstream"
$ git push --tags upstream
```
### Verify a signed tag
[`v0.5.0`](https://github.com/shaarli/Shaarli/releases/tag/v0.5.0) is the first GPG-signed tag pushed on the Community Shaarli.
Let's have a look at its signature!
```bash
$ cd /path/to/shaarli
$ git fetch upstream
# get the SHA1 reference of the tag
$ git show-ref tags/v0.5.0
f7762cf803f03f5caf4b8078359a63783d0090c1 refs/tags/v0.5.0
# verify the tag signature information
$ git verify-tag f7762cf803f03f5caf4b8078359a63783d0090c1
gpg: Signature made Thu 30 Jul 2015 11:46:34 CEST using RSA key ID 4100DF6F
gpg: Good signature from "VirtualTam <virtualtam@flibidi.net>" [ultimate]
```
## Publish the GitHub release
### Update release badges
Update `README.md` so version badges display and point to the newly released Shaarli version(s), in the `master` branch.
### Create a GitHub release from a Git tag
From the previously drafted release:
- edit the release notes (if needed)
- specify the appropriate Git tag
- publish the release
- profit!
### Generate and upload all-in-one release archives
Users with a shared hosting may have:
- no SSH access
- no possibility to install PHP packages or server extensions
- no possibility to run scripts
To ease Shaarli installations, it is possible to generate and upload additional release archives,
that will contain Shaarli code plus all required third-party libraries.
**From the `v0.5` branch:**
```bash
$ make release_archive
```
This will create the following archives:
- `shaarli-vX.Y.Z-full.tar`
- `shaarli-vX.Y.Z-full.zip`
The archives need to be manually uploaded on the previously created GitHub release.
### Update `stable` and `latest` branches
```
$ git checkout latest
# latest release
$ git merge v0.5.0
# fix eventual conflicts
$ make test
$ git push upstream latest
$ git checkout stable
# latest previous major
$ git merge v0.4.5
# fix eventual conflicts
$ make test
$ git push upstream stable
```

25
doc/md/Security.md Normal file
View file

@ -0,0 +1,25 @@
## Client browser
- Shaarli relies on `HTTP_REFERER` for some functions (like redirects and clicking on tags). If you have disabled or masqueraded `HTTP_REFERER` in your browser, some features of Shaarli may not work
## Server and sessions
- Directories are protected using `.htaccess` files
- Forms are protected against XSRF (Cross-site requests forgery):
- Forms which act on data (save,delete…) contain a token generated by the server.
- Any posted form which does not contain a valid token is rejected.
- Any token can only be used once.
- Tokens are attached to the session and cannot be reused in another session.
- Sessions automatically expire after 60 minutes.
- Sessions are protected against hijacking: the session ID cannot be used from a different IP address.
## Shaarli datastore and configuration
- The password is salted, hashed and stored in the data subdirectory, in a PHP file, and protected by htaccess. Even if the webserver does not support htaccess, the hash is not readable by URL. Even if the .php file is stolen, the password cannot deduced from the hash. The salt prevents rainbow-tables attacks.
- Links are stored as an associative array which is serialized, compressed (with deflate), base64-encoded and saved as a comment in a `.php` file.
- Even if the server does not support `.htaccess` files, the data file will still not be readable by URL.
- The database looks like this:
```php
<?php /* zP1ZjxxJtiYIvvevEPJ2lDOaLrZv7o...
...ka7gaco/Z+TFXM2i7BlfMf8qxpaSSYfKlvqv/x8= */ ?>
```
- Small hashes are used to make a link to an entry in Shaarli. They are unique. In fact, the date of the items (eg. `20110923_150523`) is hashed with CRC32, then converted to base64 and some characters are replaced. They are always 6 characters longs and use only `A-Z a-z 0-9 - _` and `@`.

406
doc/md/Server-configuration.md Normal file
View file

@ -0,0 +1,406 @@
*Example virtual host configurations for popular web servers*
- [Apache](#apache)
- [Nginx](#nginx)
## Prerequisites
### Shaarli
- Shaarli is installed in a directory readable/writeable by the user
- the correct read/write permissions have been granted to the web server _user and/or group_
- for HTTPS / SSL:
- a key pair (public, private) and a certificate have been generated
- the appropriate server SSL extension is installed and active
### HTTPS, TLS and self-signed certificates
Related guides:
- [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php)
- [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority)
- Generate a self-signed certificate (will trigger browser warnings) with apache2:
`make-ssl-cert generate-default-snakeoil --force-overwrite` will create `/etc/ssl/certs/ssl-cert-snakeoil.pem` and `/etc/ssl/private/ssl-cert-snakeoil.key`
### Proxies
If Shaarli is served behind a proxy (i.e. there is a proxy server between clients and the web server hosting Shaarli), please refer to the proxy server documentation for proper configuration. In particular, you have to ensure that the following server variables are properly set:
- `X-Forwarded-Proto`
- `X-Forwarded-Host`
- `X-Forwarded-For`
See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%93&q=label%3Aproxy+) issues.
## Apache
### Minimal
```apache
<VirtualHost *:80>
ServerName shaarli.my-domain.org
DocumentRoot /absolute/path/to/shaarli/
</VirtualHost>
```
### Debug - Log all the things!
This configuration will log both Apache and PHP errors, which may prove useful to identify server configuration errors.
See:
- [Apache/PHP - error log per VirtualHost](http://stackoverflow.com/q/176) (StackOverflow)
- [PHP: php_value vs php_admin_value and the use of php_flag explained](https://ma.ttias.be/php-php_value-vs-php_admin_value-and-the-use-of-php_flag-explained/)
```apache
<VirtualHost *:80>
ServerName shaarli.my-domain.org
DocumentRoot /absolute/path/to/shaarli/
LogLevel warn
ErrorLog /var/log/apache2/shaarli-error.log
CustomLog /var/log/apache2/shaarli-access.log combined
php_flag log_errors on
php_flag display_errors on
php_value error_reporting 2147483647
php_value error_log /var/log/apache2/shaarli-php-error.log
</VirtualHost>
```
### Standard - Keep access and error logs
```apache
<VirtualHost *:80>
ServerName shaarli.my-domain.org
DocumentRoot /absolute/path/to/shaarli/
LogLevel warn
ErrorLog /var/log/apache2/shaarli-error.log
CustomLog /var/log/apache2/shaarli-access.log combined
</VirtualHost>
```
### Paranoid - Redirect HTTP (:80) to HTTPS (:443)
See [Server-side TLS](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache) (Mozilla).
```apache
<VirtualHost *:443>
ServerName shaarli.my-domain.org
DocumentRoot /absolute/path/to/shaarli/
SSLEngine on
SSLCertificateFile /absolute/path/to/the/website/certificate.pem
SSLCertificateKeyFile /absolute/path/to/the/website/key.key
<Directory /absolute/path/to/shaarli/>
AllowOverride All
Options Indexes FollowSymLinks MultiViews
Order allow,deny
allow from all
</Directory>
LogLevel warn
ErrorLog /var/log/apache2/shaarli-error.log
CustomLog /var/log/apache2/shaarli-access.log combined
</VirtualHost>
<VirtualHost *:80>
ServerName shaarli.my-domain.org
Redirect 301 / https://shaarli.my-domain.org
LogLevel warn
ErrorLog /var/log/apache2/shaarli-error.log
CustomLog /var/log/apache2/shaarli-access.log combined
</VirtualHost>
```
### .htaccess
Shaarli use `.htaccess` Apache files to deny access to files that shouldn't be directly accessed (datastore, config, etc.). You need the directive `AllowOverride All` in your virtual host configuration for them to work.
**Warning**: If you use Apache 2.2 or lower, you need [mod_version](https://httpd.apache.org/docs/current/mod/mod_version.html) to be installed and enabled.
Apache module `mod_rewrite` **must** be enabled to use the REST API. URL rewriting rules for the Slim microframework are stated in the root `.htaccess` file.
## LightHttpd
## Nginx
### Foreword
Nginx does not natively interpret PHP scripts; to this effect, we will run a [FastCGI](https://en.wikipedia.org/wiki/FastCGI) service, to which Nginx's FastCGI module will proxy all requests to PHP resources.
Required packages:
- [nginx](http://nginx.org)
- [php-fpm](http://php-fpm.org) - PHP FastCGI Process Manager
Official documentation:
- [Beginner's guide](http://nginx.org/en/docs/beginners_guide.html)
- [ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html)
- [Pitfalls](http://wiki.nginx.org/Pitfalls)
Community resources:
- [Server-side TLS (Nginx)](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) (Mozilla)
- [PHP configuration examples](http://kbeezie.com/nginx-configuration-examples/) (Karl Blessing)
### Common setup
Once Nginx and PHP-FPM are installed, we need to ensure:
- Nginx and PHP-FPM are running using the _same user and group_
- both these user and group have
- `read` permissions for Shaarli resources
- `execute` permissions for Shaarli directories _AND_ their parent directories
On a production server:
- `user:group` will likely be `http:http`, `www:www` or `www-data:www-data`
- files will be located under `/var/www`, `/var/http` or `/usr/share/nginx`
On a development server:
- files may be located in a user's home directory
- in this case, make sure both Nginx and PHP-FPM are running as the local user/group!
For all following configuration examples, this user/group pair will be used:
- `user:group = john:users`,
which corresponds to the following service configuration:
```ini
; /etc/php/php-fpm.conf
user = john
group = users
[...]
listen.owner = john
listen.group = users
```
```nginx
# /etc/nginx/nginx.conf
user john users;
http {
[...]
}
```
### (Optional) Increase the maximum file upload size
Some bookmark dumps generated by web browsers can be _huge_ due to the presence of Base64-encoded images and favicons, as well as extra verbosity when nesting links in (sub-)folders.
To increase upload size, you will need to modify both nginx and PHP configuration:
```nginx
# /etc/nginx/nginx.conf
http {
[...]
client_max_body_size 10m;
[...]
}
```
```ini
# /etc/php5/fpm/php.ini
[...]
post_max_size = 10M
[...]
upload_max_filesize = 10M
```
### Minimal
_WARNING: Use for development only!_
```nginx
user john users;
worker_processes 1;
events {
worker_connections 1024;
}
http {
include mime.types;
default_type application/octet-stream;
keepalive_timeout 20;
index index.html index.php;
server {
listen 80;
server_name localhost;
root /home/john/web;
access_log /var/log/nginx/access.log;
error_log /var/log/nginx/error.log;
location /shaarli/ {
try_files $uri /shaarli/index.php$is_args$args;
access_log /var/log/nginx/shaarli.access.log;
error_log /var/log/nginx/shaarli.error.log;
}
location ~ (index)\.php$ {
try_files $uri =404;
fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
fastcgi_index index.php;
include fastcgi.conf;
}
}
}
```
### Modular
The previous setup is sufficient for development purposes, but has several major caveats:
- every content that does not match the PHP rule will be sent to client browsers:
- dotfiles - in our case, `.htaccess`
- temporary files, e.g. Vim or Emacs files: `index.php~`
- asset / static resource caching is not optimized
- if serving several PHP sites, there will be a lot of duplication: `location /shaarli/`, `location /mysite/`, etc.
To solve this, we will split Nginx configuration in several parts, that will be included when needed:
```nginx
# /etc/nginx/deny.conf
location ~ /\. {
# deny access to dotfiles
access_log off;
log_not_found off;
deny all;
}
location ~ ~$ {
# deny access to temp editor files, e.g. "script.php~"
access_log off;
log_not_found off;
deny all;
}
```
```nginx
# /etc/nginx/php.conf
location ~ (index)\.php$ {
# Slim - split URL path into (script_filename, path_info)
try_files $uri =404;
fastcgi_split_path_info ^(.+\.php)(/.+)$;
# filter and proxy PHP requests to PHP-FPM
fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
fastcgi_index index.php;
include fastcgi.conf;
}
location ~ \.php$ {
# deny access to all other PHP scripts
deny all;
}
```
```nginx
# /etc/nginx/static_assets.conf
location ~* \.(?:ico|css|js|gif|jpe?g|png)$ {
expires max;
add_header Pragma public;
add_header Cache-Control "public, must-revalidate, proxy-revalidate";
}
```
```nginx
# /etc/nginx/nginx.conf
[...]
http {
[...]
root /home/john/web;
access_log /var/log/nginx/access.log;
error_log /var/log/nginx/error.log;
server {
# virtual host for a first domain
listen 80;
server_name my.first.domain.org;
location /shaarli/ {
# Slim - rewrite URLs
try_files $uri /shaarli/index.php$is_args$args;
access_log /var/log/nginx/shaarli.access.log;
error_log /var/log/nginx/shaarli.error.log;
}
location = /shaarli/favicon.ico {
# serve the Shaarli favicon from its custom location
alias /var/www/shaarli/images/favicon.ico;
}
include deny.conf;
include static_assets.conf;
include php.conf;
}
server {
# virtual host for a second domain
listen 80;
server_name second.domain.com;
location /minigal/ {
access_log /var/log/nginx/minigal.access.log;
error_log /var/log/nginx/minigal.error.log;
}
include deny.conf;
include static_assets.conf;
include php.conf;
}
}
```
### Redirect HTTP to HTTPS
Assuming you have generated a (self-signed) key and certificate, and they are
located under `/home/john/ssl/localhost.{key,crt}`, it is pretty straightforward
to set an HTTP (:80) to HTTPS (:443) redirection to force SSL/TLS usage.
```nginx
# /etc/nginx/nginx.conf
[...]
http {
[...]
index index.html index.php;
root /home/john/web;
access_log /var/log/nginx/access.log;
error_log /var/log/nginx/error.log;
server {
listen 80;
server_name localhost;
return 301 https://localhost$request_uri;
}
server {
listen 443 ssl;
server_name localhost;
ssl_certificate /home/john/ssl/localhost.crt;
ssl_certificate_key /home/john/ssl/localhost.key;
location /shaarli/ {
# Slim - rewrite URLs
try_files $uri /index.php$is_args$args;
access_log /var/log/nginx/shaarli.access.log;
error_log /var/log/nginx/shaarli.error.log;
}
location = /shaarli/favicon.ico {
# serve the Shaarli favicon from its custom location
alias /var/www/shaarli/images/favicon.ico;
}
include deny.conf;
include static_assets.conf;
include php.conf;
}
}
```

41
doc/md/Server-requirements.md Normal file
View file

@ -0,0 +1,41 @@
## PHP
### Release information
- [PHP: Supported versions](http://php.net/supported-versions.php)
- [PHP: Unsupported versions](http://php.net/eol.php) _(EOL - End Of Life)_
- [PHP 7 Changelog](http://php.net/ChangeLog-7.php)
- [PHP 5 Changelog](http://php.net/ChangeLog-5.php)
- [PHP: Bugs](https://bugs.php.net/)
### Supported versions
Version | Status | Shaarli compatibility
:---:|:---:|:---:
7.1 | Supported (v0.9.x) | Yes
7.0 | Supported | Yes
5.6 | Supported | Yes
5.5 | EOL: 2016-07-10 | Yes
5.4 | EOL: 2015-09-14 | Yes (up to Shaarli 0.8.x)
5.3 | EOL: 2014-08-14 | Yes (up to Shaarli 0.8.x)
See also:
- [Travis configuration](https://github.com/shaarli/Shaarli/blob/master/.travis.yml)
### Dependency management
Starting with Shaarli `v0.8.x`, [Composer](https://getcomposer.org/) is used to resolve,
download and install third-party PHP dependencies.
Library | Required? | Usage
---|:---:|---
[`shaarli/netscape-bookmark-parser`](https://packagist.org/packages/shaarli/netscape-bookmark-parser) | All | Import bookmarks from Netscape files
[`erusev/parsedown`](https://packagist.org/packages/erusev/parsedown) | All | Parse MarkDown syntax for the MarkDown plugin
[`slim/slim`](https://packagist.org/packages/slim/slim) | All | Handle routes and middleware for the REST API
### Extensions
Extension | Required? | Usage
---|:---:|---
[`openssl`](http://php.net/manual/en/book.openssl.php) | All | OpenSSL, HTTPS
[`php-mbstring`](http://php.net/manual/en/book.mbstring.php) | CentOS, Fedora, RHEL, Windows | multibyte (Unicode) string support
[`php-gd`](http://php.net/manual/en/book.image.php) | optional | thumbnail resizing
[`php-intl`](http://php.net/manual/en/book.intl.php) | optional | localized text sorting (e.g. `e->è->f`)
[`php-curl`](http://php.net/manual/en/book.curl.php) | optional | using cURL for fetching webpages and thumbnails in a more robust way

76
doc/md/Server-security.md Normal file
View file

@ -0,0 +1,76 @@
## php.ini
PHP settings are defined in:
- a main configuration file, usually found under `/etc/php5/php.ini`; some distributions provide different configuration environments, e.g.
- `/etc/php5/php.ini` - used when running console scripts
- `/etc/php5/apache2/php.ini` - used when a client requests PHP resources from Apache
- `/etc/php5/php-fpm.conf` - used when PHP requests are proxied to PHP-FPM
- additional configuration files/entries, depending on the installed/enabled extensions:
- `/etc/php/conf.d/xdebug.ini`
### Locate .ini files
#### Console environment
```bash
$ php --ini
Configuration File (php.ini) Path: /etc/php
Loaded Configuration File: /etc/php/php.ini
Scan for additional .ini files in: /etc/php/conf.d
Additional .ini files parsed: /etc/php/conf.d/xdebug.ini
```
#### Server environment
- create a `phpinfo.php` script located in a path supported by the web server, e.g.
- Apache (with user dirs enabled): `/home/myself/public_html/phpinfo.php`
- `/var/www/test/phpinfo.php`
- make sure the script is readable by the web server user/group (usually, `www`, `www-data` or `httpd`)
- access the script from a web browser
- look at the _Loaded Configuration File_ and _Scan this dir for additional .ini files_ entries
```php
<?php phpinfo(); ?>
```
## fail2ban
`fail2ban` is an intrusion prevention framework that reads server (Apache, SSH, etc.) and uses `iptables` profiles to block brute-force attempts:
- [Official website](http://www.fail2ban.org/wiki/index.php/Main_Page)
- [Source code](https://github.com/fail2ban/fail2ban)
### Read Shaarli logs to ban IPs
Example configuration:
- allow 3 login attempts per IP address
- after 3 failures, permanently ban the corresponding IP adddress
`/etc/fail2ban/jail.local`
```ini
[shaarli-auth]
enabled = true
port = https,http
filter = shaarli-auth
logpath = /var/www/path/to/shaarli/data/log.txt
maxretry = 3
bantime = -1
```
`/etc/fail2ban/filter.d/shaarli-auth.conf`
```ini
[INCLUDES]
before = common.conf
[Definition]
failregex = \s-\s<HOST>\s-\sLogin failed for user.*$
ignoreregex =
```
## Robots - Restricting search engines and web crawler traffic
Creating a `robots.txt` with the following contents at the root of your Shaarli installation will prevent _honest_ web crawlers from indexing each and every link and Daily page from a Shaarli instance, thus getting rid of a certain amount of unsollicited network traffic.
```
User-agent: *
Disallow: /
```
See:
- http://www.robotstxt.org
- http://www.robotstxt.org/robotstxt.html
- http://www.robotstxt.org/meta.html

223
doc/md/Shaarli-configuration.md Normal file
View file

@ -0,0 +1,223 @@
## Foreword
**Do not edit configuration options in index.php! Your changes would be lost.**
Once your Shaarli instance is installed, the file `data/config.json.php` is generated:
* it contains all settings in JSON format, and can be edited to customize values
* it defines which [plugins](Plugin-System) are enabled[](.html)
* its values override those defined in `index.php`
* it is wrap in a PHP comment to prevent anyone accessing it, regardless of server configuration
## File and directory permissions
The server process running Shaarli must have:
- `read` access to the following resources:
- PHP scripts: `index.php`, `application/*.php`, `plugins/*.php`
- 3rd party PHP and Javascript libraries: `inc/*.php`, `inc/*.js`
- static assets:
- CSS stylesheets: `inc/*.css`
- `images/*`
- RainTPL templates: `tpl/*.html`
- `read`, `write` and `execution` access to the following directories:
- `cache` - thumbnail cache
- `data` - link data store, configuration options
- `pagecache` - Atom/RSS feed cache
- `tmp` - RainTPL page cache
On a Linux distribution:
- the web server user will likely be `www` or `http` (for Apache2)
- it will be a member of a group of the same name: `www:www`, `http:http`
- to give it access to Shaarli, either:
- unzip Shaarli in the default web server location (usually `/var/www/`) and set the web server user as the owner
- put users in the same group as the web server, and set the appropriate access rights
- if you have a domain / subdomain to serve Shaarli, [configure the server](Server-configuration) accordingly[](.html)
## Configuration
In `data/config.json.php`.
See also [Plugin System](Plugin-System.html).
### Credentials
_These settings should not be edited_
- **login**: Login username.
- **hash**: Generated password hash.
- **salt**: Password salt.
### General
- **title**: Shaarli's instance title.
- **header_link**: Link to the homepage.
- **links_per_page**: Number of shaares displayed per page.
- **timezone**: See [the list of supported timezones](http://php.net/manual/en/timezones.php).
- **enabled_plugins**: List of enabled plugins.
- **default_note_title**: Default title of a new note.
### Security
- **session_protection_disabled**: Disable session cookie hijacking protection (not recommended).
It might be useful if your IP adress often changes.
- **ban_after**: Failed login attempts before being IP banned.
- **ban_duration**: IP ban duration in seconds.
- **open_shaarli**: Anyone can add a new link while logged out if enabled.
- **trusted_proxies**: List of trusted IP which won't be banned after failed login attemps. Useful if Shaarli is behind a reverse proxy.
- **allowed_protocols**: List of allowed protocols in shaare URLs or markdown-rendered descriptions. Useful if you want to store `javascript:` links (bookmarklets) in Shaarli (default: `["ftp", "ftps", "magnet"]`).
### Resources
- **data_dir**: Data directory.
- **datastore**: Shaarli's links database file path.
- **history**: Shaarli's operation history file path.
- **updates**: File path for the ran updates file.
- **log**: Log file path.
- **update_check**: Last update check file path.
- **raintpl_tpl**: Templates directory.
- **raintpl_tmp**: Template engine cache directory.
- **thumbnails_cache**: Thumbnails cache directory.
- **page_cache**: Shaarli's internal cache directory.
- **ban_file**: Banned IP file path.
### Updates
- **check_updates**: Enable or disable update check to the git repository.
- **check_updates_branch**: Git branch used to check updates (e.g. `stable` or `master`).
- **check_updates_interval**: Look for new version every N seconds (default: every day).
### Privacy
- **default_private_links**: Check the private checkbox by default for every new link.
- **hide_public_links**: All links are hidden while logged out.
- **force_login**: if **hide_public_links** and this are set to `true`, all anonymous users are redirected to the login page.
- **hide_timestamps**: Timestamps are hidden.
- **remember_user_default**: Default state of the login page's *remember me* checkbox
- `true`: checked by default, `false`: unchecked by default
### Feed
- **rss_permalinks**: Enable this to redirect RSS links to Shaarli's permalinks instead of shaared URL.
- **show_atom**: Display ATOM feed button.
### Thumbnail
- **enable_thumbnails**: Enable or disable thumbnail display.
- **enable_localcache**: Enable or disable local cache.
### Redirector
- **url**: Redirector URL, such as `anonym.to`.
- **encode_url**: Enable this if the redirector needs encoded URL to work properly.
## Configuration file example
```json
<?php /*
{
"credentials": {
"login": "<login>",
"hash": "<password hash>",
"salt": "<password salt>"
},
"security": {
"ban_after": 4,
"session_protection_disabled": false,
"ban_duration": 1800,
"trusted_proxies": [
"1.2.3.4",
"5.6.7.8"
],
"allowed_protocols": [
"ftp",
"ftps",
"magnet"
]
},
"resources": {
"data_dir": "data",
"config": "data\/config.php",
"datastore": "data\/datastore.php",
"ban_file": "data\/ipbans.php",
"updates": "data\/updates.txt",
"log": "data\/log.txt",
"update_check": "data\/lastupdatecheck.txt",
"raintpl_tmp": "tmp\/",
"raintpl_tpl": "tpl\/",
"thumbnails_cache": "cache",
"page_cache": "pagecache"
},
"general": {
"check_updates": true,
"rss_permalinks": true,
"links_per_page": 20,
"default_private_links": true,
"enable_thumbnails": true,
"enable_localcache": true,
"check_updates_branch": "stable",
"check_updates_interval": 86400,
"enabled_plugins": [
"markdown",
"wallabag",
"archiveorg"
],
"timezone": "Europe\/Paris",
"title": "My Shaarli",
"header_link": "?"
},
"extras": {
"show_atom": false,
"hide_public_links": false,
"hide_timestamps": false,
"open_shaarli": false,
"redirector": "http://anonym.to/?",
"redirector_encode_url": false
},
"general": {
"header_link": "?",
"links_per_page": 20,
"enabled_plugins": [
"markdown",
"wallabag"
],
"timezone": "Europe\/Paris",
"title": "My Shaarli"
},
"updates": {
"check_updates": true,
"check_updates_branch": "stable",
"check_updates_interval": 86400
},
"feed": {
"rss_permalinks": true,
"show_atom": false
},
"privacy": {
"default_private_links": true,
"hide_public_links": false,
"force_login": false,
"hide_timestamps": false,
"remember_user_default": true
},
"thumbnail": {
"enable_thumbnails": true,
"enable_localcache": true
},
"redirector": {
"url": "http://anonym.to/?",
"encode_url": false
},
"plugins": {
"WALLABAG_URL": "http://demo.wallabag.org",
"WALLABAG_VERSION": "1"
}
} ?>
```
## Additional configuration
The `playvideos` plugin may require that you adapt your server's
[Content Security Policy](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md#troubleshooting)
configuration to work properly.

13
doc/md/Static-analysis.md Normal file
View file

@ -0,0 +1,13 @@
## WIP
This topic is currently being discussed here:
- [Fix coding style (static analysis)](https://github.com/shaarli/Shaarli/issues/95) (#95)
- [Continuous Integration tools & features](https://github.com/shaarli/Shaarli/issues/130) (#130)
### Usage
Static analysis tools can be installed with Composer, and used through Shaarli's [Makefile](https://github.com/shaarli/Shaarli/blob/master/Makefile).
For an overview of the available features, see:
- [Code quality: Makefile to run static code checkers](https://github.com/shaarli/Shaarli/pull/124) (#124)
- [Run PHPCS against different coding standards](https://github.com/shaarli/Shaarli/pull/276) (#276)

85
doc/md/Theming.md Normal file
View file

@ -0,0 +1,85 @@
## Foreword
There are two ways of customizing how Shaarli looks:
1. by using a custom CSS to override Shaarli's CSS
2. by using a full theme that provides its own RainTPL templates, CSS and Javascript resources
## Custom CSS
Shaarli's appearance can be modified by adding CSS rules to:
- Shaarli < `v0.9.0`: `inc/user.css`
- Shaarli >= `v0.9.0`: `data/user.css`
This file allows overriding rules defined in the template CSS files (only add changed rules), or define a whole new theme.
**Note**: Do not edit `tpl/default/css/shaarli.css`! Your changes would be overridden when updating Shaarli.
See also [Download CSS styles from an OPML list](Download CSS styles from an OPML list)
## Themes
Installation:
- find a theme you'd like to install
- copy or clone the theme folder under `tpl/<a_sweet_theme>`
- enable the theme:
- Shaarli < `v0.9.0`: edit `data/config.json.php` and set the value of `raintpl_tpl` to the new theme name:
`"raintpl_tpl": "tpl\/my-template\/"`
- Shaarli >= `v0.9.0`: select the theme through the _Tools_ page
## Community CSS & themes
### Custom CSS
- [mrjovanovic/serious-theme-shaarli](https://github.com/mrjovanovic/serious-theme-shaarli) - A serious theme for Shaarli
- [shaarli/shaarli-themes](https://github.com/shaarli/shaarli-themes)
### Themes
- [AkibaTech/Shaarli Superhero Theme](https://github.com/AkibaTech/Shaarli---SuperHero-Theme) - A template/theme for Shaarli
- [alexisju/albinomouse-template](https://github.com/alexisju/albinomouse-template) - A full template for Shaarli
- [ArthurHoaro/shaarli-launch](https://github.com/ArthurHoaro/shaarli-launch) - Customizable Shaarli theme
- [dhoko/ShaarliTemplate](https://github.com/dhoko/ShaarliTemplate) - A template/theme for Shaarli
- [kalvn/shaarli-blocks](https://github.com/kalvn/shaarli-blocks) - A template/theme for Shaarli
- [kalvn/Shaarli-Material](https://github.com/kalvn/Shaarli-Material) - A theme (template) based on Google's Material Design for Shaarli, the superfast delicious clone
- [ManufacturaInd/shaarli-2004licious-theme](https://github.com/ManufacturaInd/shaarli-2004licious-theme) - A template/theme as a humble homage to the early looks of the del.icio.us site
### Shaarli forks
- [misterair/Limonade](https://github.com/misterair/limonade) - A fork of (legacy) Shaarli with a new template
- [vivienhaese/shaarlitheme](https://github.com/vivienhaese/shaarlitheme) - A Shaarli fork meant to be run in an openshift instance
## Example installation: AlbinoMouse theme
With the following configuration:
- Apache 2 / PHP 5.6
- user sites are enabled, e.g. `/home/user/public_html/somedir` is served as `http://localhost/~user/somedir`
- `http` is the name of the Apache user
```bash
$ cd ~/public_html
# clone repositories
$ git clone https://github.com/shaarli/Shaarli.git shaarli
$ pushd shaarli/tpl
$ git clone https://github.com/alexisju/albinomouse-template.git
$ popd
# set access rights for Apache
$ chgrp -R http shaarli
$ chmod g+rwx shaarli shaarli/cache shaarli/data shaarli/pagecache shaarli/tmp
```
Get config written:
- go to the freshly installed site
- fill the install form
- log in to Shaarli
Edit Shaarli's [configuration](Shaarli-configuration):
```bash
# the file should be owned by Apache, thus not writeable => sudo
$ sudo sed -i s=tpl=tpl/albinomouse-template=g shaarli/data/config.php
```

132
doc/md/Troubleshooting.md Normal file
View file

@ -0,0 +1,132 @@
# Troubleshooting
## Browser
### Redirection issues (HTTP Referer)
Depending on its configuration and installed plugins, the browser may remove or alter (spoof) HTTP referers, thus preventing Shaarli from properly redirecting between pages.
See:
- [HTTP referer](https://en.wikipedia.org/wiki/HTTP_referer) (Wikipedia)
- [Improve online privacy by controlling referrer information](http://www.ghacks.net/2015/01/22/improve-online-privacy-by-controlling-referrer-information/)
- [Better security, privacy and anonymity in Firefox](http://b.agilob.net/better-security-privacy-and-anonymity-in-firefox/)
### Firefox HTTP Referer options
HTTP settings are available by browsing `about:config`, here are the available settings and their values.
`network.http.sendRefererHeader` - determines when to send the Referer HTTP header
- `0`: Never send the referring URL
- not recommended, may break some sites
- `1`: Send only on clicked links
- `2` (default): Send for links and images
`network.http.referer.XOriginPolicy` - Cross-domain origin policy
- `0` (default): Always send
- `1`: Send if base domains match
- `2`: Send if hosts match
`network.http.referer.spoofSource` - Referer spoofing (~faking)
- `false` (default): real referer
- `true`: spoof referer (use target URI as referer)
- known to break some functionality in Shaarli
`network.http.referer.trimmingPolicy` - trim the URI not to send a full Referer
- `0`: (default): send full URI
- `1`: scheme+host+port+path
- `2`: scheme+host+port
### Firefox, localhost and redirections
`localhost` is not a proper Fully Qualified Domain Name (FQDN); if Firefox has
been set up to spoof referers, or only accept requests from the same base domain/host,
Shaarli redirections will not work properly.
To solve this, assign a local domain to your host, e.g.
```
127.0.0.1 localhost desktop localhost.lan
::1 localhost desktop localhost.lan
```
and browse Shaarli at http://localhost.lan/.
Related threads:
- [What is localhost.localdomain for?](https://bbs.archlinux.org/viewtopic.php?id=156064)
- [Stop returning to the first page after editing a bookmark from another page](https://github.com/shaarli/Shaarli/issues/311)
## Login
### I forgot my password!
Delete the file `data/config.php` and display the page again. You will be asked for a new login/password.
### I'm locked out - Login bruteforce protection
Login form is protected against brute force attacks: 4 failed logins will ban the IP address from login for 30 minutes. Banned IPs can still browse links.
To remove the current IP bans, delete the file `data/ipbans.php`
### List of all login attempts
The file `data/log.txt` shows all logins (successful or failed) and bans/lifted bans.
Search for `failed` in this file to look for unauthorized login attempts.
## Hosting problems
### Old PHP versions
On **free.fr**: free.fr now supports php 5.6.x([link](http://les.pages.perso.chez.free.fr/migrations/php5v6.io))
and so support now the tag autocompletion but you have to do the following.
At the root of your webspace create a `sessions` directory and a `.htaccess` file containing:
```xml
<IfDefine Free>
php56 1
</IfDefine>
```
- If you have an error such as: `Parse error: syntax error, unexpected '=', expecting '(' in /links/index.php on line xxx`, it means that your host is using php4, not php5. Shaarli requires php 5.1. Try changing the file extension to `.php5`
- On **1and1** : If you add the link from the page (and not from the bookmarklet), Shaarli will no be able to get the title of the page. You will have to enter it manually. (Because they have disabled the ability to download a file through HTTP).
- If you have the error `Warning: file_get_contents() [function.file-get-contents]: URL file-access is disabled in the server configuration in /…/index.php on line xxx`, it means that your host has disabled the ability to fetch a file by HTTP in the php config (Typically in 1and1 hosting). Bad host. Change host. Or comment the following lines:
```php
//list($status,$headers,$data) = getHTTP($url,4); // Short timeout to keep the application responsive.
// FIXME: Decode charset according to charset specified in either 1) HTTP response headers or 2) <head> in html
//if (strpos($status,'200 OK')) $title=html_extract_title($data);
```
- On hosts which forbid outgoing HTTP requests (such as free.fr), some thumbnails will not work.
- On **lost-oasis**, RSS doesn't work correctly, because of this message at the begining of the RSS/ATOM feed : `<? // tout ce qui est charge ici (generalement des includes et require) est charge en permanence. ?>`. To fix this, remove this message from `php-include/prepend.php`
### Dates are not properly formatted
Shaarli tries to sniff the language of the browser (using HTTP_ACCEPT_LANGUAGE headers) and choose a date format accordingly. But Shaarli can only use the date formats (and more generaly speaking, the locales) provided by the webserver. So even if you have a browser in French, you may end up with dates in US format (it's the case on sebsauvage.net :-( )
### Problems on CentOS servers
On **CentOS**/RedHat derivatives, you may need to install the `php-mbstring` package.
### My session expires! I can't stay logged in
This can be caused by several things:
- Your php installation may not have a proper directory setup for session files. (eg. on Free.fr you need to create a `session` directory on the root of your website.) You may need to create the session directory of set it up.
- Most hosts regularly clean the temporary and session directories. Your host may be cleaning those directories too aggressively (eg.OVH hosts), forcing an expire of the session. You may want to set the session directory in your web root. (eg. Create the `sessions` subdirectory and add `ini_set('session.save_path', $_SERVER['DOCUMENT_ROOT'].'/../sessions');`. Make sure this directory is not browsable !)
- If your IP address changes during surfing, Shaarli will force expire your session for security reasons (to prevent session cookie hijacking). This can happen when surfing from WiFi or 3G (you may have switched WiFi/3G access point), or in some corporate/university proxies which use load balancing (and may have proxies with several external IP addresses).
- Some browser addons may interfer with HTTP headers (ipfuck/ipflood/GreaseMonkey…). Try disabling those.
- You may be using OperaTurbo or OperaMini, which use their own proxies which may change from time to time.
- If you have another application on the same webserver where Shaarli is installed, these application may forcefully expire php sessions.
## Sessions do not seem to work correctly on your server
Follow the instructions in the error message. Make sure you are accessing shaarli via a direct IP address or a proper hostname. If you have **no dots** in the hostname (e.g. `localhost` or `http://my-webserver/shaarli/`), some browsers will not store cookies at all (this respects the [HTTP cookie specification](http://curl.haxx.se/rfc/cookie_spec.html)).
### pubsubhubbub support
Download [publisher.php](https://pubsubhubbub.googlecode.com/git/publisher_clients/php/library/publisher.php) at the root of your Shaarli installation and set `$GLOBALS['config']['PUBSUBHUB_URL']` in your `config.php`

56
doc/md/Unit-tests-Docker.md Normal file
View file

@ -0,0 +1,56 @@
## Running tests inside Docker containers
Read first:
- [Docker 101](docker/docker-101.md)
- [Docker resources](docker/resources.md)
- [Unit tests](Unit-tests.md)
### Docker test images
Test Dockerfiles are located under `docker/tests/<distribution>/Dockerfile`,
and can be used to build Docker images to run Shaarli test suites under common
Linux environments.
Dockerfiles are provided for the following environments:
- `alpine36` - [Alpine 3.6](https://www.alpinelinux.org/downloads/)
- `debian8` - [Debian 8 Jessie](https://www.debian.org/DebianJessie) (oldstable)
- `debian9` - [Debian 9 Stretch](https://wiki.debian.org/DebianStretch) (stable)
- `ubuntu16` - [Ubuntu 16.04 Xenial Xerus](http://releases.ubuntu.com/16.04/) (LTS)
What's behind the curtains:
- each image provides:
- a base Linux OS
- Shaarli PHP dependencies (OS packages)
- test PHP dependencies (OS packages)
- Composer
- the local workspace is mapped to the container's `/shaarli/` directory,
- the files are rsync'd to so tests are run using a standard Linux user account
(running tests as `root` would bypass permission checks and may hide issues)
- the tests are run inside the container.
### Building test images
```bash
# build the Debian 9 Docker image
$ cd /path/to/shaarli
$ cd docker/test/debian9
$ docker build -t shaarli-test:debian9 .
```
### Running tests
```bash
$ cd /path/to/shaarli
# install/update 3rd-party test dependencies
$ composer install --prefer-dist
# run tests using the freshly built image
$ docker run -v $PWD:/shaarli shaarli-test:debian9 docker_test
# run the full test campaign
$ docker run -v $PWD:/shaarli shaarli-test:debian9 docker_all_tests
```

155
doc/md/Unit-tests.md Normal file
View file

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

197
doc/md/Upgrade-and-migration.md Normal file
View file

@ -0,0 +1,197 @@
## Preparation
### Note your current version
If anything goes wrong, it's important for us to know which version you're upgrading from.
The current version is present in the `version.php` file.
### Backup your data
Shaarli stores all user data under the `data` directory:
- `data/config.php` - main configuration file
- `data/datastore.php` - bookmarked links
- `data/ipbans.php` - banned IP addresses
- `data/updates.txt` - contains all automatic update to the configuration and datastore files already run
See [Shaarli configuration](Shaarli configuration) for more information about Shaarli resources.
It is recommended to backup this repository _before_ starting updating/upgrading Shaarli:
- users with SSH access: copy or archive the directory to a temporary location
- users with FTP access: download a local copy of your Shaarli installation using your favourite client
### Migrating data from a previous installation
As all user data is kept under `data`, this is the only directory you need to worry about when migrating to a new installation, which corresponds to the following steps:
- backup the `data` directory
- install or update Shaarli:
- fresh installation - see [Download and installation](Download and installation)
- update - see the following sections
- check or restore the `data` directory
## Recommended : Upgrading from release archives
All tagged revisions can be downloaded as tarballs or ZIP archives from the [releases](https://github.com/shaarli/Shaarli/releases) page.
We recommend that you use the latest release tarball with the `-full` suffix. It contains the dependencies, please read [Download and installation](Download and installation) for `git` complete instructions.
Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the content of the `data` directory!
After upgrading, access your fresh Shaarli installation from a web browser; the configuration and data store will then be automatically updated, and new settings added to `data/config.json.php` (see [Shaarli configuration](Shaarli configuration) for more details).
## Upgrading with Git
### Updating a community Shaarli
If you have installed Shaarli from the [community Git repository](Download#clone-with-git-recommended), simply [pull new changes](https://www.git-scm.com/docs/git-pull) from your local clone:
```bash
$ cd /path/to/shaarli
$ git pull
From github.com:shaarli/Shaarli
* branch master -> FETCH_HEAD
Updating ebd67c6..521f0e6
Fast-forward
application/Url.php | 1 +
shaarli_version.php | 2 +-
tests/Url/UrlTest.php | 1 +
3 files changed, 3 insertions(+), 1 deletion(-)
```
Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/):
```bash
$ composer install --no-dev
Loading composer repositories with package information
Updating dependencies
- Installing shaarli/netscape-bookmark-parser (v1.0.1)
Downloading: 100%
```
### Migrating and upgrading from Sebsauvage's repository
If you have installed Shaarli from [Sebsauvage's original Git repository](https://github.com/sebsauvage/Shaarli), you can use [Git remotes](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) to update your working copy.
The following guide assumes that:
- you have a basic knowledge of Git [branching](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) and [remote repositories](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes)
- the default remote is named `origin` and points to Sebsauvage's repository
- the current branch is `master`
- if you have personal branches containing customizations, you will need to [rebase them](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) after the upgrade; beware though, a lot of changes have been made since the community fork has been created, so things are very likely to break!
- the working copy is clean:
- no versioned file has been locally modified
- no untracked files are present
#### Step 0: show repository information
```bash
$ cd /path/to/shaarli
$ git remote -v
origin https://github.com/sebsauvage/Shaarli (fetch)
origin https://github.com/sebsauvage/Shaarli (push)
$ git branch -vv
* master 029f75f [origin/master] Update README.md
$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working directory clean
```
#### Step 1: update Git remotes
```
$ git remote rename origin sebsauvage
$ git remote -v
sebsauvage https://github.com/sebsauvage/Shaarli (fetch)
sebsauvage https://github.com/sebsauvage/Shaarli (push)
$ git remote add origin https://github.com/shaarli/Shaarli
$ git fetch origin
remote: Counting objects: 3015, done.
remote: Compressing objects: 100% (19/19), done.
remote: Total 3015 (delta 446), reused 457 (delta 446), pack-reused 2550
Receiving objects: 100% (3015/3015), 2.59 MiB | 918.00 KiB/s, done.
Resolving deltas: 100% (1899/1899), completed with 48 local objects.
From https://github.com/shaarli/Shaarli
* [new branch] master -> origin/master
* [new branch] stable -> origin/stable
[...]
* [new tag] v0.6.4 -> v0.6.4
* [new tag] v0.7.0 -> v0.7.0
```
#### Step 2: use the stable community branch
```bash
$ git checkout origin/stable -b stable
Branch stable set up to track remote branch stable from origin.
Switched to a new branch 'stable'
$ git branch -vv
master 029f75f [sebsauvage/master] Update README.md
* stable 890afc3 [origin/stable] Merge pull request #509 from ArthurHoaro/v0.6.5
```
Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/):
```bash
$ composer install --no-dev
Loading composer repositories with package information
Updating dependencies
- Installing shaarli/netscape-bookmark-parser (v1.0.1)
Downloading: 100%
```
Optionally, you can delete information related to the legacy version:
```bash
$ git branch -D master
Deleted branch master (was 029f75f).
$ git remote remove sebsauvage
$ git remote -v
origin https://github.com/shaarli/Shaarli (fetch)
origin https://github.com/shaarli/Shaarli (push)
$ git gc
Counting objects: 3317, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (1237/1237), done.
Writing objects: 100% (3317/3317), done.
Total 3317 (delta 2050), reused 3301 (delta 2034)to
```
#### Step 3: configuration
After migrating, access your fresh Shaarli installation from a web browser; the configuration will then be automatically updated, and new settings added to `data/config.php` (see [Shaarli configuration](Shaarli configuration) for more details).
## Troubleshooting
If the solutions provided here don't work, please open an issue specifying which version you're upgrading from and to.
### You must specify an integer as a key
In `v0.8.1` we changed how link keys are handled (from timestamps to incremental integers).
Take a look at `data/updates.txt` content.
#### `updates.txt` contains `updateMethodDatastoreIds`
Try to delete it and refresh your page while being logged in.
#### `updates.txt` doesn't exist or doesn't contain `updateMethodDatastoreIds`
1. Create `data/updates.txt` if it doesn't exist
2. Paste this string in the update file `;updateMethodRenameDashTags;`
3. Login to Shaarli
4. Delete the update file
5. Refresh

33
doc/md/Various-hacks.md Normal file
View file

@ -0,0 +1,33 @@
### Decode datastore content
To display the array representing the data saved in `data/datastore.php`, use the following snippet:
```php
$data = "tZNdb9MwFIb... <Commented content inside datastore.php>";
$out = unserialize(gzinflate(base64_decode($data)));
echo "<pre>"; // Pretty printing is love, pretty printing is life
print_r($out);
echo "</pre>";
exit;
```
This will output the internal representation of the datastore, "unobfuscated" (if this can really be considered obfuscation).
Alternatively, you can transform to JSON format (and pretty-print if you have `jq` installed):
```
php -r 'print(json_encode(unserialize(gzinflate(base64_decode(preg_replace("!.*/\* (.+) \*/.*!", "$1", file_get_contents("data/datastore.php")))))));' | jq .
```
### Changing the timestamp for a shaare
- Look for `<input type="hidden" name="lf_linkdate" value="{$link.linkdate}">` in `tpl/editlink.tpl` (line 14)
- Replace `type="hidden"` with `type="text"` from this line
- A new date/time field becomes available in the edit/new link dialog.
- You can set the timestamp manually by entering it in the format `YYYMMDD_HHMMS`.
### See also
- [Add a new custom field to shaares (example patch)](https://gist.github.com/nodiscc/8b0194921f059d7b9ad89a581ecd482c)
- [Download CSS styles for shaarlis listed in an opml file](https://gist.github.com/nodiscc/dede231c92cab22c3ad2cc24d5035012)
- [Copy an existing Shaarli installation over SSH, and serve it locally](https://gist.github.com/nodiscc/ed161c66e5b028b5299b0a3733d01c77)
- [Create multiple Shaarli instances, generate an HTML index of them](https://gist.github.com/nodiscc/52e711cda3bc47717c16065231cf6b20)

75
doc/md/Versioning-and-Branches.md Normal file
View file

@ -0,0 +1,75 @@
**WORK IN PROGRESS**
It's important to understand how Shaarli branches work, especially if you're maintaining a 3rd party tools for Shaarli (theme, plugin, etc.), to be sure stay compatible.
## `master` branch
The `master` branch is the development branch. Any new change MUST go through this branch using Pull Requests.
Remarks:
- This branch shouldn't be used for production as it isn't necessary stable.
- 3rd party aren't required to be compatible with the latest changes.
- Official plugins, themes and libraries (contained within Shaarli organization repos) must be compatible with the master branch.
- The version in this branch is always `dev`.
## `v0.x` branch
This `v0.x` branch, points to the latest `v0.x.y` release.
Explanation:
When a new version is released, it might contains a major bug which isn't detected right away. For example, a new PHP version is released, containing backward compatibility issue which doesn't work with Shaarli.
In this case, the issue is fixed in the `master` branch, and the fix is backported the to the `v0.x` branch. Then a new release is made from the `v0.x` branch.
This workflow allow us to fix any major bug detected, without having to release bleeding edge feature too soon.
## `latest` branch
This branch point the latest release. It recommended to use it to get the latest tested changes.
## `stable` branch
The `stable` branch doesn't contain any major bug, and is one major digit version behind the latest release.
For example, the current latest release is `v0.8.3`, the stable branch is an alias to the latest `v0.7.x` release. When the `v0.9.0` version will be released, the stable will move to the latest `v0.8.x` release.
Remarks:
- Shaarli release pace isn't fast, and the stable branch might be a few months behind the latest release.
## Releases
Releases are always made from the latest `v0.x` branch.
Note that for every release, we manually generate a tarball which contains all Shaarli dependencies, making Shaarli's installation only one step.
## Advices on 3rd party git repos workflow
### Versioning
Any time a new Shaarli release is published, you should publish a new release of your repo if the changes affected you since the latest release (take a look at the [changelog](https://github.com/shaarli/Shaarli/releases) (*Draft* means not released yet) and the commit log (like [`tpl` folder](https://github.com/shaarli/Shaarli/commits/master/tpl/default) for themes)). You can either:
- use the Shaarli version number, with your repo version. For example, if Shaarli `v0.8.3` is released, publish a `v0.8.3-1` release, where `v0.8.3` states Shaarli compatibility and `-1` is your own version digit for the current Shaarli version.
- use your own versioning scheme, and state Shaarli compatibility in the release description.
Using this, any user will be able to pick the release matching his own Shaarli version.
### Major bugfix backport releases
To be able to support backported fixes, it recommended to use our workflow:
```bash
# In master, fix the major bug
git commit -m "Katastrophe"
git push origin master
# Get your commit hash
git log --format="%H" -n 1
# Create a new branch from your latest release, let's say v0.8.2-1 (the tag name)
git checkout -b katastrophe v0.8.2-1
# Backport the fix commit to your brand new branch
git cherry-pick <fix commit hash>
git push origin katastrophe
# Then you just have to make a new release from the `katastrophe` branch tagged `v0.8.3-1`
```

140
doc/md/docker/docker-101.md Normal file
View file

@ -0,0 +1,140 @@
## Basics
Install [Docker](https://www.docker.com/), by following the instructions relevant
to your OS / distribution, and start the service.
### Search an image on [DockerHub](https://hub.docker.com/)
```bash
$ docker search debian
NAME DESCRIPTION STARS OFFICIAL AUTOMATED
ubuntu Ubuntu is a Debian-based Linux operating s... 2065 [OK]
debian Debian is a Linux distribution that's comp... 603 [OK]
google/debian 47 [OK]
```
### Show available tags for a repository
```bash
$ curl https://index.docker.io/v1/repositories/debian/tags | python -m json.tool
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 1283 0 1283 0 0 433 0 --:--:-- 0:00:02 --:--:-- 433
```
Sample output:
```json
[
{
"layer": "85a02782",
"name": "stretch"
},
{
"layer": "59abecbc",
"name": "testing"
},
{
"layer": "bf0fd686",
"name": "unstable"
},
{
"layer": "60c52dbe",
"name": "wheezy"
},
{
"layer": "c5b806fe",
"name": "wheezy-backports"
}
]
```
### Pull an image from DockerHub
```bash
$ docker pull repository[:tag]
$ docker pull debian:wheezy
wheezy: Pulling from debian
4c8cbfd2973e: Pull complete
60c52dbe9d91: Pull complete
Digest: sha256:c584131da2ac1948aa3e66468a4424b6aea2f33acba7cec0b631bdb56254c4fe
Status: Downloaded newer image for debian:wheezy
```
Docker re-uses layers already downloaded. In other words if you have images based on Alpine or some Ubuntu version for example, those can share disk space.
### Start a container
A container is an instance created from an image, that can be run and that keeps running until its main process exits. Or until the user stops the container.
The simplest way to start a container from image is ``docker run``. It also pulls the image for you if it is not locally available. For more advanced use, refer to ``docker create``.
Stopped containers are not destroyed, unless you specify ``--rm``. To view all created, running and stopped containers, enter:
```bash
$ docker ps -a
```
Some containers may be designed or configured to be restarted, others are not. Also remember both network ports and volumes of a container are created on start, and not editable later.
### Access a running container
A running container is accessible using ``docker exec``, or ``docker copy``. You can use ``exec`` to start a root shell in the Shaarli container:
```bash
$ docker exec -ti <container-name-or-id> bash
```
Note the names and ID's of containers are listed in ``docker ps``. You can even type only one or two letters of the ID, given they are unique.
Access can also be through one or more network ports, or disk volumes. Both are specified on and fixed on ``docker create`` or ``run``.
You can view the console output of the main container process too:
```bash
$ docker logs -f <container-name-or-id>
```
### Docker disk use
Trying out different images can fill some gigabytes of disk quickly. Besides images, the docker volumes usually take up most disk space.
If you care only about trying out docker and not about what is running or saved, the following commands should help you out quickly if you run low on disk space:
```bash
$ docker rmi -f $(docker images -aq) # remove or mark all images for disposal
$ docker volume rm $(docker volume ls -q) # remove all volumes
```
### Systemd config
Systemd is the process manager of choice on Debian-based distributions. Once you have a ``docker`` service installed, you can use the following steps to set up Shaarli to run on system start.
```bash
systemctl enable /etc/systemd/system/docker.shaarli.service
systemctl start docker.shaarli
systemctl status docker.*
journalctl -f # inspect system log if needed
```
You will need sudo or a root terminal to perform some or all of the steps above. Here are the contents for the service file:
```
[Unit]
Description=Shaarli Bookmark Manager Container
After=docker.service
Requires=docker.service
[Service]
Restart=always
# Put any environment you want in an included file, like $host- or $domainname in this example
EnvironmentFile=/etc/sysconfig/box-environment
# It's just an example..
ExecStart=/usr/bin/docker run \
-p 28010:80 \
--name ${hostname}-shaarli \
--hostname shaarli.${domainname} \
-v /srv/docker-volumes-local/shaarli-data:/var/www/shaarli/data:rw \
-v /etc/localtime:/etc/localtime:ro \
shaarli/shaarli:latest
ExecStop=/usr/bin/docker rm -f ${hostname}-shaarli
[Install]
WantedBy=multi-user.target
```

19
doc/md/docker/resources.md Normal file
View file

@ -0,0 +1,19 @@
### Docker
- [Interactive Docker training portal](https://www.katacoda.com/courses/docker/) on [Katakoda](https://www.katacoda.com/)
- [Where are Docker images stored?](http://blog.thoward37.me/articles/where-are-docker-images-stored/)
- [Dockerfile reference](https://docs.docker.com/reference/builder/)
- [Dockerfile best practices](https://docs.docker.com/articles/dockerfile_best-practices/)
- [Volumes](https://docs.docker.com/userguide/dockervolumes/)
### DockerHub
- [Repositories](https://docs.docker.com/userguide/dockerrepos/)
- [Teams and organizations](https://docs.docker.com/docker-hub/orgs/)
- [GitHub automated build](https://docs.docker.com/docker-hub/github/)
### Service management
- [Using supervisord](https://docs.docker.com/articles/using_supervisord/)
- [Nginx in the foreground](http://nginx.org/en/docs/ngx_core_module.html#daemon)
- [supervisord](http://supervisord.org/)

6
doc/md/docker/reverse-proxy-configuration.md Normal file
View file

@ -0,0 +1,6 @@
TODO, see https://github.com/shaarli/Shaarli/issues/888
## HAProxy
## Nginx

71
doc/md/docker/shaarli-images.md Normal file
View file

@ -0,0 +1,71 @@
## Get and run a Shaarli image
### DockerHub repository
The images can be found in the [`shaarli/shaarli`](https://hub.docker.com/r/shaarli/shaarli/)
repository.
### Available image tags
- `latest`: master branch (tarball release)
- `stable`: stable branch (tarball release)
All images rely on:
- [Debian 8 Jessie](https://hub.docker.com/_/debian/)
- [PHP5-FPM](http://php-fpm.org/)
- [Nginx](http://nginx.org/)
### Download from DockerHub
```bash
$ docker pull shaarli/shaarli
latest: Pulling from shaarli/shaarli
32716d9fcddb: Pull complete
84899d045435: Pull complete
4b6ad7444763: Pull complete
e0345ef7a3e0: Pull complete
5c1dd344094f: Pull complete
6422305a200b: Pull complete
7d63f861dbef: Pull complete
3eb97210645c: Pull complete
869319d746ff: Already exists
869319d746ff: Pulling fs layer
902b87aaaec9: Already exists
Digest: sha256:f836b4627b958b3f83f59c332f22f02fcd495ace3056f2be2c4912bd8704cc98
Status: Downloaded newer image for shaarli/shaarli:latest
```
### Create and start a new container from the image
```bash
# map the host's :8000 port to the container's :80 port
$ docker create -p 8000:80 shaarli/shaarli
d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101
# launch the container in the background
$ docker start d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101
d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101
# list active containers
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
d40b7af693d6 shaarli/shaarli /usr/bin/supervisor 15 seconds ago Up 4 seconds 0.0.0.0:8000->80/tcp backstabbing_galileo
```
### Stop and destroy a container
```bash
$ docker stop backstabbing_galileo # those docker guys are really rude to physicists!
backstabbing_galileo
# check the container is stopped
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
# list ALL containers
$ docker ps -a
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
d40b7af693d6 shaarli/shaarli /usr/bin/supervisor 5 minutes ago Exited (0) 48 seconds ago backstabbing_galileo
# destroy the container
$ docker rm backstabbing_galileo # let's put an end to these barbarian practices
backstabbing_galileo
$ docker ps -a
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
```

BIN
doc/md/images/bookmarklet.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 52 KiB

BIN
doc/md/images/doc-logo.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 19 KiB

BIN
doc/md/images/doc-logo.svg Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 68 KiB

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

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 757 B

BIN
doc/md/images/rss-filter-1.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 18 KiB

BIN
doc/md/images/rss-filter-2.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 15 KiB

126
doc/md/index.md Normal file
View file

@ -0,0 +1,126 @@
# [Shaarli](https://github.com/shaarli/Shaarli/) documentation
Here you can find some info on how to use, configure, tweak and solve problems with your Shaarli.
For general info, read the [README](https://github.com/shaarli/Shaarli/blob/master/README.md).
If you have any questions or ideas, please join the [chat](https://gitter.im/shaarli/Shaarli) (also reachable via [IRC](https://irc.gitter.im/)), post them in our [general discussion](https://github.com/shaarli/Shaarli/issues/308) or read the current [issues](https://github.com/shaarli/Shaarli/issues).
If you've found a bug, please create a [new issue](https://github.com/shaarli/Shaarli/issues/new).
If you would like a feature added to Shaarli, check the issues labeled [`feature`](https://github.com/shaarli/Shaarli/labels/feature), [`enhancement`](https://github.com/shaarli/Shaarli/labels/enhancement), and [`plugin`](https://github.com/shaarli/Shaarli/labels/plugin).
_Note: This documentation is available online at https://shaarli.readthedocs.io/, and locally in the `doc/html/` directory of your Shaarli installation._
[![Join the chat at https://gitter.im/shaarli/Shaarli](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/shaarli/Shaarli)
[![Bountysource](https://www.bountysource.com/badge/team?team_id=19583&style=bounties_received)](https://www.bountysource.com/teams/shaarli/issues)
[![Docker repository](https://img.shields.io/docker/pulls/shaarli/shaarli.svg)](https://hub.docker.com/r/shaarli/shaarli/)
### Demo
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.
Login: `demo`; Password: `demo`
Docker users can start a personal instance from an [autobuild image](https://hub.docker.com/r/shaarli/shaarli/). For example to start a temporary Shaarli at ``localhost:8000``, and keep session data (config, storage):
```
MY_SHAARLI_VOLUME=$(cd /path/to/shaarli/data/ && pwd -P)
docker run -ti --rm \
-p 8000:80 \
-v $MY_SHAARLI_VOLUME:/var/www/shaarli/data \
shaarli/shaarli
```
A brief guide on getting starting using docker is given in [Docker 101](docker/docker-101).
To learn more about user data and how to keep it across versions, please see [Upgrade and Migration](Upgrade-and-migration) documentation.
## Features
### Interface
- minimalist design (simple is beautiful)
- FAST
- ATOM and RSS feeds
- views:
- paginated link list
- tag cloud
- picture wall: image and video thumbnails
- daily: newspaper-like daily digest
- daily RSS feed
- permalinks for easy reference
- links can be public or private
- extensible through [plugins](https://shaarli.readthedocs.io/en/master/Plugins/#plugin-usage)
### Tag, view and search your links!
- add a custom title and description to archived links
- add tags to classify and search links
- features tag autocompletion, renaming, merging and deletion
- full-text and tag search
### Easy setup
- dead-simple installation: drop the files, open the page
- links are stored in a file
- compact storage
- no database required
- easy backup: simply copy the datastore file
- import and export links as Netscape bookmarks
### Accessibility
- Firefox bookmarlet to share links in one click
- support for mobile browsers
- works with Javascript disabled
- easy page customization through HTML/CSS/RainTPL
### Security
- bruteforce-proof login form
- protected against [XSRF](http://en.wikipedia.org/wiki/Cross-site_request_forgery)
and session cookie hijacking
### Goodies
- thumbnail generation for images and video services:
dailymotion, flickr, imageshack, imgur, vimeo, xkcd, youtube...
- lazy-loading with [bLazy](http://dinbror.dk/blazy/)
- [PubSubHubbub](https://code.google.com/p/pubsubhubbub/) protocol support
- URL cleanup: automatic removal of `?utm_source=...`, `fb=...`
- discreet pop-up notification when a new release is available
### REST API
Easily extensible by any client using the REST API exposed by Shaarli.
See the [API documentation](http://shaarli.github.io/api-documentation/).
### Other usages
Though Shaarli is primarily a bookmarking application, it can serve other purposes
(see [Features](Features)):
- micro-blogging
- pastebin
- online notepad
- snippet archive
## About
### Shaarli community fork
This friendly fork is maintained by the Shaarli community at https://github.com/shaarli/Shaarli
This is a community fork of the original [Shaarli](https://github.com/sebsauvage/Shaarli/) project by [Sébastien Sauvage](http://sebsauvage.net/).
The original project is currently unmaintained, and the developer [has informed us](https://github.com/sebsauvage/Shaarli/issues/191)
that he would have no time to work on Shaarli in the near future.
The Shaarli community has carried on the work to provide
[many patches](https://github.com/shaarli/Shaarli/compare/sebsauvage:master...master)
for [bug fixes and enhancements](https://github.com/shaarli/Shaarli/issues?q=is%3Aclosed+)
in this repository, and will keep maintaining the project for the foreseeable future, while keeping Shaarli simple and efficient.
### Contributing
If you'd like to help, please:
- have a look at the open [issues](https://github.com/shaarli/Shaarli/issues)
and [pull requests](https://github.com/shaarli/Shaarli/pulls)
- feel free to report bugs (feedback is much appreciated)
- suggest new features and improvements to both code and [documentation](https://github.com/shaarli/Shaarli/wiki)
- propose solutions to existing problems
- submit pull requests :-)
### License
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.

Some files were not shown because too many files have changed in this diff Show more