Home

Awesome

PHPCSExtra

<div aria-hidden="true">

Latest Stable Version Release Date of the Latest Version :construction: Latest Unstable Version Last Commit to Unstable

CS Build Status Test Build Status Coverage Status

Minimum PHP Version Tested on PHP 5.4 to 8.3

License: LGPLv3 Awesome

</div>

Introduction

PHPCSExtra is a collection of sniffs and standards for use with PHP_CodeSniffer.

Minimum Requirements

Installation

Installing via Composer is highly recommended.

Composer will automatically install the project dependencies and register the rulesets from PHPCSExtra and other external standards with PHP_CodeSniffer using the Composer PHPCS plugin.

Composer Project-based Installation

Run the following from the root of your project:

composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
composer require --dev phpcsstandards/phpcsextra:"^1.2.0"

Composer Global Installation

Alternatively, you may want to install this standard globally:

composer global config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
composer global require --dev phpcsstandards/phpcsextra:"^1.2.0"

Updating to a newer version

If you installed PHPCSExtra using either of the above commands, you can update to a newer version as follows:

# Project local install
composer update phpcsstandards/phpcsextra --with-dependencies

# Global install
composer global update phpcsstandards/phpcsextra --with-dependencies

If your project includes require[-dev]s for the squizlabs/php_codesniffer, phpcsstandards/phpcsutils or dealerdirect/phpcodesniffer-composer-installer packages in its composer.json file, you may need to use --with-all-dependencies instead of --with-dependencies.

:bulb: Pro-tip: Unless your project is a PHPCS standard which actually uses any of these packages directly, it is recommended to remove these packages from your own composer.json file, in favour of letting PHPCSExtra (and potential other external PHPCS standards you use), manage the version requirements for these packages.

Features

Once this project is installed, you will see three new rulesets in the list of installed standards when you run vendor/bin/phpcs -i: Modernize, NormalizedArrays and Universal.

Sniffs

Legend:

Modernize

Modernize.FunctionCalls.Dirname :wrench: :books:

This sniff will detect and auto-fix two typical code modernizations which can be made related to the dirname() function:

  1. Since PHP 5.3, calls to dirname(__FILE__) can be replaced by __DIR__. Errorcode: Modernize.FunctionCalls.Dirname.FileConstant.
  2. Since PHP 7.0, nested function calls to dirname() can be changed to use the $levels parameter. Errorcode: Modernize.FunctionCalls.Dirname.Nested.

If a php_version configuration option has been passed to PHPCS using either --config-set or --runtime-set, it will be respected by the sniff. In effect, this means that the sniff will only report on modernizations which can be applied for the PHP version as configured.

NormalizedArrays

NormalizedArrays.Arrays.ArrayBraceSpacing :wrench: :bar_chart: :books:

Enforce consistent spacing for the open/close braces of array declarations.

The sniff allows for having different settings for:

Note: if any of the above properties are set to newline, it is recommended to also include an array indentation sniff. This sniff will not handle the indentation.

NormalizedArrays.Arrays.CommaAfterLast :wrench: :bar_chart: :books:

Enforce/forbid a comma after the last item in an array declaration.

By default, this sniff will:

This can be changed for each type or array individually by setting the singleLine and/or multiLine properties in a custom ruleset.

Use any of the following values to change the properties: enforce, forbid or skip to not check the comma after the last array item for a particular type of array.

The default for the singleLine property is forbid. The default for the multiLine property is enforce.

Universal

Universal.Arrays.DisallowShortArraySyntax :wrench: :bar_chart: :books:

Disallow short array syntax.

In contrast to the PHPCS native Generic.Arrays.DisallowShortArraySyntax sniff, this sniff will ignore short list syntax and not cause parse errors when the fixer is used.

Universal.Arrays.DuplicateArrayKey :books:

Detects duplicate array keys in array declarations.

The sniff will make a distinction between keys which will be duplicate in all PHP version and (numeric) keys which will only be a duplicate key in PHP < 8.0 or PHP >= 8.0.

