README

PHP 7.4+ coding standards for Syde WordPress projects.

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>

Here, <path> is at least one file or directory to check, for example:

vendor/bin/phpcs --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

A phpcs.xml.dist file can be used to avoid passing many arguments via the command line. For example:

<?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.4-"/>
    <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>

</ruleset>

Such a configuration allows to run the code style check like so:

vendor/bin/phpcs

Moreover, thanks to the text_domain setting, PHP_CodeSniffer will also check that all WordPress internationalization functions are called with the proper text domain.

Included rules

For the detailed lists of included rules, refer to ruleset.xml.

PSR-1, PSR-2, PSR-12

For more information about included rules from PHP Standards Recommendations (PSR), refer to the official documentation:

WordPress Coding Standards

To ensure code quality, and compatibility with WordPress VIP, some rules have been included from:

Slevomat

A few rules have been included from the Slevomat Coding Standard.

PHPCompatibility

For PHP cross-version compatibility checks, the full PHP Compatibility Coding Standard for PHP CodeSniffer standard has been included.

The target PHP version (range) can be changed via a custom phpcs.xml file.

Generic Rules

Some rules are also included from PHP_CodeSniffer itself, as well as PHPCSExtra.

Custom Rules

The following custom rules are in use:

For notes and configuration, refer to the inpsyde-custom-sniffs.md file in this repository.

Template Rules

The InpsydeTemplates ruleset extends the standard Inpsyde ruleset with some template-specific sniffs.

The recommended way to use the InpsydeTemplates ruleset is as follows:

<ruleset>
    <file>./src</file>
    <file>./templates</file>
    <file>./tests</file>
    <file>./views</file>

    <rule ref="Inpsyde"/>

    <rule ref="InpsydeTemplates">
        <include-pattern>*/templates/*</include-pattern>
        <include-pattern>*/views/*</include-pattern>
    </rule>
</ruleset>

The following template-specific rules are available:

Removing or Disabling Rules

Rules Tree

Sometimes it is necessary not to follow some rules. To avoid error reporting, it is possible to:

remove rules for an entire project via configuration;
disable rules from code, only is specific places.

In both cases, it is possible to remove or disable:

a complete standard;
a standard subset;
a single sniff;
a single rule.

These things are in a hierarchical relationship: standards are made of one or more subsets, which contain one or more sniffs, which in turn contain one or more rules.

Removing Rules via Configuration File

Rules can be removed for the entire project by using a custom phpcs.xml file, like this:

<?xml version="1.0"?>
<ruleset name="MyProjectCodingStandard">

    <rule ref="Inpsyde">
        <exclude name="PSR1.Classes.ClassDeclaration"/>
    </rule>

</ruleset>

In the example above, the PSR1.Classes.ClassDeclaration sniff (and all the rules it contains) has been removed.

By using PSR1 instead of PSR1.Classes.ClassDeclaration, one would remove the entire PSR1 standard, whereas using PSR1.Classes.ClassDeclaration.MultipleClasses would remove this one rule only, but no other rules in the PSR1.Classes.ClassDeclaration sniff.

Removing Rules via Code Comments

Removing a rule/sniff/subset/standard only for a specific file or a part of it can be done by using special phpcs annotations/comments, for example, // phpcs:disable followed by an optional name of a standard/subset/sniff/rule. Like so:

// phpcs:disable PSR1.Classes.ClassDeclaration

For more information about ignoring files, please refer to the official PHP_CodeSniffer Wiki.

IDE Integration

PhpStorm

After installing the package as explained above, 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 PHP_CodeSniffer executable.

Open the file selection dialog, navigate to vendor/bin/ in your project, and select phpcs. On Windows, choose phpcs.bat.

Click the "Validate" button next to the path input field. If everything is working fine, a success message will be shown at the bottom of the window.

Still in the PhpStorm settings, navigate to:

Editor -> Inspections

Type codesniffer in the search field before the list of inspections, then select:

PHP -> Quality Tools -> PHP_CodeSniffer validation

Enable it using the checkbox in the list, press "Apply".

Select "PHP_CodeSniffer validation", click the refresh icon next to the "Coding standard" dropdown on the right, and choose Inpsyde.

If you don't see Inpsyde here, you may need to specify the phpcs.xml file by selecting "Custom" as standard and then use the "..." button next to the dropdown.

Once the PhpStorm integration is complete, warnings and errors in your code will automatically be shown in your IDE editor.

Installation

Via Composer, require as development dependency:

composer require "inpsyde/php-coding-standards:^2@dev" --dev

(Please note that @dev can be removed as soon as a stable 2.0.0 version has been released, or if your root package minimum stability is dev).

inpsyde / php-coding-standards

Maintainers

Details