README

About phpList

phpList is an open source newsletter manager. This project is a rewrite of the original phpList.

About this package

This is the core module of phpList 4, currently in alpha stage. It provides the following functionality:

Database access via Doctrine models and repositories (and raw SQL for performance-critical parts)
Routing (which the web frontend and REST API use)
Authentication (which the web frontend and REST API use)
Logging (including Graylog integration for centralized logging)
Command line interface for maintenance tasks
Database schema creation and updates
Asynchronous email sending using Symfony Messenger

Please note that this module does not provide a web frontend or a REST API. There are separate modules for these purposes:

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

Requirements

PHP 8.1 or higher
Symfony 6.4 components
Doctrine ORM 3.3

Installation

Since this package is only a service required to run a full installation of phpList 4, the recommended way of installing this package is to run composer install from within the phpList base distribution which requires this package. phpList/base-distribution contains detailed installation instructions in its README.

Contributing to this package

Contributions to phpList repositories are highly welcomed! To get started please take a look at the contribution guide. It contains everything you would need to make your first contribution including how to run local style checks and run tests.

Code of Conduct

This project adheres to a Contributor Code of Conduct. By participating in this project and its community, you are expected to uphold this code.

Documentation

Class structure overview
Domain model diagram and description of the domain entities
Mailer transports - configuring Gmail, Amazon SES, Mailchimp, and SendGrid
Asynchronous email sending - queuing email delivery with Symfony Messenger
Graylog integration - centralized log management
Elasticsearch-backed search for big tables - dual-write to the database and Elasticsearch, reading from Elasticsearch only
Generating class API docs - regenerating the phpDocumentor output

Running the web server

The phpList application is configured so that the built-in PHP web server can run in development and testing mode, while Apache can run in production mode.

Please first set the database credentials in .env (created from .env.dist on composer install/composer update).

Development

To run the application in development mode using PHP's built-in server, use this command:

bin/console server:run -d public/

The server will then listen on http://127.0.0.1:8000 (or, if port 8000 is already in use, on the next free port after 8000).

You can stop the server with CTRL + C.

Testing

Create test db with name phplist in your mysql DB or uncomment sqlite part in config_test.yml file to use in memory DB for functional tests. To run the server in testing mode (which normally will only be needed for the automated tests, provide the --env option:

bin/console server:run -d public/ --env=test

Production

For documentation on running the application in production mode using Apache, please see the phpList base distribution README.

Changing the database schema

Any changes to the database schema must always be done both in phpList 3 and later versions so that both versions always have the same schema.

For changing the database schema, please edit resources/Database/Schema.sql and adapt the corresponding domain model classes and repository classes accordingly.

Developing phpList modules (plugins)

In phpList, plugins are called modules. They are Composer packages which have the type phplist-module.

Bundle and route configuration

If your module provides any Symfony bundles, the bundle class names need to be listed in the extra section of the module's composer.json like this:

{
  "extra": {
    "phplist/core": {
      "bundles": [
        "Symfony\\Bundle\\FrameworkBundle\\FrameworkBundle",
        "PhpList\\Core\\EmptyStartPageBundle\\PhpListEmptyStartPageBundle"
      ]
    }
  }
}

Please note that the key of the section with extra needs to always be phplist/core, not the name of your module package. Please have a look at the composer.json in the rest-api module for an example.

Similarly, if your module provides any routes, those also need to be listed in the extra section of the module's composer.json like this:

{
  "extra": {
    "phplist/core": {
      "routes": {
        "homepage": {
          "resource": "@PhpListEmptyStartPageBundle/Controller/",
          "type": "annotation"
        }
      }
    }
  }
}

You can also provide system configuration for your module:

{
  "extra": {
    "phplist/core": {
      "configuration": {
        "framework": {
          "templating": {
            "engines": [
              "twig"
            ]
          }
        }
      }
    }
  } 
}

It is recommended to define the routes using annotations in the controller classes so that the route configuration in the composer.json is minimal.

Accessing the database

For accessing the phpList database tables from a module, please use the Doctrine model and repository classes stored in src/Domain/ in the phplist/core package (this package).

For accessing a repository, please have it injected via dependency injection. Please do not get the repository directly from the entity manager as this would skip dependency injection for that repository, causing those methods to break that rely on other services having been injected.

Currently, only a few database tables are mapped as models/repositories. If you need a mode or a repository method that still is missing, please submit a pull request or file an issue.

Accessing the phpList data from third-party applications

To access the phpList data from a third-party application (i.e., not from a phpList module), please use the REST API.

Translations

To extract translation strings from the source into an XLIFF catalog:

php bin/console translation:extract --force en --format=xlf
php bin/console messenger:setup-transports
php bin/console messenger:consume async_email --limit=1
php bin/console phplist:search:init-indices

phplist / phplist4-core

Package info

Security

Statistics