If a php_version configuration option has been passed to PHPCS using either --config-set or --runtime-set, it will be respected by the sniff and only report duplicate keys for the configured PHP version.

Universal.Arrays.MixedArrayKeyTypes :books:

Best practice sniff: don't use a mix of integer and string keys for array items.

Universal.Arrays.MixedKeyedUnkeyedArray :books:

Best practice sniff: don't use a mix of keyed and unkeyed array items.

Universal.Classes.DisallowAnonClassParentheses :wrench: :bar_chart: :books:

Disallow the use of parentheses when declaring an anonymous class without passing parameters.

Universal.Classes.RequireAnonClassParentheses :wrench: :bar_chart: :books:

Require the use of parentheses when declaring an anonymous class, whether parameters are passed or not.

Universal.Classes.DisallowFinalClass :wrench: :bar_chart: :books:

Disallow classes being declared final.

Universal.Classes.RequireFinalClass :wrench: :bar_chart: :books:

Require all non-abstract classes to be declared final.

:warning: Warning: the auto-fixer for this sniff may have unintended side-effects for applications and should be used with care! This is considered a risky fixer.

Universal.Classes.ModifierKeywordOrder :wrench: :bar_chart: :books:

Require a consistent modifier keyword order for class declarations.

Universal.CodeAnalysis.ConstructorDestructorReturn :wrench: :books:

If a php_version configuration option has been passed to PHPCS using either --config-set or --runtime-set, it will be respected by the sniff. In effect, this means that the sniff will only report on PHP4-style constructors if the configured PHP version is less than 8.0.

Universal.CodeAnalysis.ForeachUniqueAssignment :wrench: :books:

Detects foreach control structures which use the same variable for both the key as well as the value assignment as this will lead to unexpected - and most likely unintended - behaviour.

Note: The fixer will maintain the existing behaviour of the code. This may not be the intended behaviour.

Universal.CodeAnalysis.NoDoubleNegative :wrench: :books:

Detects double negation !! in code, which is effectively the same as a boolean cast, but with a much higher cognitive load. Also detects triple negation !!!, which is effectively the same as a single negation.

The sniff has modular error codes to allow for disabling individual checks. The error codes are: FoundDouble, FoundDoubleWithInstanceof (not auto-fixable) and FoundTriple.

Universal.CodeAnalysis.NoEchoSprintf :wrench: :books:

Detects use of the inefficient echo [v]sprintf(...); combi. Use [v]printf() instead.

Universal.CodeAnalysis.StaticInFinalClass :wrench: :books:

Detects using static instead of self in OO constructs which are final.

Universal.Constants.LowercaseClassResolutionKeyword :wrench: :bar_chart: :books:

Enforce that the class keyword when used for class name resolution, i.e. ::class, is in lowercase.

Universal.Constants.ModifierKeywordOrder :wrench: :bar_chart: :books:

Require a consistent modifier keyword order for OO constant declarations.

Universal.Constants.UppercaseMagicConstants :wrench: :bar_chart: :books:

Enforce uppercase when using PHP native magic constants, like __FILE__ et al.

Universal.ControlStructures.DisallowAlternativeSyntax :wrench: :bar_chart: :books:

Disallow using the alternative syntax for control structures.

Universal.ControlStructures.DisallowLonelyIf :wrench: :books:

Disallow if statements as the only statement in an else block.

Note: This sniff will not fix the indentation of the "inner" code. It is strongly recommended to run this sniff together with the Generic.WhiteSpace.ScopeIndent sniff to get the correct indentation.

Universal.ControlStructures.IfElseDeclaration :wrench: :bar_chart: :books:

Verify that else(if) statements with braces are on a new line.

Universal.Files.SeparateFunctionsFromOO :bar_chart: :books:

Enforce for a file to either declare (global/namespaced) functions or declare OO structures, but not both.

Universal.FunctionDeclarations.NoLongClosures :bar_chart: :books:

Detects "long" closures and recommends using a named function instead.

The sniff is configurable by setting any of the following properties in a custom ruleset:

Universal.FunctionDeclarations.RequireFinalMethodsInTraits :wrench: :bar_chart: :books:

