This repository has been archived and renamed, moved to iO PHP_CodeSniffer Standard. Feature sniffs and changes will be processed in the iO repository.
To replace isaac/php-code-sniffer-standard
by iodigital-com/php-code-sniffer-standard
, execute the following steps:
-
Remove
isaac/php-code-sniffer-standard
fromcomposer.json
:composer remove --dev --no-update isaac/php-code-sniffer-standard
-
Install
iodigital-com/php-code-sniffer-standard
:composer require --dev iodigital-com/php-code-sniffer-standard
Note: if you are not on the latest version, you might want to include a version constraint while requiring the new package.
-
In your project's
phpcs.xml
, replace<rule ref="ISAAC"/>
by<rule ref="IO"/>
. -
Replace any references to specific ISAAC sniffs in
phpcs.xml
and PHP files by references to the IO sniffs. This can be done by searching for the sniff names in the entire project and replace them with the new sniff names:Search for Replace by ISAAC.Classes.MethodPerClassLimit IO.Classes.MethodPerClassLimit ISAAC.Classes.PropertyPerClassLimit IO.Classes.PropertyPerClassLimit ISAAC.ControlStructures.DisallowGotoOperator IO.ControlStructures.DisallowGotoOperator ISAAC.ControlStructures.DisallowNullCoalesceOperator IO.ControlStructures.DisallowNullCoalesceOperator ISAAC.Namespaces.MultipleLinesPerUse IO.Namespaces.MultipleLinesPerUse
Verify that PHP_CodeSniffer still works correctly by executing:
vendor/bin/phpcs
Extending the default PHP_CodeSniffer with ISAAC rules
Note: Adding new phpcs-rules to this package must result in a major version update!
Require the package:
composer require --dev isaac/php-code-sniffer-standard
Create a phpcs.xml
-file in the root of your project, and include the default ISAAC ruleset:
<?xml version="1.0" encoding="UTF-8"?>
<ruleset name="phpcs-isaac">
<!-- include root folder of project -->
<file>.</file>
<!-- exclude paths -->
<exclude-pattern>./src/Migrations</exclude-pattern>
<exclude-pattern>./vendor</exclude-pattern>
<!-- include all rules in isaac ruleset -->
<rule ref="ISAAC"/>
</ruleset>
Change the name of the ruleset, modify the excluded paths and/or include custom rulesets for your project.
To get the most out of the PHPCompatibility standard, you should specify a testVersion to check against.
That will enable the checks for both deprecated/removed PHP features as well as the detection of code using new PHP features.
Include the testVersion by adding a config rule in your phpcs.xml
. Examples:
<config name="testVersion" value="7.0"/> <!-- check for compatability with php 7.0 -->
<config name="testVersion" value="7.1-"/> <!-- check for 7.1 and higher -->
<config name="testVersion" value="7.0-7.2"/> <!-- check within range 7.0 to 7.2 -->
Look here for more information: https://github.com/PHPCompatibility/PHPCompatibility#using-a-custom-ruleset
Since you now have a phpcs.xml
file in the root of your project, you can run the default phpcs-command: vendor/bin/phpcs
.
Sometimes a violation of a sniff cannot be resolved. In this case, the violation should be ignored using the phpcs:ignore
and phpcs:disable
/ phpcs:enable
annotations.
In order to do this, please take the following approach:
- Ignore only the parts of the file that cause the violation, not the file itself. If it is really the case the file should be ignored, you can use the
phpcs:ignoreFile
annotation or, better, add an<exclude-pattern>
to theruleset.xml
of the project. - Prefer
phpcs:ignore
overphpcs:disable
andphpcs:enable
, i.e. usephpcs:ignore
when this is possible and when the placement of thephpcs:ignore
does not introduce any other sniff violations, usephpcs:disable
andphpcs:enable
otherwise. Rationale: usingphpcs:disable
andphpcs:enable
might disable more code than initially intended when adding new code or moving existing code, for instance when refactoring code. - Always indicate the exact sniff or sniffs that are going to be ignored, use the complete sniff name, not only the sniff group. So for instance use
phpcs:ignore Squiz.WhiteSpace.FunctionSpacing.BeforeFirst, Squiz.WhiteSpace.FunctionSpacing.AfterLast
instead ofphpcs:ignore Squiz.WhiteSpace.FunctionSpacing
orphpcs:ignore
without any arguments. - Prefer placing the
phpcs:ignore
annotation on a separate line before the violation over placing it on the line of the violation itself. Rationale: when ignoring multiple sniffs, thephpcs:ignore
annotation can quickly exceed the line length limit; this is not checked when thephpcs:ignore
annotation is placed on a separate line before the violation, but it is checked when thephpcs:ignore
annotation is placed on the line of the violation itself. - Add an explanation why the sniff is ignored using
--
followed by a short explanation.
Example:
try {
$this->logger->log(LogLevel::INFO, new DateTimeImmutable());
//phpcs:ignore Generic.CodeAnalysis.EmptyStatement.DetectedCatch -- DateTimeImmutable creation cannot fail in this case
} catch (Exception $exception) {
}
If you want to to contribute, create a merge request with one sniff per merge request. Please provide an example in the description of what the sniff is about with a good and bad code snippet.