zicht/standards-php

Contains the Zicht PHP coding standards, including phpcs ruleset

Zicht PHP standards

Roughly based on the PEAR and Zend coding standards, with inclusion of the PSR-1 and PSR-2 standards, the Zicht coding standard applies some custom rules and modifications to these standards:, _(*1)

• There are no required tags for file and class comments.
• Since we do no longer live in an era with fixed width consoles, the line length limit is fixed at 256, warning at 256, erroring at 512.
• Doc comment tags are compulsory for define() calls.
• Global function names are underscored_and_lowercased(), and method names are studlyCased.
• All constants, both global and class constants are UPPERCASED_AND_UNDERSCORED.
• Excessive whitespace is discouraged, i.e. more than two lines of whitespace and whitespace before the end of a scope (before a closing '}') causes warnings.
• Referring global namespaces in use statements is not allowed (must not begin with a backslash).
• Referring global namespaces for non-global classes (classes that do not reside in the global namespace, i.e. PHP core classes) is discouraged.

Usage

composer require --dev zicht/standards-php

Basic usage vendor/bin/phpcs --standard=vendor/zicht/standards-php/phpcs.xml <directories-and-files>, _(*2)

Projects should incorporate following commands in the scripts section of their composer.json. You should be using the composer lint command in your daily work to inspect code changes you made before submitting a pull request (you can also incorporate these checks into PhpStorm). You can use the composer lint-fix command to auto-fix errors that can be fixed automatically. Projects should implement the composer lint-no-warn command into their Q&A jobs that should be ran on newly submitted pull requests (this ignores warnings to prevent loads of warning messages in the logs while the test will still pass)., _(*3)

{
    "scripts": {
        "lint": [
            "phpcs --standard=vendor/zicht/standards-php/phpcs.xml src/ tests/"
        ],
        "lint-no-warn": [
            "phpcs -n --standard=vendor/zicht/standards-php/phpcs.xml src/ tests/"
        ],
        "lint-fix": [
            "phpcbf --standard=vendor/zicht/standards-php/phpcs.xml src/ tests/"
        ]
    }
}

Current ruleset

Generic

Generic.Files.LineLength

This rule is configured to give warnings on lines longer than 256 characters and give errors on lines longer than 512 characters (deliberately not following PSR-2). You should fix these warnings and stick to a maximum line length of 256 characters, but the Q&A tests should not fail on code having lines longer than 256 characters and less than 512 characters., _(*4)

Zicht Sniffs

In this section each of the rules from the Zicht set are explained., _(*5)

Commenting in general

All doc block comment sniffs (ClassComment, FileComment, FunctionComment and PropertyComment) will scan for empty doc blocks and doc blocks containing superfluous descriptions. Empty doc blocks and doc block containing only a superfluous comment (no tags) must be improved or removed. The description of doc blocks having a superfluous description and having tags must be improved or removed., _(*6)

Superfluous descriptions are detected by looking at the declaration the doc block belongs to and see if it is a repetition of its name, which obviously is not adding anything of value. Superfluous doc blocks/descriptions are auto-fixable., _(*7)

Example, all three doc block comments produce an error by the related sniff because the descriptions are superfluous:, _(*8)

<?php
/**
 * Class SomeExampleClass                   <-- Doc block must be improved or removed
 */
class SomeExampleClass
{
    /**
     * SomeClass constructor.               <-- Doc block must be improved or removed
     */
    public function __construct()
    {
        $this->setSomeValues([1, 2, 3]);
    }

    /**
     * Set some values                      <-- Description must be improved or removed
     *
     * @param int[] $someValues  Integer values to set
     */
    public function setSomeValues(array $someValues)
    {
        $this->someValues = $someValues;
    }
}

Zicht.Commenting.ClassComment

Extends PHP_CodeSniffer\Standards\PEAR\Sniffs\Commenting\ClassCommentSniff. Additionally detects empty or superfluous comments (see Commenting in general) and adds rules about what the doc block is allowed to contain in a class doc comment., _(*9)

• @category, @package, @subpackage, @author and @copyright tags are not allowed in class doc comments.
• @version tag in doc is not required but only one is allowed. Follows @license.
• @link tag in doc is not required but one or more is allowed.
• @see tag in doc is not required but one or more is allowed. Follows @link.
• @deprecated tag in doc is not required but only one is allowed. Follows @see (if used) or @version (if used).

Zicht.Commenting.DefineComment

