Download the PHP package forrest79/phpcs without Composer

Forrest79 Coding Standard for PHP

Based on (no more developed) https://github.com/consistence/coding-standard and work of https://github.com/klapuch. Thanks!

Installation

The recommended way to install Forrest79 PHP Coding Standard is through Composer:

Forrest79 PHP Coding Standard requires PHP 8.0.

How to use it:

• Create your CS XML and include this Forrest79CodingStandard:

• Or you can use version with fully qualified global functions (\ prefix before global functions i.e. \is_array($x)) and constants (\ prefix before global constants i.e. \FILE_APPEND):

• You can use it and ignore some rules.

• Or just concrete files.

PSR-4 settings

• Recommend is to proper set PSR-4 via these settings:

  • key is directory, value is namespace

Custom sniffs

Exceptions\ExceptionDeclarationSniff

Forrest79CodingStandard.Exceptions.ExceptionDeclarationSniff.NotEndingWithException

Or exceptions should have Exception suffix.

Forrest79CodingStandard.Exceptions.ExceptionDeclarationSniff.NotChainable

Exceptions should be chainable, last constructor argument must be \Throwable.

Forrest79CodingStandard.Exceptions.ExceptionDeclarationSniff.IncorrectExceptionDirectory

All exceptions should be in Exceptions subdirectory. You can change subdirectory name via settings:

Methods\MethodStructureSniff

Forrest79CodingStandard.Methods.MethodStructureSniff.AlphabeticalOrder

Check if class has public methods in alphabetical order. Set files via settings:

NamingConventions\MethodStructureSniff

Forrest79CodingStandard.NamingConventions.ValidVariableNameSniff.NotCamelCaps

Check camel caps variable names.

Nette\FinalInjectMethodSniff

Forrest79CodingStandard.Nette.FinalInjectMethodSniff.MissingFinal

For Nette Framework. If some presenter or other object uses inject functionality, class should be final or inject methods should be final.

Nette\ParentCallSniff

Forrest79CodingStandard.Nette.ParentCallSniff.MissingParent

For Nette Framework. In presenters, all beforeRender methods should call their parent.

Nette\PresenterMethodsSniff

Forrest79CodingStandard.Nette.PresenterMethodsSniff.NotProtected

For Nette Framework. In presenters, all startup, beforeRender and createComponent methods should be protected.

PHP\CorrectCaseTypeSniff

Forrest79CodingStandard.PHP.CorrectCaseType

Checks that all PHP types are lowercase except NULL, TRUE and FALSE that must be uppercase. Based on Generic.PHP.LowerCaseTypeSniff.

General naming conventions

• Avoid abbreviations, use them only if long name would be less readable.
• For 2-letter shortcuts use UPPERCASE, for longer PascalCase.

General formatting conventions

• Tab indentation is used.
• Files end with a single blank line \n.
• Unix-style (LF) line endings \n are used.
• If there is a list of information, where ordering has no semantic meaning, the list is sorted alphabetically.
  • Sorting concatenated words (e.g. PascalCase) takes into account original words:

PHP files

• Contains only PHP code (no inline HTML etc.).
• File does not have the closing tag ?>.
• There are no characters (including BOM) before the PHP opening tag.
• Long opening tags are used (always <?php, never <?).
• There is one empty line after the line with the open tag.
• File either declares new symbols (classes, functions, constants, etc.) and causes no other side effects, or executes logic with side effects, but should not do both.
• Uses strict typing by enabling declare(strict_types = 1);.
  • This declaration is placed right behind the opening tag.
  • There is no space on each side of the = operator.

Strings

