The Arsse is a news aggregator server, written in PHP, which implements multiple synchronization protocols. Unlike most other aggregator servers, The Arsse does not include a Web front-end (though one is planned as a separate project), and it relies on existing protocols to maximize compatibility with existing clients.
Information on how to install and use the software can be found in the manual, which is available online as well as with every copy of the software. This readme file instead focuses on how to set up a programming environment to modify the source code.
Composer is required to manage PHP dependencies. After cloning the repository or downloading a source code tarball, running
composer install will download all the required dependencies, and will advise if any PHP extensions need to be installed. If not installing as a programming environment, running
composer install --no-dev is recommended.
The code which runs The Arsse, contained in
/arsse.php, is only a short stub: the application itself is composed of the classes found under
/lib/, with the main ones being:
||The command-line interface, including its documentation|
||High-level database interface|
||Low-level database abstraction layer|
||General protocol handler for CORS, HTTP auth, etc.|
||Singleton glueing the parts together|
/lib/Database.php file is the heart of the application, performing queries on behalf of protocol implementations or the command-line interface.
Also necessary to the functioning of the application is the
/vendor/ directory, which contains PHP libraries which The Arsse depends upon. These are managed by Composer.
/sql/ directories contain human-language files and database schemata, both of which are occasionally used by the application in the course of execution. The
/www/ directory serves as a document root for a few static files to be made available to users by a Web server.
/dist/ directory, on the other hand, contains samples of configuration for Web servers and init systems. These are not used by The Arsse itself, but are merely distributed with it for reference.
In addition to the manual the files
/README.md (this file),
/AUTHORS also document various things about the software, rather than the software itself.
/tests/ directory contains everything related to automated testing. It is itself organized as follows:
||The test cases themselves, organized in roughly the same structure as the code|
||(optional) Generated code coverage reports|
||Sample documents used in some tests, to be returned by the PHP’s basic HTTP server|
||Supporting classes which do not contain test cases|
||Bootstrap script, equivalent to
||PHPUnit configuration file|
||Simple driver for the PHP HTTP server used during testing|
PHPUnit’s configuration can be customized by copying its configuration file to
/tests/phpunit.xml and modifying the copy accordingly.
/vendor-bin/ directory houses the files needed for the tools used in The Arsse’s programming environment. These are managed by the Composer “bin” plugin and are not used by The Arsse itself. The following files are also related to various programming tools:
||Git settings for handling files|
||Git file exclusion patterns|
||Configuration for php-cs-fixer|
||Cache for php-cs-fixer|
||Configuration for Composer|
||Version synchronization data for Composer|
||Task definitions for Robo|
||Simple wrapper for executing Robo on POSIX systems|
||Simple wrapper for executing Robo on Windows|
We use a tool called Robo to simplify the execution of common tasks. It is installed with The Arsse’s other dependencies, and its configured tasks can be listed by executing
./robo without arguments.
The Arsse has an extensive PHPUnit test suite; tests can be run by executing
./robo test, which can be supplemented with any arguments understoof by PHPUnit. For example, to test only the Tiny Tiny RSS protocol, one could run
./robo test --testsuite TTRSS.
There is also a
test:quick Robo task which excludes slower tests, and a
test:full task which includes redundant tests in addition to the standard test suite
The Arsse’s user manual, made using Daux, can be compiled by running
./robo manual, which will output files to
/manual/. It is also possible to serve the manual from a test HTTP server on port 8085 by running
The manual employs a custom theme derived from the standard Daux theme. If the standard Daux theme receives improvements, the custom theme can be rebuilt by running
The Robo task
manual:css will recompile the theme’s stylesheet without rebuilding the entire theme.
Producing a release package is done by running
./robo package. This performs the following operations:
Due to the first step, Git is required to package a release.