Looks for comments before the define function of PHP., _(*10)

Zicht.Commenting.FileComment

Extends PHP_CodeSniffer\Standards\PEAR\Sniffs\Commenting\FileCommentSniff. Additionally detects empty or superfluous comments (see Commenting in general) and adds rules about what the doc block is allowed to contain in a file doc comment., _(*11)

• @category, @package, @subpackage and @author tags are not allowed in file doc comments.
• @copyright tag in doc is not required but one or more is allowed.
• @version tag in doc is not required but only one is allowed. Follows @license.
• @link tag in doc is not required but one or more is allowed.
• @see tag in doc is not required but one or more is allowed. Follows @link.
• @deprecated tag in doc is not required but only one is allowed. Follows @see (if used) or @version (if used) or @copyright (if used).

Zicht.Commenting.FunctionComment

Extends \PHP_CodeSniffer\Standards\PEAR\Sniffs\Commenting\FunctionCommentSniff. Additionally detects empty or superfluous comments (see Commenting in general) and detects {@inheritdoc} in the function comment which makes it skip params and return tags validation (if no @param or @return is added additionally). Also this sniff allows skipping a function comment when there are no parameters and returned values or when all parameters and the returned value have their type declared (type hinted):, _(*12)

public function getMeSomeArray(int $id, SomeObject $someObject = null): array
{
    return [];
}

No function doc comment is needed in above example., _(*13)

Zicht.Commenting.PropertyComment

