Skip to content

Contributing

First of all, many thanks to spend your time on this library!

Workflow

Pre-requisites

  1. Have PHP 8.5 installed.
  2. Have Composer installed to manage dependencies and autoloading.

  3. Have Phive to install and manage our development tools (PhpUnit, PhpStan, PhpDocumentor etc.) avoiding dependencies conflicts.

  4. Fork susina/config-builder repository.

  5. Run composer install to install dependencies and create the correct autoloading map.
  6. Run phive install to safely install our development tools.
  7. Apply your patches.
  8. Run the test suite by composer test command and fix all red tests.
  9. Run static analysis tool by composer analytics command and fix all errors.
  10. Fix the coding standard by running composer cs:fix.

Tip

We provide a check command which runs the test suite, analytics tool and coding standard fix. So, before submitting a pull request you can simply run composer check.

Running the Test Suite

While developing, the test part is very important: if you apply a patch to the existing code, the test suite must run without errors or failures and if you add a new functionality, no one will consider it without tests.

Our test tool is PhpUnit and we provide a script to launch it:

composer test

Code Coverage

We provides two commands to generate the code coverage report in html or xml format:

  • composer coverage:html command generates a code coverage report in html format, into the directory coverage/
  • composer coverage:clover generates the report in xml format, into clover.xml file.

Static Analysis Tool

To prevent as many bugs as possible, we use a static analysis tool called PHPStan. To launch it, run the following command:

composer analytics

After its analysis, PHPStan outputs errors and issues with its suggestions on how to fix them.

Coding Standard

We ship our script to easily fix coding standard errors, via php-cs-fixer tool. To fix coding standard errors just run:

composer cs:fix

and to show the errors without fixing them, run:

composer cs:check

All the repositories inside Susina Project follow PER 3.x coding style.

Documentation Contributing

susina/config-builder documentation resides into the directory docs/. It's written in markdown and it's generated by Zensical: a static site generator. To install Zensical please refer to https://zensical.org/docs/get-started/#installation.

Markdown flavour

Zensical uses Python-Markdown with some extensions active by default. It supports the standard markdown, markdown-extra and some of the Github-flavoured markdown features (i.e. syntax highlight). You can find detailed information on https://zensical.org/docs/authoring/markdown/.

Admonition

admonition extension helps to write beautiful notes or warnings or other (see the official documentation) with a syntax like the following:

!!! Danger
    Very dangerous operation!

which translates into the following:

Danger

Very dangerous operation!

Api Documentation

We use Php Documentor to generate the project api documentation, starting from the docbloc comments along the code. The documentation api is accesible via the site menu.

Since the api is not generated by Zensical, it doesn't correctly serve the documentation site locally. If you want to navigate the site locally, follow these steps (from the project root directory):

  1. build the documentaion site with Zensical: run zensical build
  2. build the documentation api with PHPDocumentor: run composer api:doc
  3. run the php local server: php -S localhost:8000 -t _site/