Enforce non-private, non-abstract methods in traits to be declared as final.

The available error codes are: NonFinalMethodFound and NonFinalMagicMethodFound.

Universal.Lists.DisallowLongListSyntax :wrench: :books:

Disallow the use of long lists.

For metrics about the use of long lists vs short lists, please use the Universal.Lists.DisallowShortListSyntax sniff.

Universal.Lists.DisallowShortListSyntax :wrench: :bar_chart: :books:

Disallow the use of short lists.

Universal.Namespaces.DisallowDeclarationWithoutName :bar_chart: :books:

Disallow namespace declarations without a namespace name.

This sniff only applies to namespace declarations using the curly brace syntax.

Universal.Namespaces.DisallowCurlyBraceSyntax :bar_chart: :books:

Disallow the use of the alternative namespace declaration syntax using curly braces.

Universal.Namespaces.EnforceCurlyBraceSyntax :bar_chart: :books:

Enforce the use of the alternative namespace syntax using curly braces.

Universal.Namespaces.OneDeclarationPerFile :books:

Disallow the use of multiple namespaces within a file.

Universal.NamingConventions.NoReservedKeywordParameterNames :books:

Disallow function parameters using reserved keywords as names, as this can quickly become confusing when people use them in function calls using named parameters

Universal.OOStructures.AlphabeticExtendsImplements :wrench: :bar_chart: :books:

Enforce that the names used in a class/enum "implements" statement or an interface "extends" statement are listed in alphabetic order.

Universal.Operators.ConcatPosition :wrench: :bar_chart: :books:

Enforce that the concatenation operator for multi-line concatenations is in a preferred position, either always at the start of the next line or always at the end of the previous line.

Universal.Operators.DisallowLogicalAndOr :bar_chart: :books:

Enforce the use of the boolean && and || operators instead of the logical and/or operators.

:information_source: Note: as the operator precedence of the logical operators is significantly lower than the operator precedence of boolean operators, this sniff does not contain an auto-fixer.

Universal.Operators.DisallowShortTernary :bar_chart: :books:

Disallow the use of short ternaries ?:.

While short ternaries are useful when used correctly, the principle of them is often misunderstood and they are more often than not used incorrectly, leading to hard to debug issues and/or PHP warnings/notices.

Universal.Operators.DisallowStandalonePostIncrementDecrement :wrench: :bar_chart: :books:

Universal.Operators.StrictComparisons :wrench: :bar_chart: :books:

Enforce the use of strict comparisons.

:warning: Warning: the auto-fixer for this sniff may cause bugs in applications and should be used with care! This is considered a risky fixer.

Universal.Operators.TypeSeparatorSpacing :wrench: :bar_chart: :books:

Enforce no spaces around the union type and intersection type operators.

The available error codes are: UnionTypeSpacesBefore, UnionTypeSpacesAfter, IntersectionTypeSpacesBefore, IntersectionTypeSpacesAfter.

Universal.PHP.LowercasePHPTag :wrench: :bar_chart: :books:

Enforces that the "PHP" in a PHP open tag is lowercase.

Universal.PHP.OneStatementInShortEchoTag :wrench: :books:

Disallow short open echo tags <?= containing more than one PHP statement.

Universal.UseStatements.DisallowMixedGroupUse :wrench: :bar_chart: :books:

Disallow group use statements which import a combination of namespace/OO construct, functions and/or constants in one statement.

Note: the fixer will use a semi-standardized format for group use statements. If there are more specific requirements for the formatting of group use statements, the ruleset configurator should ensure that additional sniffs are included in the ruleset to enforce the required format.

Universal.UseStatements.DisallowUseClass :bar_chart: :books:

Forbid using import use statements for classes/traits/interfaces/enums.

Individual sub-types - with/without alias, global imports, imports from the same namespace - can be forbidden by including that specific error code and/or allowed including the whole sniff and excluding specific error codes.

The available error codes are: FoundWithoutAlias, FoundWithAlias, FromGlobalNamespace, FromGlobalNamespaceWithAlias, FromSameNamespace and FromSameNamespaceWithAlias.