This sniffs checks for required property comment tags (@var), their (required) content and the order of tags (@var tag must always come first and official PHPDoc tags must be placed above other custom tags. Empty lines are not allowed within the property comment and a separate description is not allowed and must be placed with the @var tag. The sniff also detects for superfluous descriptions (see Commenting in general). Single line property comments (/** @var <type> */) are allowed., _(*14)

Zicht.ControlStructures.ControlSignature

Checks if certain structures are formed according to the definition of the signature., _(*15)

do {EOL...} while (...);EOL, while (...) {EOL, for (...) {EOL, if (...) {EOL, foreach (...) {EOL, } else if (...) {EOL, } elseif (...) {EOL, } else {EOL, do {EOL,, _(*16)

for example do {EOL...} while (...);EOL means: do {// (EOL) End of line from here } while ();// (EOL) End of line from here., _(*17)

Zicht.ControlStructures.DisallowAssignments

Detects if there are any assignments happening in if, elseif, while, foreach and switch control structures. By default configuration a maximum of 1 assignment is allowed and it must come first before any other logic in the statement:, _(*18)

    if ($result = someDataRetrieval() && isset($result['success']) && true === $result['success'])

Zicht.Functions.FunctionCallSignature

This sniff overrides the PEAR Sniff to allow function call opening parenthesis and array square brackets on the same line. It is only allowing this if there's only one argument, which should be an array or could be a closure., _(*19)

Zicht.Methods.FunctionOpeningBrace

Detects if there are no empty lines between a function's opening brace and the first line of code., _(*20)

Zicht.NamingConventions.Classname

This sniff requires class names to be CamelCased., _(*21)

Zicht.NamingConventions.Constants

This sniff requires a constant name to be UPPERCASE (no lower case characters allowed) and no characters other than A-Z, 0-9 and underscore., _(*22)

Zicht.NamingConventions.Functions

This sniff defines the naming conventions., _(*23)

Class methods are required to be studlyCased or alternatively named lowerCamelCased. The following methods are allowed: construct, get, set, call, callStatic, invoke, destruct, toString, clone, invoke, invokeStatic. Underscore and numbers are discouraged to be used in method names in classes. A number creates a warning whereas an underscore creates an error., _(*24)

Global functions are required to be snake_cased so all lower an divided by a underscore., _(*25)

Zicht.PHP.Namespace

Except for global classes all other classes in namespaces are not allowed to be used in code referring to the fully qualified class name. Like $sniff = new \Zicht\Sniffs\PHP\NamespaceSniff()) use an use statement and format your code like $sniff = new NamespaceSniff();, _(*26)

Zicht.PHP.UseStatement

This sniff defines that the use statements should be at the top of in a PHP file and can only be preceded by a declare statement, doc blocks or the namespace declaration (and surely whitespaces etc)., _(*27)

Zicht.Whitespace.ExcessiveWhitespace

This sniff looks for more then one whitespace after the last } in a file., _(*28)

Other rules

To view the rules in this ruleset you can use the following command from the package root:, _(*29)

vendor/bin/phpcs --standard=Zicht -e

That will produce the following set:, _(*30)

   The Zicht standard contains 67 sniffs

   Generic (15 sniffs)
   -------------------
     Generic.Arrays.DisallowLongArraySyntax
     Generic.ControlStructures.InlineControlStructure
     Generic.Files.ByteOrderMark
     Generic.Files.LineEndings
     Generic.Files.LineLength
     Generic.Formatting.DisallowMultipleStatements
     Generic.Formatting.NoSpaceAfterCast
     Generic.Formatting.SpaceAfterCast
     Generic.Functions.FunctionCallArgumentSpacing
     Generic.Functions.OpeningFunctionBraceBsdAllman
     Generic.NamingConventions.UpperCaseConstantName
     Generic.PHP.DisallowShortOpenTag
     Generic.PHP.LowerCaseConstant
     Generic.PHP.LowerCaseKeyword
     Generic.WhiteSpace.DisallowTabIndent

   PEAR (3 sniffs)
   ---------------
     PEAR.ControlStructures.ControlSignature
     PEAR.Functions.ValidDefaultValue
     PEAR.WhiteSpace.ScopeClosingBrace

   PSR1 (3 sniffs)
   ---------------
     PSR1.Classes.ClassDeclaration
     PSR1.Files.SideEffects
     PSR1.Methods.CamelCapsMethodName

   PSR12 (1 sniff)
   ----------------
     PSR12.Operators.OperatorSpacing

   PSR2 (12 sniffs)
   ----------------
     PSR2.Classes.ClassDeclaration
     PSR2.Classes.PropertyDeclaration
     PSR2.ControlStructures.ControlStructureSpacing
     PSR2.ControlStructures.ElseIfDeclaration
     PSR2.ControlStructures.SwitchDeclaration
     PSR2.Files.ClosingTag
     PSR2.Files.EndFileNewline
     PSR2.Methods.FunctionCallSignature
     PSR2.Methods.FunctionClosingBrace
     PSR2.Methods.MethodDeclaration
     PSR2.Namespaces.NamespaceDeclaration
     PSR2.Namespaces.UseDeclaration

   Squiz (16 sniffs)
   -----------------
     Squiz.Arrays.ArrayDeclaration
     Squiz.Classes.ValidClassName
     Squiz.ControlStructures.ControlSignature
     Squiz.ControlStructures.ForEachLoopDeclaration
     Squiz.ControlStructures.ForLoopDeclaration
     Squiz.ControlStructures.LowercaseDeclaration
     Squiz.Functions.FunctionDeclaration
     Squiz.Functions.FunctionDeclarationArgumentSpacing
     Squiz.Functions.LowercaseFunctionKeywords
     Squiz.Functions.MultiLineFunctionDeclaration
     Squiz.Scope.MethodScope
     Squiz.Strings.DoubleQuoteUsage
     Squiz.WhiteSpace.ControlStructureSpacing
     Squiz.WhiteSpace.ScopeClosingBrace
     Squiz.WhiteSpace.ScopeKeywordSpacing
     Squiz.WhiteSpace.SuperfluousWhitespace

   Zend (2 sniffs)
   ---------------
     Zend.Debug.CodeAnalyzer
     Zend.Files.ClosingTag

   Zicht (15 sniffs)
   -----------------
     Zicht.Commenting.ClassComment
     Zicht.Commenting.DefineComment
     Zicht.Commenting.FileComment
     Zicht.Commenting.FunctionComment
     Zicht.Commenting.PropertyComment
     Zicht.ControlStructures.ControlSignature
     Zicht.Functions.FunctionCallSignature
     Zicht.Methods.FunctionOpeningBrace
     Zicht.NamingConventions.Classname
     Zicht.NamingConventions.Constants
     Zicht.NamingConventions.Functions
     Zicht.PHP.DisallowMultipleAssignmentsInIfStatements
     Zicht.PHP.Namespace
     Zicht.PHP.UseStatement
     Zicht.Whitespace.ExcessiveWhitespace

These namespaces of rules are applied as you could see above. Check the documentation of these namespaces for explanation., _(*31)

• Generic
• PEAR
• PSR1
• PSR2
• Squiz
• Zend
• Zicht

Maintainers

• Boudewijn Schoon boudewijn@zicht.nl
• Erik Trapman erik@zicht.nl
• Jochem Klaver jochem@zicht.nl