Susina Utils

Contributing

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

Contributing to the code

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, php-cs-fixer, phpDocumentor) avoiding dependencies conflicts.

Workflow

  1. Fork susina/utils repository.
  2. Run composer install to install dependencies and create the correct autoloading map.
  3. Run phive install to safely install our development tools.
  4. Apply your patches.
  5. Run the test suite composer test and fix all red tests.
  6. Run static analysis tool by composer analytics and fix all errors.
  7. Fix the coding standard by running composer cs:fix .

We provide a check command which runs the test suite, analytics tool and coding standard fix in one go. 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

Phive creates symbolic links into you tools directory, instead of always download the full phar libraries. If your editor can't follow the symlinks for autocompletion, download Phpunit library only phar file and put it into tools directory.

Code Coverage

We ship 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 PHPStan as static analysis tool. 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.

Contributing to the documentation

Our documentation resides in the docs directory and is written in reStructuredText format. The documentation site is generated by phpDocumentor tool and can be built by running the following command:

composer docs:build

You can find the generated documentation in the .phpdoc/build directory.

We also provide a command to serve the documentation site locally, so you can preview your changes before submitting a pull request:

composer docs:serve

This command will build the documentation and serve it on http://localhost:8000 using PHP built-in web server. As usual, you can stop the server by pressing CTRL+C in the terminal.

Search results