yoast / yoastcs
PHP_CodeSniffer rules for Yoast projects
Installs: 793 309
Dependents: 30
Suggesters: 0
Security: 0
Stars: 21
Watchers: 17
Forks: 3
Open Issues: 16
Type:phpcodesniffer-standard
Requires
- php: >=7.2
- ext-tokenizer: *
- automattic/vipwpcs: ^3.0.0
- php-parallel-lint/php-console-highlighter: ^1.0.0
- php-parallel-lint/php-parallel-lint: ^1.4.0
- phpcompatibility/phpcompatibility-wp: ^2.1.4
- phpcsstandards/phpcsextra: ^1.2.1
- phpcsstandards/phpcsutils: ^1.0.10
- sirbrillig/phpcs-variable-analysis: ^2.11.17
- slevomat/coding-standard: ^8.15.0
- squizlabs/php_codesniffer: ^3.9.1
- wp-coding-standards/wpcs: ^3.1.0
Requires (Dev)
- phpcompatibility/php-compatibility: ^9.3.5
- phpcsstandards/phpcsdevtools: ^1.2.1
- phpunit/phpunit: ^8.0 || ^9.0
- roave/security-advisories: dev-master
- dev-develop
- 3.1.0
- 3.0.0
- 2.3.1
- 2.3.0
- 2.2.1
- 2.2.0
- 2.1.0
- 2.0.2
- 2.0.1
- 2.0.0
- 1.3.0
- 1.2.2
- 1.2.1
- 1.2.0
- 1.1.0
- 1.0
- 0.5
- 0.4.3
- 0.4.2
- 0.4.1
- 0.4
- 0.3
- 0.2
- 0.1
- dev-JRF/ghactions-add-actionlint
- dev-main
- dev-TEMP/docs-validation-test
- dev-WIP/yoastcs-vendor
- dev-WIP/new-modern-class-refs-sniff
- dev-74-introduce-required-parameters-sniff
This package is auto-updated.
Last update: 2024-12-21 15:00:55 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 global config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true composer global require --dev yoast/yoastcs:"^3.0"
As dependency
To include standards as part of a project require them as development dependencies:
composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true composer require --dev yoast/yoastcs:"^3.0"
Composer will automatically install dependencies and register 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 --show-deprecated --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:
- The
WordPress
ruleset from the WordPress Coding Standards implementing the official WordPress PHP Coding Standards, with some select exclusions. - The
PHPCompatibilityWP
ruleset which checks code for PHP cross-version compatibility while preventing false positives for functionality polyfilled within WordPress. - The
VariableAnalysis
ruleset. - Select additional sniffs taken from
PHP_CodeSniffer
. - Select additional sniffs taken from
PHPCSExtra
. - Select additional sniffs taken from
SlevomatCodingStandard
. - Select additional sniffs taken from WordPress VIP Coding Standards.
- A number of custom Yoast specific sniffs.
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-warnings
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.
The YoastCS "Threshold" report
The YoastCS package includes a custom YoastCS\Yoast\Reports\Threshold
report for PHP_CodeSniffer to compare the current PHPCS run results with predefined "threshold" settings.
The report will look in the runtime environment for the following two environment variables and will take the values of those as the thresholds to compare the PHPCS run results against:
YOASTCS_THRESHOLD_ERRORS
YOASTCS_THRESHOLD_WARNINGS
If the environment variables are not set, they will default to 0 for both, i.e. no errors or warnings allowed.
The report will not print any details about the issues found, it just shows a summary based on the thresholds:
PHP CODE SNIFFER THRESHOLD COMPARISON
------------------------------------------------------------------------------------------------------------------------
Coding standards ERRORS: 148/130.
Coding standards WARNINGS: 539/539.
Please fix any errors introduced in your code and run PHPCS again to verify.
Please fix any warnings introduced in your code and run PHPCS again to verify.
After the report has run, a global YOASTCS_ABOVE_THRESHOLD
constant (boolean) will be available which can be used in calling scripts.
To use this report, run PHPCS with the following command-line argument: --report=YoastCS\Yoast\Reports\Threshold
.
Note: depending on the OS the command is run on, the backslashes in the report name may need to be escaped (doubled).
For those Yoast plugin repositories which use thresholds, the status can be checked locally by running:
composer check-cs-thresholds
Changelog
The changelog for this package can be found in the CHANGELOG.md file.