PHP 7+ coding standards for Inpsyde WordPress projects.
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": "^0.13"
}
}or via command line with:
$ composer require inpsyde/php-coding-standards --devWhen 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 <path> is at least one file or directory to check, e.g.:
$ vendor/bin/phpcs --standard="Inpsyde" ./src/ ./my-plugin.phpOn Windows it would be something like:
$ ./vendor/bin/phpcs.bat --standard="Inpsyde" ./src/ ./my-plugin.phpThere are many options that can be used to customise the behavior of the command, to get documentation use:
$ vendor/bin/phpcs --helpTo 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>./src</file>
<file>./tests/src</file>
<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/phpcsMoreover, thanks to the text_domain setting, Code Sniffer will also check that all WP
internationalization functions are called with the proper text domain.
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
See https://github.com/Automattic/phpcs-neutron-standard
Almost all Neutron Standard rules are included.
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.
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.
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.
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.
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.
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.
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:disablefollowed 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:disableandphpcs:enablecan 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
}
}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.
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