Architecture overview

Oliver Klee edited this page May 30, 2017 · 3 revisions

This is the blueprint for the first steps to get phpList 4 up to speed and for creating a new REST API (AKA the REST API V2).


Get the phpList REST API V2 running as quickly as possible while not painting the project in a corner. Refactor/rewrite the parts of the phpList 4 core that are needed for the REST API.


  • The project should follow best practices for open-source projects to facilitate contributing.
  • The code should use established standards and use existing libraries as much as possible (and where it makes sense) to avoid reinventing the wheel and the not-invented-here syndrome.
  • The code should be checked via automatic tools as much as possible to ensure high code quality and to reduce the time needed to manual code reviews.
  • Updating the installation of phpList 4 should require only one or two terminal commands maximum (including the changes to the database).
  • An update should be possible with near-zero downtime.
  • The REST API V2 and phpList 4 will be mostly new code. Some time in the future, it should fully replace phpList 3 and the REST API plugin v1.
  • It should be possible to automatically deploy the initial installation and any updates to an installation using an established deployment solution like TYPO3 Surf (PHP) or Capistrano (Ruby), making updates to multiple (even hundreds of) installations extremely efficient.
  • It should also be possible to create and update an installation via SFTP and the web frontend (i.e., without having shell access to the server and without and existing installation of Composer).
  • Have a proper separation of concerns with domain models, repositories, services, controllers etc.
  • While writing code, we will keep an eye on performance so that we won't have code that has data structures or algorithms that are know to be slow or that will block us from improving performance.

PHP language level and license

  • PHP ~7.x (currently 7.0 and 7.1)
  • AGPL (except for the base distribution, which is intended to be modified for each individual installation, and which will contain practically no code, which will be GPL)

Repositories and composer packages

Short-term, the legacy phpList 3 should still handle the web interface, while the new code should cover the REST API and not call any of the phpList 3 code.

In general, Composer will be used to manage all dependencies, including other phpList modules. (Note: "plugins" for phpList 4 will also be called "modules".)

phpList 4 can be installed next to phpList 3, and both are intended to happily share the same DB.


This Compose package will be the basis of a new site. It will pull in the phplist/phplist4-core module (the core) and by default also the phplist/rest-api module (the new REST API package) and (in the future) the phplist/web-frontend module (all via Composer). Both dependencies are optional.

This package is intended to be cloned and then modified. It is not intended to be updated via Composer after the initial install (although updating the dependencies via composer update is fine).

This (i.e., the downloaded package) is also the place where configuration files will be stored (or symlinked to).


This module is the phpList 4 core. It will have the following responsibilities:

  • provide access to the DB via Doctrine ORM models and repositories (and the Doctrine QueryBuilder or DQL for performance-critical parts where Doctrine ORM is too slow)
  • routing (which the web frontend and REST API will use)
  • authentication (which the web frontend and REST API will use)
  • logging
  • a script for tasks to be called from the command line (or a cron job)
  • tasks to create and update the DB schema

The existing code in this repository will be replaced by new code bit by bit.

This module should not be modified locally. It should be updated via Composer.


This module will be the new REST API. It will use functionality from phplist/phplist4-core. It will not contain any SQL queries, but use functionality from the new core for DB access.

This module is optional, i.e. it will be possible to run phpList 4 without the REST API.

phplist/web-frontend (later)

This module can be created later. It will contain the web frontend for phpList 4. It will not contain any SQL queries, but use functionality from the new core for DB access.

This module is optional, i.e. it will be possible to run phpList 4 without a web frontend.

phplist/composer-install (later)

This will be a non-phpList-specific tool that downloads and installs Composer and then creates a site using a Composer package (in this case from phplist/base-distribution), asks for the database credentials etc. It can be installed via SFTP and then be accessed via a web frontend.

Maybe we won't need this and can continue shipping the new phpList as a ZIP package (also including the dependencies) for those users who only have SFTP, but no shell access.

Repository standards

All related repositories will

  • be available as Composer packages on Packagist (including a badge)
  • will have a Travis CI task (including a badge)
  • have the code checked with the PHP linter, PHPCS, PHPMD, and unit tests (if applicable)

For the existing repository phpList (phpList 4), the CI checks will only cover the new code, not the existing code.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.