• Common strings are written using apostrophes ('). Only strings containing control characters (such as \n) may use double quotes (").
• For concatenation of mixed strings and variables sprintf() is used. If in-place strings are not needed concatenation is done with only concatenation operator (.).
  • . is surrounded by one space on each side, unless it is on the beginning of the line.
  • Strings do not contain variables ("Hello $name!").

Arrays

• Short array syntax is used ([, ]) instead of the array() language construct.

Namespaces

• Namespaces are written in PascalCase.
• Each file contains only one namespace declaration applied to the whole file.
  • Before the line with namespace there is one empty line.
• Types from other namespaces are imported with use.
  • use declarations are separated from namespace declaration with one empty line.
  • There is only one type imported per use declaration (one import per line).
  • use declarations are sorted alphabetically.
  • use declarations never begin with backslash (\).

Types

• Type names are written in PascalCase.
• Type names are nouns.
• Types are placed in namespaces (not global space).
• Opening brace and closing brace of type are always on a separate line.
• All parts of types are indented with one tab.
• Only one type per file is defined, name of this file has the same name as the type.
• Multiple types referenced in implements are separated with comma and one space and are ordered alphabetically.
• Types referenced in code are always referenced using Foo::class syntax, never using a string.
• If the referenced type in static access is the "current" one, self/static is used instead of type name.
• If type can be null, always use |NULL not ? - string|NULL instead of ?string.

Interfaces

• Interfaces are never prefixed with I.

Scalar types

• Short type names are used in code (int, bool). This also applies to PHP functions which offer both variants.

• float is always used instead of double or real. This also applies to PHP functions which offer both variants.

Variables

• Variable names are written in camelCase.
• global keyword is never used to declare global variables.

Properties

• All variables rules apply.
• All properties have explicitly declared visibility with private, protected or public.
• var is never used.
• Only one property is declared per statement.

Constants

• Constant names are written in UPPER_CASE.
• Constants are defined only inside classes using const, global constants are never defined.
• Constants have explicitly declared visibility with private, protected or public.
• If there are more constants, that "belong together", empty lines between them may be omitted.

Functions

• Function names are written in camelCase.
  • Calls to built-in PHP functions are exception to this rule and are written in snake_case.
• There is no space between the function name and the opening parenthesis.
• Opening brace and closing brace of type are always on separate line.
  • Exception: anonymous functions.
• Global functions are never declared, they should be defined inside a (static) class.
• Named functions (not anonymous) are never declared inside other functions.

Argument list

• There should be type hint defined whenever possible (including scalar type hints).
  • Nullable types (string|NULL) are used to allow passing null to a type hinted argument.
• There is no space after the opening parenthesis, and there is no space before the closing parenthesis.

• Arguments both in function declaration and in function call are separated with comma, followed by one space (,).

• Function declaration and call with arguments on multiple lines:

  • There is only one argument per line.

• Default argument values are used only when needed to either express optional argument (only at the end of the list) or to allow passing null to a type hinted argument.

  • Nullable types (string|NULL) are used to allow passing null to a type hinted argument and therefore default arguments are used only for optional arguments.
  • For scalar arguments default arguments are used only for optional arguments, not to allow passing nulls (see detailed example below).
• Variadic argument is written in this format: @param \Foo ...$foo.

Return type

• There should be type hint defined whenever possible (including scalar type hints).
  • Nullable types (string|NULL) are used to allow returning null.

• There is no space after the closing parenthesis, colon immediately follows and then there is one space between the colon and the type.

• When there is nothing to return, void return type must be specified.

• When method interrupt script, never return type must be specified.

Anonymous functions

• There is a space between the function keyword and the opening parenthesis.
• Opening brace is NOT placed on the next line.
• There is one space before and after the use keyword.

Methods

• All methods have explicitly declared visibility with private, protected or public.
• Order of keywords in declaration:
  1. final/abstract,
  2. private/protected/public,
  3. static
• Constructor is always defined with __construct name, never using the old PHP behavior - with name same as class name.
• There is one new line before and after each function (so two new lines between two functions).

Control structures

• Conditional statement is surrounded by parentheses.
  • There is no space after/before parentheses inside the statement.
  • There is one space before/after parentheses around the statement.
• Opening brace is placed on the same line as the conditional statement.
• else if is used instead of elseif.
• case statements in switch are indented with one tab, and their content on following lines again with another tab.

• case statements in switch end with a colon :.

• In switch, there must be a comment such as // no break when fall-through is intentional in a non-empty case body.
• Empty bodies of control structures are forbidden.
  • Exception is catch, but there must be a comment explaining situation.

Expressions

• After all operators, there is one space. Before operators, there is one space too, unless it is on the beginning of a line.
• Logical operators && and || are always used instead of and and or.
• All keywords are lowercase, exceptions are TRUE, FALSE and NULL.
• Strict comparisons are used by default (===), if there is need for ==, usually a comment should be given explaining situation.
  • Magic PHP type conversions should be avoided - WRONG: ($foo), CORRECT: ($foo !== NULL) - only expressions already containing boolean values should be written in ($foo) form.
  • The same applies for empty function, so it is forbidden.
• Yoda conditions should not be used.

• If expression needs to be written on multiple lines, operators belong on the beginning of the line.

• There is always only one statement per line.
• One blank line may be used to separate other statements.

• If there are multiple method calls in a row, and it is needed to write this on multiple lines, all the method calls are indented (including the first one).

• Parentheses in new statements should be always present, even if there are no arguments for constructor.

• There is one space after type cast and no space inside the parentheses.
  • (binary) and (unset) casts are forbidden.
• For increments and decrements respective operators ++/-- are used instead of "manual" addition/subtraction.
• All static symbols should be accessed only with ::, never using $this.
• echo, print, ... allowing both echo('...') and echo '' syntax are always used without parentheses and with one space after the keyword.

Closures and callables

• Closure is preferred to use instead of a callable (callable might be required while implementing a third party interface though).
• Closures are invoked using $closure() instead of using functions.
  • call_user_func should never be needed.
  • call_user_func_array is not needed since PHP 5.6 - argument unpacking was introduced.

Exceptions

• Type name always ends with Exception.
• Exceptions are placed in a separate directory called Exceptions.
• Class name describes the use-case and should be very specific.
• Inheritance is used for implementation purposes (not for creating hierarchies) - such as Forrest79\PhpException, where $code argument is skipped.
• Constructor requires only arguments, which are needed, the rest of the message is composed in the constructor.
  • All exceptions should support exceptions chaining (allow optional \Throwable as last argument).
  • Arguments should be stored in private properties and available via public methods, so that exception handling may use this data.

Commenting

• // inline style comments are used, never #.
• Inline comment has a space between // and the text.
• If there is no explicit need to write something, it should be omitted - well named classes, variables, methods and arguments should be preferred.
• "Commented out" code is never present.

PHPDoc

Structure for types and methods:

Structure for properties and constants:

Annotation blocks

• Different types of annotations are grouped together (separated from other blocks by an empty line).
• See structure above.

Short+long description

• Optional.
• If there is no explicit need to write something, it should be omitted - well named classes, variables, methods and arguments should be preferred.
• Descriptions which only rephrase method names (etc.) are never written.
• Clear code is better than long explanation.
• Short description has only one line (with no dot at the end).
• Long description may contain example usage.
• In long description formatting may be used (e.g. with HTML).

Documentation annotations

• Optional.
• PHPDoc's annotations with documentation metadata like @author, @copyright, @see, @link, ...

Code analysis annotations

• Are never user, use PHPCS-Ignores when needed.

Application annotations

• Optional.
• Annotations, that have functional significance for the application, such as Symfony, Doctrine and custom annotations.

Multi-line annotations

• Follows general formatting rules for dealing with separating statements to multiple lines.
• Two spaces are used for indentation.

Allowed types for @param, @return, @var

List of allowed types (long variants are used):

• int
• bool
• string
• float
• resource
• null
• object
• mixed
• array/collection (see below)
• type (see below)

Multiple different types are separated with |.

Mixed

• Used when nothing is known about the type.

Array/collection

• Written as array<int, type>, array<string, type> or list<type>.
• If the values are of more than one type, then array<int, mixed> is used (also if there is no knowledge about the types).
• If associative array is expected (or a Map), in description, there should be description of used format, such as array<string, string> $names format: lastName(string) => firstName (string).
• If there are more nested arrays/collections, this is expressed with more array<>, e.g. array<int, array<string, integer>> means array of arrays of integers.

Type

• FQN with a leading backslash.
• If the referenced type is the "current" one, self/static is used instead of type name.

@param

• Can be omitted when type hint is the same as annotation.
• Annotations are in the same order as defined in the argument list.

@return

• If there are no return statements in the method, @return is not present.
• Can be omitted when type hint is the same as annotation.

@var

• If the @var annotation is the only annotation and there is no long description in the PHPDoc, then one-line format is used:

• Inline @var is used to define types for variables, where the type is not clear.
  • Uses docblock comment /** ... */.
  • Type is defined first, followed by variable name.

@throws

• For implemented methods @throws is never used.
• @throws is only used in interfaces or abstract methods as part of the defining contract.
• @throws annotations are sorted alphabetically (according to the exception name).

Constants

• @var is not used for constants (type is defined by its value).
• If there is no need for other annotations or description, then PHPDoc is omitted.