flyeralarm/php-code-validator

A custom coding standard for FLYERALARM

4.1.1 2024-12-03 15:35 UTC

Requires

• squizlabs/php_codesniffer: ^3.5

BSD-3-Clause

• Daniel Müller
• Maximilian Grosch

README

This repository contains the ruleset for the PHP code we develop at FLYERALARM. It mostly consists of PSR-12 with some custom additions. The rules are enforced with the help of squizlabs/PHP_CodeSniffer

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Custom Rules in addition to PSR-12

• Variable names MUST be in lowerCamelCase
• Yoda conditions MUST NOT be used
• Unit tests with @expectedException MUST contain @expectedExceptionMessage annotation
• Exceptions messages MUST not contain exclamation marks or full stops
• Keywords GOTO and EVAL MUST NOT be used
• Underscores in namespaces MUST NOT be used
• Classtype suffixes like Interface, Abstract or Trait MUST NOT be used (e.g. LoggerInterface)

How-To work within this project

To prepare run command:

make build
make install

To check code style compliance or to fix what can be autofixed run commands:

make sniff
make sniff-fix

To test ruleset run command:

make test

As test runner is dockerized we can test with different PHP versions:

PHP_VERSION=8.2 make test

or all at once:

make test-all

Embed into your project

Add as composer dev dependency:

composer require --dev flyeralarm/php-code-validator

Embed code sniffer in your Makefile. To intend please use tabs instead of spaces.

Example Makefile:

test:
	vendor/bin/phpcs -w -p -s --standard=vendor/flyeralarm/php-code-validator/ruleset.xml src/ tests/

Add project specific rules

The recommended way to define custom rules for the own project is to provide a phpcs.xml in the root of your project. PHP_CodeSniffer will automatically detect this standard if no other standard was defined (See PHP_CodeSniffer Advanced Usage).

This phpcs.xml can then reference the FLYERALARM PHP coding standard.

<?xml version="1.0" encoding="UTF-8" ?>
<ruleset name="Project Rules">
    <file>./src/</file>
    <file>./tests/</file>
    <arg value="sp"/>

    <rule ref="vendor/flyeralarm/php-code-validator/ruleset.xml"/>

    <!-- custom rules -->

</ruleset>

Once the file phpcs.xml is created the code can be validated using:

vendor/bin/phpcs

Update to latest stable

composer update flyeralarm/php-code-validator

Run sniffer

make test

Use within PHPStorm

1. Ensure the path to PHP Code Sniffer is configured - open configuration manual
2. Open settings:
   Mac: PhpStorm > Preferences > Editor > Inspections > PHP
   Windows & Linux: File > Settings > Editor > Inspections > PHP \
3. Activate/Tick checkbox for PHP Code Sniffer validation
4. Click on the item PHP Code Sniffer validation to open its settings on the right hand side
5. Choose "Custom" for „Coding standard:“ and click on ... on the right hand side
6. Select Path to ruleset. This would be something like <YOUR_APP_ROOT>/vendor/flyeralarm/php-code-validator/ruleset.xml
7. Confirm dialogs by pressing ok

On a side note: We are searching for talented people to join our various teams of developers in multiple locations