Contributing to this project
When you contribute, please take the following things into account:
Contributor Code of Conduct
Please note that this project is released with a Contributor Code of Conduct. By participating in this project, you agree to abide by its terms.
Reporting an issue
We have provided an issue template that will help you create helpful tickets.
Do not report an issue if …
- … you are asking how to use some feature. Please use the phpList community for this purpose.
- … your issue is about a security vulnerability. Please contact us directly to report security issues.
Avoid duplicated issues
Before you report an issue, please search through the existing issues here on GitHub to see if your issue is already reported or fixed to make sure you are not reporting a duplicated issue.
Also please make sure you have the latest version of this package and check if the issue still exists.
Contribute code, bug fixes or documentation (pull requests)
Third-party contributions are essential for keeping the project great.
We want to keep it as easy as possible to contribute changes that get things working in your environment.
There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things:
- Make sure you have a GitHub account.
- Fork this Git repository.
- Clone your forked repository and install the development dependencies doing
- Add a local remote "upstream" so you will be able to synchronize your fork with the original repository.
- Create a local branch for your changes.
- Add unit tests for your changes (if your changes are code-related). These tests should fail without your changes.
- Add your changes. Your added unit tests now should pass, and no other tests should be broken. Check that your changes follow the coding style.
- Add a changelog entry.
- Commit and push your changes.
- Create a pull request for your changes. Check that the Github actions build is green. (If it is not, fix the problems listed by Github actions.) We have provided a template for pull requests as well.
- Request a review.
- Together with your reviewer, polish your changes until they are ready to be merged.
API Documenting with
If you add or modify existing annotations, you should run
composer openapi-generate to have the updated openapi decription of the API.
- The generated
docs/openapi.jsonis excluded in commits. See .gitignore
- The only reason you should generate
openapi.jsonis for debugging and testing.
To ensure builds pass and new annotations are deployed, do validate
openapi.json by copy-pasting it's content in
In addition you can also use the openapi-checker to validate you file as follows;
npm install -g openapi-checker
composer openapi-generate basically runs
vendor/bin/openapi -o docs/openapi.json --format json src defined in the scripts section of
composer.json which as mentioned above generates
openapi.json description file in the
You might also achieve local visualization by cloning phplist/restapi-docs and temporally changing the
url property of
SwaggerUIBundle to point to your generated file.
Unit-test your changes
Please cover all changes with automatic tests and make sure that your code does not break any existing tests. We will only merge pull request that include full code coverage of the fixed bugs and the new features.
Running the unit tests
To run the existing unit tests, run this command:
Running the integration tests
For being able to run the integration tests, you will need a local MySQL database and a user with access permissions to that database.
After you have created the database and the user, please import the database
schema once. Assuming that your database is named
phplist_test, the user is
phplist, and the password is
batterystaple, the command looks like
mysql -u phplist_test --password=batterystaple phplist_test < vendor/phplist/core/resources/Database/Schema.sql
When running the integration tests, you will need to specify the database name and access credentials on the command line (in the same line):
PHPLIST_DATABASE_NAME=phplist_test PHPLIST_DATABASE_USER=phplist PHPLIST_DATABASE_PASSWORD=batterystaple vendor/bin/phpunit -c config/PHPUnit/phpunit.xml tests/Integration/
Please make your code clean, well-readable and easy to understand.
Please use the same coding style (PSR-2) as the rest of the code. Indentation for all files is four spaces.
We will only merge pull requests that follow the project's coding style.
Please check your code with the provided PHP_CodeSniffer standard:
vendor/bin/phpcs --standard=vendor/phplist/core/config/PhpCodeSniffer/ src/ tests/
Please also check the code structure using PHPMD:
vendor/bin/phpmd src/ text vendor/phplist/core/config/PHPMD/rules.xml
And also please run the static code analysis:
vendor/bin/phpstan analyse -l 5 src/ tests/
You can also run all code style checks using one long line from a bash shell:
find src/ tests/ -name '*.php' -print0 | xargs -0 -n 1 -P 4 php -l && vendor/bin/phpstan analyse -l 5 src/ tests/ && vendor/bin/phpmd src/ text vendor/phplist/core/config/PHPMD/rules.xml && vendor/bin/phpcs --standard=vendor/phplist/core/config/PhpCodeSniffer/ src/ tests/
This will execute all tests except for the unit tests and the integration tests.