PHPackages                             phplist/base-distribution - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Mail &amp; Notifications](/categories/mail)
4. /
5. phplist/base-distribution

ActiveProject[Mail &amp; Notifications](/categories/mail)

phplist/base-distribution
=========================

A distribution of phpList, the world's most popular open source newsletter manager

v5.0.0-alpha8(8mo ago)14498↓100%9[1 issues](https://github.com/phpList/base-distribution/issues)[1 PRs](https://github.com/phpList/base-distribution/pulls)GPL-3.0-or-laterPHPPHP ^8.1CI passing

Since Jan 31Pushed 5d ago6 watchersCompare

[ Source](https://github.com/phpList/base-distribution)[ Packagist](https://packagist.org/packages/phplist/base-distribution)[ Docs](https://www.phplist.com/)[ RSS](/packages/phplist-base-distribution/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (14)Versions (13)Used By (0)

phpList 4 base distribution
===========================

[](#phplist-4-base-distribution)

[![Build Status](https://github.com/phpList/base-distribution/workflows/phpList%20Base%20Dist%20Build/badge.svg)](https://github.com/phpList/base-distribution/actions)[![Latest Stable Version](https://camo.githubusercontent.com/b7f4d3d676a104deb54172df1003c1bd5081eb20914e971e3fb7ae05c6b6d722/68747470733a2f2f706f7365722e707567782e6f72672f7068706c6973742f626173652d646973747269627574696f6e2f762f737461626c652e737667)](https://packagist.org/packages/phpList/base-distribution)[![Total Downloads](https://camo.githubusercontent.com/ec8826eacf639796c2f2a24669df7fb7ca74bbc17207fa90a00f74877fa9847c/68747470733a2f2f706f7365722e707567782e6f72672f7068706c6973742f626173652d646973747269627574696f6e2f646f776e6c6f6164732e737667)](https://packagist.org/packages/phpList/base-distribution)[![Latest Unstable Version](https://camo.githubusercontent.com/f386033a069ae3a95061aaebc3216ff2a160714f5cc938c6deb83d66d3d4669d/68747470733a2f2f706f7365722e707567782e6f72672f7068706c6973742f626173652d646973747269627574696f6e2f762f756e737461626c652e737667)](https://packagist.org/packages/phpList/base-distribution)[![License](https://camo.githubusercontent.com/308e6c4ee2a9ce6ca1fbb57e027a5371ada2e28c3b228f1eb9098ab1190d4bd3/68747470733a2f2f706f7365722e707567782e6f72672f7068706c6973742f626173652d646973747269627574696f6e2f6c6963656e73652e737667)](https://packagist.org/packages/phpList/base-distribution)

About phpList
-------------

[](#about-phplist)

phpList is an open source newsletter manager. This project is a rewrite of the [original phpList](https://github.com/phpList/phplist3).

About this package
------------------

[](#about-this-package)

This module is the basis for a phpList 4 installation. It will pull in the `phplist/core` module (the phpList 4 core) and by default also the `phplist/rest-api` module (the new REST API package). The rest-api dependency is 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).

Installation
------------

[](#installation)

1. Download and install [composer](https://getcomposer.org/download/).
2. Run `composer create-project -s dev --no-dev phplist/base-distribution your-project`(use any name you like for the `your-project` directory).
3. Switch to the `your-project` directory.
4. If you would like to not have the REST API, edit the `composer.json`, remove the corresponding `phplist/rest-api` requirement, and run `composer update`.

Configuring and running phpList on a web server
-----------------------------------------------

[](#configuring-and-running-phplist-on-a-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.

### Production on Apache

[](#production-on-apache)

1. In the Apache virtual host configuration, set the directory `public/` as the document root.
2. Set a random 40-character hex secret and the phpList database credentials in the Apache virtual host configuration. Your Apache 2.4 configuration then could look like this:

```

    ServerName domain.tld
    ServerAlias www.domain.tld

    DocumentRoot /var/www/project/public

        AllowOverride All
        Require all granted

    # uncomment the following lines if you install assets as symlinks
    # or run into problems when compiling LESS/Sass/CoffeeScript assets
    #
    #     Options FollowSymlinks
    #

    SetEnv PHPLIST_SECRET f75365ecb07c725ba05d5361e415a328880360e5
    SetEnv PHPLIST_DATABASE_NAME phplist
    SetEnv PHPLIST_DATABASE_USER phplist
    SetEnv PHPLIST_DATABASE_PASSWORD correctHorseBatteryStaple

    ErrorLog /var/log/apache2/project_error.log
    CustomLog /var/log/apache2/project_access.log combined

```

Then reload or restart Apache to activate the configuration changes.

If you cannot set any environment variables in your Apache configuration, you can also set the database credentials in `config/parameters.yml`. However, this should only be used as a last resort as this reduces security (as an attacker with read access to the files on the web server then could read that file, whereas they then still would not be able to access the environment variables).

Use the following optimized configuration to disable .htaccess support and increase web server performance:

```

    ServerName domain.tld
    ServerAlias www.domain.tld

    DocumentRoot /var/www/project/public

        AllowOverride None
        Order Allow,Deny
        Allow from All

            Options -MultiViews
            RewriteEngine On
            RewriteCond %{REQUEST_FILENAME} !-f
            RewriteRule ^(.*)$ app.php [QSA,L]

    SetEnv PHPLIST_SECRET f75365ecb07c725ba05d5361e415a328880360e5
    SetEnv PHPLIST_DATABASE_NAME phplist
    SetEnv PHPLIST_DATABASE_USER phplist
    SetEnv PHPLIST_DATABASE_PASSWORD correctHorseBatteryStaple

    ErrorLog /var/log/apache2/project_error.log
    CustomLog /var/log/apache2/project_access.log combined

```

### Development

[](#development)

For running the application in development mode using the built-in PHP 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

[](#testing)

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

Useful Composer scripts
-----------------------

[](#useful-composer-scripts)

You can get a list of all installed phpList modules with this command:

```
composer run-script list-modules
```

Creating a .tar.gz package of this distribution
-----------------------------------------------

[](#creating-a-targz-package-of-this-distribution)

These are the steps to create a package for version 4.0.x-dev with the file name `phplist-base-distribution-4.0.x-dev.tar.gz`:

```
composer create-project phplist/base-distribution phplist 4.0.x-dev --prefer-dist --no-dev -s dev
tar -cvzf phplist-base-distribution-4.0.x-dev.tar.gz phplist
```

These steps assume that `tar` and `composer` are installed on your machine, and that `composer` is [in your path](https://getcomposer.org/doc/00-intro.md#globally)(and that it is named `composer`, not `composer.phar`).

Contributing to this package
----------------------------

[](#contributing-to-this-package)

Please read the [contribution guide](.github/CONTRIBUTING.md) on how to contribute and how to run the unit tests and style checks locally.

### Code of Conduct

[](#code-of-conduct)

This project adheres to a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project and its community, you are expected to uphold this code.

Docker deployment
-----------------

[](#docker-deployment)

The project includes a Docker setup to run phpList with Apache and MySQL.

Quick start (development/test):

- Build and start the stack: `docker compose up --build`
- Open

The app container is configured to read database settings from environment variables that match config/parameters.yml defaults. The provided docker-compose.yml sets:

- PHPLIST\_DATABASE\_HOST=db
- PHPLIST\_DATABASE\_PORT=3306
- PHPLIST\_DATABASE\_NAME=phplistdb
- PHPLIST\_DATABASE\_USER=phplist
- PHPLIST\_DATABASE\_PASSWORD=phplist

Notes:

- For production deployments, build and push the image, then run it behind a reverse proxy or load balancer. Example:
    - `docker build -t your-registry/phplist-base:latest .`
    - `docker run -p 8080:80 --env PHPLIST_DATABASE_HOST=... --env PHPLIST_DATABASE_NAME=... --env PHPLIST_DATABASE_USER=... --env PHPLIST_DATABASE_PASSWORD=... your-registry/phplist-base:latest`
- Persist the MySQL data using the db\_data volume defined in docker-compose.yml, or bind mount your own volume.
- You can also mount ./var to persist logs/cache between restarts. See commented volume in docker-compose.yml.
- The container uses Apache with DocumentRoot set to /var/www/html/public and mod\_rewrite enabled.
- The base image uses PHP 8.1 (php:8.1-apache-bullseye) to match the Composer constraint (^8.1) and to ensure the IMAP build dependencies are available. You can bump to a newer 8.x tag (e.g., 8.3) if your deployment prefers it, but ensure IMAP build deps are present for that base.

```
docker exec -it base-distribution-app bash
```

###  Health Score

50

—

FairBetter than 96% of packages

Maintenance80

Actively maintained with recent releases

Popularity25

Limited adoption so far

Community21

Small or concentrated contributor base

Maturity65

Established project with proven stability

 Bus Factor1

Top contributor holds 81.8% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~541 days

Recently: every ~667 days

Total

6

Last Release

264d ago

Major Versions

v4.0.0-alpha2 → v5.0.0-alpha12025-03-05

PHP version history (2 changes)v4.0.0-alpha1PHP ~7.0.0 || ~7.1.0 || ~7.2.0

v5.0.0-alpha1PHP ^8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/037bbc2508491c234e383f06d7d9d2c498287038887ca7fc12c9750ab015e094?d=identicon)[samtuke](/maintainers/samtuke)

![](https://www.gravatar.com/avatar/0547fb66da95b0064d5586513a5b61a915330920cc8e3a13f30682bde22fc509?d=identicon)[phplist](/maintainers/phplist)

---

Top Contributors

[![oliverklee](https://avatars.githubusercontent.com/u/765746?v=4)](https://github.com/oliverklee "oliverklee (72 commits)")[![TatevikGr](https://avatars.githubusercontent.com/u/187495323?v=4)](https://github.com/TatevikGr "TatevikGr (6 commits)")[![nfebe](https://avatars.githubusercontent.com/u/14317775?v=4)](https://github.com/nfebe "nfebe (3 commits)")[![michield](https://avatars.githubusercontent.com/u/569843?v=4)](https://github.com/michield "michield (3 commits)")[![tatevikg1](https://avatars.githubusercontent.com/u/61038422?v=4)](https://github.com/tatevikg1 "tatevikg1 (2 commits)")[![schmidtsabine](https://avatars.githubusercontent.com/u/66960492?v=4)](https://github.com/schmidtsabine "schmidtsabine (1 commits)")[![xh3n1](https://avatars.githubusercontent.com/u/9008509?v=4)](https://github.com/xh3n1 "xh3n1 (1 commits)")

---

Tags

emailmanagernewsletterphplist

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/phplist-base-distribution/health.svg)

```
[![Health](https://phpackages.com/badges/phplist-base-distribution/health.svg)](https://phpackages.com/packages/phplist-base-distribution)
```

###  Alternatives

[phplist/core

The core module of phpList, the world's most popular open source newsletter manager

874.8k3](/packages/phplist-core)[hocza/sendy

Sendy API implementation for Laravel

71192.5k](/packages/hocza-sendy)[azine/email-bundle

Symfony3 Bundle to send html- &amp; txt-emails (notification about events on your web-app or newsletters etc. scheduled/aggregated) to your users.

667.8k](/packages/azine-email-bundle)[putyourlightson/craft-campaign

Send and manage email campaigns, contacts and mailing lists.

6434.7k](/packages/putyourlightson-craft-campaign)[ecomailcz/ecomail

Ecomail.cz API Wrapper

17372.4k4](/packages/ecomailcz-ecomail)[phplist/rest-api

A REST API for phpList, the world's most popular open source newsletter manager

242.7k1](/packages/phplist-rest-api)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)
