This is a PHP Codesniffer standard enhancing the Drupal Coder project. It is designed to be utilised on full Drupal site projects, rather than core or contrib, or projects outside of Drupal.
The standard improves upon the Drupal standard, while maintaining the general style of Drupal.
Rules are loosened where static analysis tools such as PHPStan are better at enforcing.
Documentation rules are loosened, trusting developers to properly self describe code. Suggestions to improve documentation are encouraged during human code review of MR/PR's.
Rules added are generally those we think would be accepted by Drupal Coder itself.
Generally, rules that are not auto-fixable, especially documentation/commenting related, will be stripped from the ruleset.
New rules may be introduced in minor versions. You can choose to lock a version until you are ready, or utilise the baseline project.
MIT
Consider using the Baseliner project when
transitioning. A quick phpcbf beforehand will eliminate most or all problems
before they are added to a baseline.
composer require --dev digitalrevolution/php-codesniffer-baseline
php bin/phpcs --report=\\DR\\CodeSnifferBaseline\\Reports\\Baseline --report-file=phpcs.baseline.xmlUnlike PHPStan's reportUnmatchedIgnoredErrors, warnings will not display when
items in the PHPCS baseline are resolved. Instead, work until no CS issues are
reported with phpcs, then regenerate with the same baseline command above.
Use the installer via Composer:
composer require dealerdirect/phpcodesniffer-composer-installerInstall this project with:
composer require previousnext/coding-standardDependencies such as Coding standard, Drupal Coder, and Slevomat Coding Standard will be brought in automatically.
Create a phpcs.xml file in a project root with the following contents:
<?xml version="1.0" encoding="UTF-8"?>
<ruleset name="My Coding Standard">
<file>./src</file>
<file>./tests</file>
<file>./app/modules/custom</file>
<file>./app/profiles/custom</file>
<file>./app/themes/custom</file>
<rule ref="PreviousNextDrupal" />
<arg name="report" value="full"/>
</ruleset>This standard does not assume the location of code, so all covered paths must be added to the extending ruleset.
Parameters and return documentation may be omitted.
If you intend to add typing, but do not care to document what a param or return
does, then consider using @phpstan- prefixed annotations. Such as
@phpstan-param or @phpstan-return.
Example
From Drupal Coder style:
/**
* Does a thing.
*
* @param array $data
* Some data.
*
* @return int
* An integer.
*/
function foo(array $data): int {
}To:
Remove useless documentation for the function/method itself. Human code review must ensure the function/method/variable/param, etc, are self describing.
/**
* @phpstan-param array{bar: int} $data
* @phpstan-return int{0, max}
*/
function doesAThing(array $data): int {
}PHPStorm can be configured with Editor -> General -> Auto Import: Function: Prefer FQN
- Drupal.Commenting.ClassComment.Short
- Drupal.Commenting.DocComment.MissingShort
- Drupal.Commenting.FileComment.Missing
- Drupal.Commenting.FunctionComment.IncorrectParamVarName
- Drupal.Commenting.FunctionComment.InvalidReturn
- Drupal.Commenting.TodoComment.TodoFormat
- Drupal.Commenting.VariableComment.Missing
Commenting rules are not auto-fixable, are usually boilerplate-y.
Developers are entrusted to properly self-describe code. Suggestions to improve documentation are encouraged during human code review of MR/PR's.
This rule has trouble with newer PHP syntax, especially expression throwables. In any case this rule is best enforced with static analysis.
Drupal is a registered trademark of Dries Buytaert.