yoast/yoastcs

PHP_CodeSniffer rules for Yoast projects

Installs: 203 655

Dependents: 21

Suggesters: 0

Security: 0

Stars: 17

Watchers: 14

Forks: 3

Open Issues: 30

Type:phpcodesniffer-standard

2.2.0 2021-09-22 14:11 UTC

README

Yoast Coding Standards (YoastCS) is a project with rulesets for code style and quality tools to be used in Yoast projects.

Installation

Standalone

Standards are provided as a Composer package and can be installed with:

composer create-project yoast/yoastcs:dev-master

Composer will automatically install dependencies, register standards paths, and set default PHP Code Sniffer standard to Yoast.

As dependency

To include standards as part of a project require them as development dependencies:

composer require --dev yoast/yoastcs:^2.0

Composer will automatically install dependencies and register the YoastCS and other external standards with PHP_CodeSniffer.

Tools provided via YoastCS

  • PHP Parallel Lint
  • PHP_CodeSniffer and select standards for PHP_CodeSniffer, including a number of Yoast native sniffs.

PHP Parallel Lint

PHP Parallel Lint is a tool to lint PHP files against parse errors.

PHP Parallel Lint does not use a configuration file, so command-line options need to be passed to configure what files to scan.

It is best practice within the Yoast projects, to add a script to the composer.json file which encapsules the command with the appropriate command-line options to ensure that running the tool will yield the same results each time.

Typically, (a variation on) the following snippet would be added to the composer.json file for a project:

    "scripts" : {
        "lint": [
            "@php ./vendor/php-parallel-lint/php-parallel-lint/parallel-lint . -e php --exclude vendor --exclude .git"
        ]
    }

PHP Code Sniffer

Set of PHP_CodeSniffer rules.

Severity levels:

  • error level issues are considered mandatory to fix in Yoast projects and enforced in continuous integration
  • warning level issues are considered recommended to fix

The YoastCS Standard

The Yoast standard for PHP_CodeSniffer is comprised of the following:

Files within version management and dependency related directories, such as the Composer vendor directory, are excluded from the scans by default.

Sniffs

To obtain a list of all sniffs used within YoastCS:

"vendor/bin/phpcs" -e --standard=Yoast

Sniff Documentation

Not all sniffs have documentation available about what they sniff for, but for those which do, this documentation can be viewed from the command-line:

"vendor/bin/phpcs" --standard=Yoast --generator=Text

Running the sniffs

Command line

"vendor/bin/phpcs" --extensions=php /path/to/folder/

For more command-line options, please have a read through the PHP_CodeSniffer documentation.

Yoast plugin repositories

All Yoast plugin repositories contain a [.]phpcs.xml.dist file which contains the repository specific configuration.

From the root of these repositories, you can run PHPCS by using:

composer check-cs

PhpStorm

Refer to Using PHP Code Sniffer Tool in the PhpStorm documentation.

After installation, the Yoast standard will be available as a choice in PHP Code Sniffer Validation inspection.

Changelog

The changelog for this package can be found in the CHANGELOG.md file.