README

This package contains a base set of coding standards for StellarWP package development.

The rules are generally based on the PSR-12 coding standard, which is generally recommended within the larger PHP community.

Additionally, since StellarWP is largely-focused on WordPress, our standards also include important WordPress-oriented rules (e.g. late-escaping of output, input sanitization, nonce usage, etc.).

What's included?

There are two main tools included in this package:

PHP_CodeSniffer

PHP_CodeSniffer is the de-facto linting tool for PHP, and there are a number of pre-configured standards available.

This package includes PHP_CodeSniffer itself, along with the WordPress Coding Standards ruleset, PHP compatibility checks, and Dealerdirect's Composer installer for PHP_CodeSniffer.

PHP-CS-Fixer

PHP-CS-Fixer is an additional coding standards checker for PHP, maintained by several members of the Symfony team. It provides a bit more flexibility around more sophisticated checks and experiemental features.

Installation

This package should be installed as a development dependency for your project:

$ composer require --dev stellarwp/coding-standards

This will automatically expose the phpcs, phpcbf, and php-cs-fixer binaries in your project's vendor/bin directory.

You may also wish to add the following Composer scripts to make it easier to run checks:

# composer.json
{
    // ...
    "scripts": {
        // ...
        "test:standards": [
            "phpcs --standard=StellarWP --cache ./src ./tests",
            "php-cs-fixer fix --config=vendor/stellarwp/coding-standards/src/php-cs-fixer.php -v --diff --dry-run"
        ],
        "test:standards-fix": [
            "phpcbf --standard=StellarWP ./src ./tests",
            "php-cs-fixer fix --config=vendor/stellarwp/coding-standards/src/php-cs-fixer.php -v --diff"
        ]
    },
    "scripts-descriptions": [
        "test:standards": "Check coding standards.",
        "test:standards-fix": "Attempt to fix coding standards violations automatically.",
    ]
}

Note: You may need to adjust paths to suit your project, especially if your Composer "vendor-dir" has been changed.

Project-specific configuration

The default coding standards make a few assumptions about the project (all of which may be overwritten on a per-project basis):

Code should be compatible with PHP 5.6 or newer (to match WordPress' minimum requirements)
Code should be compatible with the latest and previous major release WordPress (a.k.a. "current minus one")
Anything passed through WordPress' internationalization (i18n) functions should use the "stellarwp" text domain

Rather than overwriting these values via command-line arguments, it's recommended to create a PHP_CodeSniffer configuration file in your project. An annotated starter configuration is included in this package, and can automatically be copied into the project root (.phpcs.xml.dist) by running the following command:

$ vendor/bin/make-phpcs-config

Should you need to change the rules for PHP-CS-Fixer, you may publish a .php-cs-fixer.dist.php file by running the following:

$ vendor/bin/make-php-cs-fixer-config

If you've copied the default test:standards and test:standards-fix scripts into your composer.json file, please be sure to update their arguments!

# composer.json
{
    // ...
    "scripts": {
        // ...
        "test:standards": [
            "phpcs --cache",
            "php-cs-fixer fix --config=.php-cs-fixer.dist.php -v --diff --dry-run"
        ],
        "test:standards-fix": [
            "phpcbf",
            "php-cs-fixer fix --config=.php-cs-fixer.dist.php -v --diff"
        ]
    },
}

License

This library is licensed under the terms of the MIT license.

stellarwp / nexcess-coding-standards

Maintainers

Details