Download the PHP package zicht/standards-php without Composer

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:

• 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

Basic usage vendor/bin/phpcs --standard=vendor/zicht/standards-php/phpcs.xml <directories-and-files>

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).

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.

Zicht Sniffs

In this section each of the rules from the Zicht set are explained.

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.

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.

Example, all three doc block comments produce an error by the related sniff because the descriptions are superfluous:

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.

• @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.

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.

• @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):

No function doc comment is needed in above example.

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.

Zicht.ControlStructures.ControlSignature

Checks if certain structures are formed according to the definition of the signature.

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

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

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:

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.

Zicht.Methods.FunctionOpeningBrace

Detects if there are no empty lines between a function's opening brace and the first line of code.

Zicht.NamingConventions.Classname

This sniff requires class names to be CamelCased.

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.

Zicht.NamingConventions.Functions

This sniff defines the naming conventions.

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.

Global functions are required to be snake_cased so all lower an divided by a underscore.

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();

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).

Zicht.Whitespace.ExcessiveWhitespace

This sniff looks for more then one whitespace after the last } in a file.

Other rules

To view the rules in this ruleset you can use the following command from the package root:

That will produce the following set:

These namespaces of rules are applied as you could see above. Check the documentation of these namespaces for explanation.

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

Maintainers

• Boudewijn Schoon [email protected]
• Erik Trapman [email protected]
• Jochem Klaver [email protected]