PHPCSExtra

🚧

• Introduction
• Minimum Requirements
• Installation
  • Composer Project-based Installation
  • Composer Global Installation
• Features
• Sniffs
  • NormalizedArrays
  • Universal
• Contributing
• License

Introduction

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

Minimum Requirements

• PHP 5.4 or higher.
• PHP_CodeSniffer version 3.7.0 or higher.
• PHPCSUtils version 1.0.0 or higher.

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.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.0"

Features

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

• The NormalizedArrays ruleset is a standard to check the formatting of array declarations.
• The Universal ruleset is NOT a standard, but a sniff collection. It should NOT be included in custom rulesets as a standard as it contains contradictory rules. Instead include individual sniffs from this standard in a custom project/company ruleset to use them.

Sniffs

Legend:

• 🔧 = Includes auto-fixer.
• 📊 = Includes metrics.
• 📚 = Includes CLI documentation.

NormalizedArrays

NormalizedArrays.Arrays.ArrayBraceSpacing 🔧 📊 📚

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

The sniff allows for having different settings for:

• Space between the array keyword and the open parenthesis for long arrays via the keywordSpacing property. Accepted values: (int) number of spaces or false to turn this check off. Defaults to 0 spaces.
• Spaces on the inside of the braces for empty arrays via the spacesWhenEmpty property. Accepted values: (string) newline, (int) number of spaces or false to turn this check off. Defaults to 0 spaces.
• Spaces on the inside of the braces for single-line arrays via the spacesSingleLine property; Accepted values: (int) number of spaces or false to turn this check off. Defaults to 0 spaces.
• Spaces on the inside of the braces for multi-line arrays via the spacesMultiLine property. Accepted values: (string) newline, (int) number of spaces or false to turn this check off. Defaults to newline.

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 🔧 📊 📚

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

By default, this sniff will:

• Forbid a comma after the last array item for single-line arrays.
• Enforce a comma after the last array item for multi-line arrays.

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 🔧 📚

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 📚

Detects duplicate array keys in array declarations.

Universal.Arrays.MixedArrayKeyTypes 📚

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

Universal.Arrays.MixedKeyedUnkeyedArray 📚

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

Universal.Constants.UppercaseMagicConstants 🔧 📊 📚

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

Universal.ControlStructures.DisallowAlternativeSyntax 🔧 📊 📚

Disallow using the alternative syntax for control structures.

• This sniff contains an allowWithInlineHTML property to allow alternative syntax when inline HTML is used within the control structure. In all other cases, the use of the alternative syntax will still be disallowed. Acceped values: (bool) true|false. Defaults to false.
• The sniff has modular error codes to allow for making exceptions based on specific control structures and/or specific control structures in combination with inline HTML. The error codes follow the following pattern: Found[ControlStructure][WithInlineHTML]. Examples: FoundIf, FoundSwitchWithInlineHTML.

Universal.ControlStructures.IfElseDeclaration 🔧 📊 📚

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

Universal.Lists.DisallowLongListSyntax 🔧 📊 📚

Disallow the use of long lists.

Universal.Lists.DisallowShortListSyntax 🔧 📊 📚

Disallow the use of short lists.

Universal.Namespaces.DisallowDeclarationWithoutName 📊 📚

Disallow namespace declarations without a namespace name.

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

Universal.Namespaces.DisallowCurlyBraceSyntax 📊 📚

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

Universal.Namespaces.EnforceCurlyBraceSyntax 📊 📚

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

Universal.Namespaces.OneDeclarationPerFile 📚

Disallow the use of multiple namespaces within a file.

Universal.OOStructures.AlphabeticExtendsImplements 🔧 📊 📚

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

• This sniff contains a orderby property to determine the sort order to use for the statement. If all names used are unqualified, the sort order won't make a difference. However, if one or more of the names are partially or fully qualified, the chosen sort order will determine how the sorting between unqualified, partially and fully qualified names is handled. The sniff supports two sort order options:
  • 'name' : sort by the interface name only (default);
  • 'full' : sort by the full name as used in the statement (without leading backslash). In both cases, the sorting will be done using natural sort, case-insensitive.
• The sniff has modular error codes to allow for selective inclusion/exclusion:
  • ImplementsWrongOrder - for "class implements" statements.
  • ImplementsWrongOrderWithComments - for "class implements" statements interlaced with comments. These will not be auto-fixed.
  • ExtendsWrongOrder - for "interface extends" statements.
  • ExtendsWrongOrderWithComments - for "interface extends" statements interlaced with comments. These will not be auto-fixed.
• When fixing, the existing spacing between the names in an implements/extends statement will not be maintained. The fixer will separate each name with a comma and one space. If alternative formatting is desired, a sniff which will check and fix the formatting should be added to the ruleset.

Universal.Operators.DisallowLogicalAndOr 📊 📚

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

ℹ️ 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 📊 📚

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 🔧 📊 📚

• Disallow the use of post-in/decrements in stand-alone statements - error codes: PostDecrementFound and PostIncrementFound. Using pre-in/decrement is more in line with the principle of least astonishment and prevents bugs when code gets moved around at a later point in time.
• Discourages the use of multiple increment/decrement operators in a stand-alone statement - error code: MultipleOperatorsFound.

Universal.Operators.StrictComparisons 🔧 📊 📚

Enforce the use of strict comparisons.

⚠️ 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.UseStatements.DisallowUseClass 📊 📚

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

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 📊 📚

Forbid using import use statements for constants.

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

Universal.UseStatements.DisallowUseFunction 📊 📚

Forbid using import use statements for functions.

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

Universal.UseStatements.LowercaseFunctionConst 🔧 📊 📚

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 🔧 📊 📚

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.WhiteSpace.DisallowInlineTabs 🔧 📚

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.

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). For more information, visit http://www.gnu.org/copyleft/lesser.html