Inpsyde PHP Coding Standards
PHP 7+ coding standards for Inpsyde WordPress projects.
Installation
The code styles are enforced via the popular php_codesniffer
and can be installed via Composer by the name inpsyde/php-coding-standards
.
It means they can be installed by adding the entry to composer.json require-dev
:
{
"require-dev": {
"inpsyde/php-coding-standards": "^1@dev"
}
}
(the @dev
suffix can be removed if the project minimum-stability
is "dev"
, or as soon as the stable v1.0.0 of the standards will be released.)
or via command line with:
$ composer require inpsyde/php-coding-standards --dev
Usage
Basic usage
When the package is installed via Composer, and dependencies are updated, everything is ready and the coding standards can be checked via:
$ vendor/bin/phpcs --standard="Inpsyde" <path>
Where
is at least one file or directory to check, e.g.:
$ vendor/bin/phpcs --standard="Inpsyde" ./src/ ./my-plugin.php
On Windows it would be something like:
$ ./vendor/bin/phpcs.bat --standard="Inpsyde" ./src/ ./my-plugin.php
There are many options that can be used to customise the behavior of the command, to get documentation use:
$ vendor/bin/phpcs --help
Configuration File
To do not have to pass all the arguments to the command line, and to also be able to do customization it is also possible to create a phpcs.xml.dist
file that contains something like this:
xml version="1.0"?>
<ruleset name="MyProjectCodingStandard">
<description>My Project coding standard.description>
<file>./srcfile>
<file>./tests/srcfile>
<arg value="sp"/>
<arg name="colors"/>
<config name="testVersion" value="7.2-"/>
<config name="text_domain" value="my-project"/>
<rule ref="Inpsyde">
<exclude name="WordPress.PHP.DiscouragedPHPFunctions.serialize_serialize" />
rule>
<rule ref="Inpsyde.CodeQuality.Psr4">
<properties>
<property
name="psr4"
type="array"
value="Inpsyde\MyProject=>src,Inpsyde\MyProject\Tests=>tests/src|tests/unit"/>
properties>
rule>
<rule ref="Inpsyde.CodeQuality.ElementNameMinimalLength">
<properties>
<property name="additionalAllowedNames" type="array" value="c,me,my" />
properties>
rule>
ruleset>
Such a configuration allows to run the code style check with only:
$ vendor/bin/phpcs
Moreover, thanks to the text_domain
setting, Code Sniffer will also check that all WP internationalization functions are called with the proper text domain.
Included rules
PSR-1, PSR-2, PSR-12
See https://www.php-fig.org/psr/psr-1, https://www.php-fig.org/psr/psr-2, https://www.php-fig.org/psr/psr-12
Neutron Standard
See https://github.com/Automattic/phpcs-neutron-standard
Almost all Neutron Standard rules are included.
WordPress Coding Standard
To ensure code quality, and compatibility with VIP, several WordPress Coding Standard rules have been "cherry picked" from WP coding standards.
See https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards.
PHPCompatibility
See https://github.com/wimg/PHPCompatibility.
It allows to analyse code for compatibility with higher and lower versions of PHP. The default target version is PHP 7.0+.
Target version can be changed via custom phpcs.xml
.
Generic Rules
Some rules are also included from PHPCS itself. Those rules fall in the "Generic", "Squiz" and "PEAR" namespace. Some of them are included by other styles, mainly by PSR-1 and PSR-2.
Custom Rules
Some custom rules are also in use. They are:
Sniff name | Description | Has Config | Auto-Fixable |
---|---|---|---|
ArgumentTypeDeclaration |
Enforce argument type declaration. | ||
ConstantVisibility |
Force use of visibility for constants. | ||
DisallowShortOpenTag |
Disallow short open PHP tag (short echo tag allowed). | ||
ElementNameMinimalLength |
Use minimum 3 chars for names (with a few exclusions) | ✓ | |
ForbiddenPublicProperty |
No public class properties | ||
FunctionBodyStart |
Handle blank line at start of function body. | ✓ | |
FunctionLength |
Max 50 lines per function/method, excluding blank lines and comments-only lines. | ✓ | |
HookClosureReturn |
Ensure that actions callbacks do not return anything, while filter callbacks return something. | ||
LineLength |
Max 100 chars per line | ✓ | |
NestingLevel |
Max indent level of 3 inside functions | ✓ | |
NoAccessors |
Discourage usage of getters and setters. | ||
NoElse |
Discourage usage of else . |
||
NoTopLevelDefine |
Discourage usage of define where const is preferable. |
||
PropertyPerClassLimit |
Discourage usage of more than 10 properties per class. | ✓ | |
Psr4 |
Check PSR-4 compliance | ✓ | |
ReturnTypeDeclaration |
Enforce return type declaration | ||
StaticClosure |
Points closures that can be static . |
✓ | |
VariablesName |
Check variable (and properties) names | ✓ |
For notes and configuration see /inpsyde-custom-sniffs.md
file in this repo.
Removing or Disabling Rules
Rules Tree
Sometimes it is necessary to don't follow some rules. To avoid error reporting is is possible to:
- Removing rules for an entire project via configuration
- Disabling rules from code, only is specific places
In both cases it is possible to remove or disable:
- a whole standard
- a standard subset
- a single sniff
- a single rules
The for things above are in hierarchical relationship: a standard is made of one or more subset, each subset contains one or more sniff and each sniff contains one or more rule.
Remove rules via configuration file
Rules can be removed for the entire project by using a custom phpcs.xml
, with a syntax like this:
xml version="1.0"?>
<ruleset name="MyProjectCodingStandard">
<rule ref="Inpsyde">
<exclude name="PSR1.Classes.ClassDeclaration"/>
rule>
ruleset>
In the example above, the sniff PSR1.Classes.ClassDeclaration
(and all the rules it contains) has been removed.
Replacing PSR1.Classes.ClassDeclaration
with just PSR1
had been possible to remove the whole standard, while replacing it with PSR1.Classes.ClassDeclaration.MultipleClasses
only the single rule is removed.
Remove rules via code comments
If it is necessary to remove a rule/sniff/standard subset/standard only in specific place in the code, it is possible to use special comments that starts with:
// phpcs:disable
followed by the what you want to to remove.
For example: // phpcs:disable PSR1.Classes.ClassDeclaration
.
From the point the comment is encountered to the end of the file, the requested rule/sniff/standard subset/standard is not checked anymore.
To re-enable it is necessary to use a similar syntax, but this time using phpcs:enable
instead of phpcs:disable
.
It worth noting:
phpcs:disable
andphpcs:enable
can be used without specifying the rule name, in this case the check for all rules are disabled/enabled.- Disabling / enabling comments could be embedded in doc block comments at file/class/method level. For example:
class Foo
{
/**
* @param mixed $a
* @param mixed $b
*
* phpcs:disable NeutronStandard.Functions.TypeHint.NoArgumentType
*/
public function test($a, $b)
{
// phpcs:enable
}
}
IDE integration
PhpStorm
After having installed the package as explained above in the "Installation" section, open PhpStorm settings, and navigate to
Language & Frameworks
-> PHP
-> Quality Tools
-> PHP_CodeSniffer
Choose "Local" in the "Configuration" dropdown.
Click the "..." button next to the dropdown, it will show a dialog where you need to specify the path for the Code Sniffer executable.
Open the file selection dialog, navigate to vendor/bin/
in your project and select phpcs
(phpcs.bat
on Windows).
Click the "Validate" button next to the path input field, if everything is fine a success message will be shown at the bottom of the window.
Navigate PhpStorm settings to:
Editor
-> Inspections
Type codesniffer
in the search field before the list of inspections, select PHP
-> Quality Tools
-> PHP_CodeSniffer validation
and enable it using the checkbox in the list, press "Apply".
Select "PHP_CodeSniffer validation", press the refresh icon next to the "Coding standard" dropdown on the right and choose Inpsyde
.
If you do not see Inpsyde
here, you may need to specify phpcs.xml
file by selecting "Custom" as standard and using the "..." button next to the dropdown.
Now PhpStorm integration is complete, and errors in the code style will be shown in the IDE editor allowing to detect them without running any commands at all.
Contribution
Running tests
To run the tests for this package you need to install its dependencies first:
$ composer install
After that you can run all PHPUnit tests like this:
$ vendor/bin/phpunit
The tests are organized in fixture files. If you want to run a single test use the filter argument:
$ vendor/bin/phpunit --filter function-length-no-blank-lines