Difference between revisions of "Development/Coding standard"

Revision as of 16:22, 29 March 2021

Main Page > Development > Development/Coding standard

AtoM uses PHP CS Fixer to check and auto-format the PHP code following the @PhpCsFixer ruleset, a highly opinionated extension of the Symfony Coding Standards and the PSR-12 coding style specification.

The PHP CS Fixer tool is included in the AtoM project's Composer dependencies for development. PHP CS Fixer's configuration is tracked as part of the project's source code (see .php_cs) and it's used in the Continuous Integration process to check the code on every pull request and commit merged to the stable/** and qa/** branches.

Contributors to the AtoM project should run PHP CS Fixer locally to ensure their modifications meet the coding standards. There are a number of options for running PHP CS Fixer on your code: PHP CS Fixer's README file links to plugins for several popular code editors (e.g. VS Studio Code, atom.io, Sublime text), you can configure a git pre-commit hook to run PHP CS Fixer when commiting changes, or PHP CS Fixer can be run manually.

Coding Standards that are not handled by PHP CS Fixer

While PHP CS Fixer covers a lot of rules to meet the coding standard, there are a few cases that need to be handled manually, especially for multi-line statements. The PSR-12 standard doesn't impose a hard limit on line length, but it recommends a soft limit of 120 characters, and to keep lines under 80 characters where possible. However, the following cases need to be manually edited at the moment:

Multi-line method calls

Due to an issue formatting the Symfony templates, the ensure_fully_multiline option of the method_argument_space rule is currently disabled. Nevertheless, as noted in the PSR-12 standard:

Argument lists MAY be split across multiple lines, where each subsequent line is indented once. When doing so, the first item in the list MUST be on the next line, and there MUST be only one argument per line. A single argument being split across multiple lines (as might be the case with an anonymous function or array) does not constitute splitting the argument list itself.

<?php

$foo->bar(
    $longArgument,
    $longerArgument,
    $muchLongerArgument
);

N.B.: AtoM argument lists SHOULD be split into multiple lines, according to the rules above, to keep the line length under 80 characters.

Multi-line control structures

[ The PSR-12 standard on control structures](https://www.php-fig.org/psr/psr-12/#5-control-structures) is not fully covered by PHP CS Fixer currently, but control structure formatting follows the same pattern as the method call formatting, with the additional rule:

Boolean operators between conditions MUST always be at the beginning or at the end of the line, not a mix of both.

<?php

if (
    $expr1
    && $expr2
) {
    // if body
} elseif (
    $expr3
    && $expr4
) {
    // elseif body
}

N.B. AtoM boolean operators MUST come at the beginning of the line, as shown above, when boolean statements are split over multiple lines.*

Multi-line assignments

The PSR-12 standard doesn't specify how to format multi-line assignments, nor does the @PhpCsFixer ruleset. However, the AtoM standard formats multi-line assignments thus:

- The assignment statement starts on the same line as the assigned variable or "return" keyword. - Subsequent operators come at the start of the following lines, with indentation.

For example:

<?php

$foo = $condition
    ? 'true value'
    : 'false value';

return $conditionOne
    && $conditionTwo
    && $conditionThree;

$sum = $sumOne
    + $sumTwo
    + 123;

return $stringOne
    .$stringTwo
    .' extra content';

$bar = 'Long string
    where whitespace
    is not an issue';

N.B. statements SHOULD NOT be broken over multiple lines unless it is necessary to keep lines under the recommended 80 character line length.

• Back to top