Universal.UseStatements.DisallowUseConst :bar_chart: :books:

Forbid using import use statements for constants.

See Universal.UseStatements.DisallowUseClass for information on the error codes.

Universal.UseStatements.DisallowUseFunction :bar_chart: :books:

Forbid using import use statements for functions.

See Universal.UseStatements.DisallowUseClass for information on the error codes.

Universal.UseStatements.KeywordSpacing :wrench: :bar_chart: :books:

Enforce the use of a single space after the use, function, const keywords and both before and after the as keyword in import use statements.

Companion sniff to the PHPCS native Generic.WhiteSpace.LanguageConstructSpacing sniff which doesn't cover the function, const and as keywords when used in an import use statement.

The sniff has modular error codes to allow for disabling individual checks. The error codes are: SpaceAfterUse, SpaceAfterFunction, SpaceAfterConst, SpaceBeforeAs and SpaceAfterAs.

Universal.UseStatements.LowercaseFunctionConst :wrench: :bar_chart: :books:

Enforce that function and const keywords when used in an import use statement are always lowercase.

Companion sniff to the PHPCS native Generic.PHP.LowerCaseKeyword sniff which doesn't cover these keywords when used in an import use statement.

Universal.UseStatements.NoLeadingBackslash :wrench: :bar_chart: :books:

Verify that a name being imported in an import use statement does not start with a leading backslash.

Names in import use statements should always be fully qualified, so a leading backslash is not needed and it is strongly recommended not to use one.

This sniff handles all types of import use statements supported by PHP, in contrast to other sniffs for the same in, for instance, the PHPCS native PSR12 or the Slevomat standard, which are incomplete.

Universal.UseStatements.NoUselessAliases :wrench: :books:

Detects useless aliases in import use statements.

Aliasing something to the same name as the original construct is considered useless (though allowed in PHP). Note: as OO and function names in PHP are case-insensitive, aliasing to the same name, using a different case is also considered useless.

Universal.WhiteSpace.AnonClassKeywordSpacing :wrench: :bar_chart: :books:

Standardize the amount of spacing between the class keyword and the open parenthesis (if any) for anonymous class declarations.

Universal.WhiteSpace.CommaSpacing :wrench: :bar_chart: :books:

Enforce that there is no space before a comma and exactly one space, or a new line, after a comma.

Additionally, the sniff also enforces that the comma should follow the code and not be placed after a trailing comment.

For the spacing part, the sniff makes the following exceptions:

  1. A comma preceded or followed by a parenthesis, curly or square bracket. These will not be flagged to prevent conflicts with sniffs handling spacing around braces.
  2. A comma preceded or followed by another comma, like for skipping items in a list assignment. These will not be flagged.

Universal.WhiteSpace.DisallowInlineTabs :wrench: :books:

Enforce using spaces for mid-line alignment.

While tab versus space based indentation is a question of preference, for mid-line alignment, spaces should always be preferred, as using tabs will result in inconsistent formatting depending on the dev-user's chosen tab width.

This sniff is especially useful for tab-indentation based standards which use the Generic.Whitespace.DisallowSpaceIndent sniff to enforce this.

DO make sure to set the PHPCS native tab-width configuration for the best results.

   <arg name="tab-width" value="4"/>

The PHPCS native Generic.Whitespace.DisallowTabIndent sniff (used for space-based standards) oversteps its reach and silently does mid-line tab to space replacements as well. However, the sister-sniff Generic.Whitespace.DisallowSpaceIndent leaves mid-line tabs/spaces alone. This sniff fills that gap.

Universal.WhiteSpace.PrecisionAlignment :wrench: :books:

Enforce code indentation to always be a multiple of a tabstop, i.e. disallow precision alignment.

Note:

The behaviour of the sniff is customizable via the following properties:

Contributing

Contributions to this project are welcome. Clone the repo, branch off from develop, make your changes, commit them and send in a pull request.

If unsure whether the changes you are proposing would be welcome, open an issue first to discuss your proposal.

License

This code is released under the GNU Lesser General Public License (LGPLv3).