Phootwork Contributing Guide

If you're reading this document, it is likely that you have decided to contribute to this project. Therefore, first of all, we want to warmly thank you! The Open Source Software grows and improves thanks to people like you!

Contributing to a project is a process with its own rules and we try to explain them along this document.

Quick Start for Experienced Programmers

1. Fork, clone and apply your patches. See the directory structure explanation if needed and don't forget to write tests.
2. Run the test suite composer test and fix all red tests.
3. Run static analysis tool (by now, we use Psalm) composer analytics and fix all errors and issues.
4. Fix the coding standard composer cs-fix.

Requirements

To contribute to this project, you should have an good knowledge of PHP (of course) and a basic knowledge of git, Github and the dependency manager composer.

First Step: Clone the Project and Install the Dependencies

The phootwork project is a collection of single libraries that can be installed separately. Anyway, all the development process takes place in the global repository https://github.com/phootwork/phootwork .

So, the first step is to fork the phootwork repository on Github and clone it on your local machine. If you have any doubt, please read https://help.github.com/en/articles/fork-a-repo .

Then install the dependencies:

composer install

Understanding the Directory Structure

After cloning and installing the dependencies, you should have a directory structure like the following:

   ├── src
   │   ├── collection
   │   ├── file
   │   │   └── exception
   │   ├── json
   │   ├── lang
   |   |   ├── inflector
   │   │   └── parts
   │   ├── tokenizer
   │   └── xml
   │       └── exception
   ├── tests
   │   ├── collection
   │   │   └── fixtures
   │   ├── file
   │   ├── json
   │   ├── lang
   │   │   ├── fixtures
   │   │   └── inflector
   │   ├── tokenizer
   │   │   └── fixtures
   │   │       └── samples
   │   └── xml
   │       └── fixtures
   └── vendor

As usual, into the directory vendor you can find all the libraries Phootwork depends on, both for runtime and development.

The directory src contains the source code of our libraries and tests contains the relative tests.

Both src and tests have sub-folders which correspond to the single libraries. E.g. you can find the source code of the library https://github.com/phootwork/lang into src/lang folder and the relative tests into tests/lang directory.

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

Since our command runs phpunit binary under the hood, you can pass all phpunit options to it via the -- operator, i.e.:

composer test -- --stop-on-failure

You can also use phpunit directly:

vendor/bin/phpunit

Each single library has its own test suite and you can launch it separately. I.e. if you want to run the phootwork/lang test suite:

composer test -- --testsuite lang

or alternatively:

vendor/bin/phpunit --testsuite lang

The last two commands can be useful to speed up the tests, if your contribution involves only one library.

Phootwork also provides a command to generate a code coverage report in html format, into the coverage/ directory:

composer coverage

Static Analysis Tool

To prevent as many bugs as possible, we use a static analysis tool called Psalm. To launch it, run the following command from the root directory of Phootwork project:

composer analytics

After its analysis, Psalm outputs errors and issues with its suggestions on how to fix them. Errors are more important and generally more dangerous than issues, anyway you should fix both.

Coding Standard

Phootwork ships its scripts 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

If you want to learn more about phootwork code style, see https://github.com/phootwork/php-cs-fixer-config.

Icing on the Cake

Phootwork provides a script to run all the previous explained commands in a single line:

composer check

It runs all the tests, analytics and code fixers needed before submitting a pull request.