README

Syde PHP Coding Standards

Syde PHP coding standards for WordPress projects.

This package contains PHP_CodeSniffer sniffs and rulesets to validate code developed for WordPress projects. It ensures code quality and adherence to coding conventions, especially the official WordPress Coding Standards, as well as select best practices from the wider web development and PHP industries.

Requirements
Installation
Rulesets
Usage
Migrating from Inpsyde to Syde PHP Coding Standards
Crafted by Syde
Copyright and License
Contributing

Requirements

The Syde PHP Coding Standards package requires:

PHP 8.1+
Composer
PHP_CodeSniffer 3.11+
PHP_CodeSniffer Standards Composer Installer Plugin 1.0+
PHPCompatibility 10+ (dev-develop)
PHPCSExtra 1.2+
PHPCSUtils 1.0+
Slevomat Coding Standard 8.15
VariableAnalysis 2.11+
WordPress Coding Standards 3.1+
WordPress VIP Coding Standards 3.0+

When installed for local development, these packages will be installed as well:

PHPStan 2.0+
PHPUnit 10.5+

Installation

Installing this package with Composer will automatically install all required dependencies, and register the rulesets from the Syde PHP Coding Standards and other external standards with PHP_CodeSniffer using the PHP_CodeSniffer Standards Composer Installer Plugin.

Local Installation

To install the Syde PHP Coding Standards, execute the following commands from the root of your project:

composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
composer require --dev syde/phpcs

Global Installation

Alternatively, you can also install the Syde PHP Coding Standards globally:

composer global config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
composer global require --dev syde/phpcs

Verify Installation

You can verify the installation by executing the following command:

./vendor/bin/phpcs -i

This should display something like the following, including the Syde PHP Coding Standards (bold):

The installed coding standards are MySource, PEAR, PSR1, PSR2, PSR12, Squiz, Zend, Syde, Syde-Core, Syde-Extra, Syde-Templates, WordPress-VIP-Go, WordPressVIPMinimum, PHPCompatibility, Modernize, NormalizedArrays, Universal, PHPCSUtils, VariableAnalysis, SlevomatCodingStandard, WordPress, WordPress-Core, WordPress-Docs and WordPress-Extra

Rulesets

This package contains four rulesets:

Syde: Complete set with all the sniffs defined in this package.
Syde-Core: Minimum required rules for modern WordPress development at scale.
Syde-Extra: Opinionated rules specific to formatting and other preferred coding practices at Syde; includes Syde-Core.
Syde-Templates: Additional rules specific to PHP template files.

Usage

Command Line

Once the package has been installed via Composer, you can run the phpcs command-line tool on a given file or directory using the desired Syde PHP Coding Standard.

For example, this is how you can check a third-party plugin for minimum required rules only:

./vendor/bin/phpcs --standard=Syde-Core ./some-plugin/

Using the full Syde standard for a specific file would look like so:

./vendor/bin/phpcs --standard=Syde ./some-plugin/some-file.php

For more information on PHP_CodeSniffer usage, refer to the documentation in the PHP_CodeSniffer Wiki.

Custom Ruleset

Like any other PHP_CodeSniffer standard, you can add the Syde PHP Coding Standard(s) to a custom PHP_CodeSniffer ruleset (e.g., a phpcs.xml.dist file).

A minimum working example could look like so:

<?xml version="1.0"?>
<ruleset>
    <!-- Minimum required Syde PHP Coding Standard rules. -->
    <rule ref="Syde-Core" />

    <!-- Secondary standard. -->
    <rule ref="MyCompanyStandard" />

</ruleset>

Using a custom ruleset avoids passing many arguments via the command line, and at the same time ensures consistent usage. All you have to do then is to run the phpcs command-line tool:

./vendor/bin/phpcs

Any argument or option you pass, will overwrite what's been defined in the custom ruleset.

Here is a real-world example including files and folders to check, as well as some PHP_CodeSniffer and ruleset configuration:

<?xml version="1.0"?>
<ruleset>
    <!-- Check for cross-version support for PHP 8.1 and higher. -->
    <config name="testVersion" value="8.1-" />

    <!-- Check for correct text domain usage. -->
    <config name="text_domain" value="my-project" />

    <file>./src</file>
    <file>./templates</file>
    <file>./tests</file>
    <file>./index.php</file>

    <!-- Use colors, and show sniff error codes and progress. -->
    <arg name="colors" />
    <arg value="sp" />

    <!-- Recommended Syde PHP Coding Standard rules. -->
    <rule ref="Syde-Extra" />

    <!-- Template-specific rules. -->
    <rule ref="Syde.ControlStructures.DisallowElse">
        <exclude-pattern>*/templates/*</exclude-pattern>
    </rule>
    <rule ref="Syde-Templates">
        <include-pattern>*/templates/*</include-pattern>
    </rule>

    <!-- Do not report on function length for tests. -->
    <rule ref="Syde.Functions.FunctionLength">
        <exclude-pattern>*/tests/cases/*</exclude-pattern>
    </rule>

    <!-- PSR-4 namespace configuration. -->
    <rule ref="SlevomatCodingStandard.Files.TypeNameMatchesFileName">
        <properties>
            <property name="rootNamespaces" type="array">
                <element key="src" value="MyCompany\MyProject" />
                <element key="tests/cases" value="MyCompany\MyProject\Tests" />
                <element key="tests/src" value="MyCompany\MyProject\Tests" />
            </property>
        </properties>
    </rule>

    <!-- Secondary standard. -->
    <rule ref="MyCompanyStandard" />

</ruleset>

For more information, take a look at Using a Default Configuration File and the Annotated Ruleset pages in the PHP_CodeSniffer Wiki.

Customization

The Syde PHP Coding Standards contain a number of sniffs that are configurable. This means that you can turn parts of the sniff on or off, or change the behavior by setting a property for the sniff in your custom ruleset file.

You can find a complete list of all the properties you can change for the Syde PHP Coding Standards in the list of all sniffs.

Auto-Fixing

The Syde PHP Coding Standards include several sniffs that support automatic fixing of coding standard violations. These sniffs are marked with the 🔧 symbol in the list of all sniffs. To fix your code automatically, run the phpcbf command-line tool instead of phpcs:

./vendor/bin/phpcbf --standard=Syde-Extra ./some-file.php

Always remember to back up your code before performing automatic fixes. Also, make sure to manually check the updated code as the automatic fixer can sometimes produce unwanted results.

Disabling or Excluding Rules

For information about disabling or excluding rules, refer to the Disabling or Excluding Rules page in the docs/ folder.

IDE Integration

For information about IDE integration (currently PhpStorm only), refer to the IDE Integration page in the docs/ folder.

Migrating from Inpsyde to Syde PHP Coding Standards

In case you are already using the Inpsyde PHP Coding Standards (version 1 or 2) and want to migrate to the Syde PHP Coding Standards, refer to the Migration page in the docs/ folder.

Crafted by Syde

The team at Syde is engineering the Web since 2006.

Copyright and License

This package is free software distributed under the terms of the GNU General Public License version 2 or (at your option) any later version. For the full license, see LICENSE.

Contributing

All contributions are very welcome. Please read the CONTRIBUTING documentation to get started.

By contributing code, you grant its use under the current license (see LICENSE).

syde / phpcs

Maintainers

Details