README

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:

composer require --dev forrest79/phpcs

Forrest79 PHP Coding Standard requires PHP 8.0.

How to use it:

Create your CS XML and include this Forrest79CodingStandard:

<?xml version="1.0"?>
<ruleset name="MyOwnCS">
	<rule ref="./Forrest79CodingStandard/ruleset.xml"/>
</ruleset>

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

<?xml version="1.0"?>
<ruleset name="MyOwnCS">
	<rule ref="./Forrest79CodingStandard/ruleset-fully-qualified-global.xml"/>
</ruleset>

You can use it and ignore some rules.

<?xml version="1.0"?>
<ruleset name="MyOwnCS">
	<rule ref="./Forrest79CodingStandard/ruleset.xml">
		<exclude name="Forrest79CodingStandard.Exceptions.ExceptionDeclaration.NotChainable"/>
	</rule>
</ruleset>

Or just concrete files.

<rule ref="Forrest79CodingStandard.Exceptions.ExceptionDeclaration.NotChainable">
    <exclude-pattern>tests/Sniffs/TestCase.php</exclude-pattern>
</rule>

PSR-4 settings

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

<rule ref="SlevomatCodingStandard.Files.TypeNameMatchesFileName">
    <properties>
        <property name="rootNamespaces" type="array" value="
            apps/home/app/src=>Home\App,
            apps/home/tests/src=>Home\Tests,
            packages/internals/src=>Forrest79,
            tools/src=>Tools,
        "/>
    </properties>
</rule>

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:

<rule ref="Forrest79CodingStandard.Exceptions.ExceptionDeclaration">
    <properties>
        <property name="exceptionsDirectoryName" type="string" value="exceptions"/>
    </properties>
</rule>

Methods\MethodStructureSniff

Forrest79CodingStandard.Methods.MethodStructureSniff.AlphabeticalOrder

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

<rule ref="Forrest79CodingStandard.Methods.MethodStructure">
    <properties>
        <property name="checkFiles" type="array" value="
            apps/home/app/src/Configurator.php,
        "/>
    </properties>
</rule>

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.

General naming conventions

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

<?php

use Foo\IP\Bar;
use Foo\Php\Bar;
use Foo\UI\Bar;
use Foo\Xml\Bar;

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

use LogAware;
use LogFactory;
use LogLevel;
use LogStandard;
use LogableTrait;
use LoggerInterface;

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.

<?php declare(strict_types=1);

namespace Forrest79;

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

<?php

sprintf('%s/%s', $dir, $fileName);

// vs

$foo . $bar;

'SELECT `id`, `name` FROM `people`'
. 'WHERE `role` = 1'
. 'ORDER BY `name` ASC';

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

<?php

namespace Forrest79;

use Forrest79\Bar;
use Forrest79\Foo;

use DateTime;

use Lorem\Amet;
use Lorem\Ipsum\Dolor\Foo as DolorFoo;
use Lorem\Sit;

use ReflectionClass;
use ReflectionMethod;

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.

<?php

if (!is_int($foo)) {
	return (int) $foo;
}

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.

<?php

class Foo
{
	const FOO = 'foo';

	const VISIBILITY_PRIVATE = 'private';
	const VISIBILITY_PROTECTED = 'protected';
	const VISIBILITY_PUBLIC = 'public';

}

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

<?php

class X
{

	public function __construct(Foo $foo, string $string)
	{
		// ...
	}

}

Function declaration and call with arguments on multiple lines:
- There is only one argument per line.

<?php

class X
{

	public function __construct(
		Foo $foo,
		string $string,
	)
	{
		// ...
	}

}

new X(
	$foo,
	$string,
);

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

<?php

class X
{

	/**
	 * @param \Foo $a required type argument
	 * @param \Foo|null $b required argument, but nullable type needed
	 * @param string $c required scalar argument
	 * @param string|null $d required argument with nullable scalar
	 * @param string $e optional nullable scalar argument
	 * @param string|null $f optional nullable scalar argument
	 */
	public function __construct(
		Foo $a,
		Foo|null $b,
		string $c,
		string|null $d,
		string $e = '',
		string|null $f = null
	)
	{
		// ...
	}

}

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.

<?php

class X
{

	public function getFoo(): Foo
	{
		// ...
	}

}

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

<?php

class X
{

	public function process(Foo $foo): void
	{
		$foo->bar();
	}

}

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

<?php

class X
{

	public function process(Foo $foo): never
	{
		exit(1);
	}

}

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.

<?php

array_walk($foo, function (Item $item) use ($bar): string {
	// ...
});

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

<?php

class X
{

	final public static function foo(): void
	{
		// ...
	}


	abstract public static function bar(): void
	{
		// ...
	}

}

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

<?php

if ($foo) {
	// ...
}

if (
	$foo
	&& $bar
) {
	// ...
}

switch ($foo) {
	case 1:
	case 2:
		// ...
		break;
	default:
		// ...

}

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.

<?php

if (
	($lorem >= 3 && $lorem <= 5)
	|| $ipsum !== null
) {
	// ...
}

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

<?php

$lorem
	->ipsum()
	->dolor()
	->sit()
	->amet();

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

<?php

new Foo();

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.

<?php

function foo($foo, Closure $callback): void
{
	// ...
	$callback($bar);
	// ...
}

foo('foo', function (Bar $bar): void {
	// ...
});

<?php

function foo($foo, Closure $callback): void
{
	// ...
	$callback(...$barArray);
	// ...
}

foo('foo', function (Bar ...$bars): void {
	// ...
});

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.

<?php

namespace Forrest79\Foo;

use Forrest79;

class LoremException extends Forrest79\PhpException
{
	private strinf $lorem;


	public function __construct(string $lorem, \Throwable $previous = null)
	{
		parent::__construct(sprintf('%s ipsum dolor sit amet', $lorem), $previous);
		$this->lorem = $lorem;
	}


	public function getLorem(): string
	{
		return $this->lorem;
	}

}

##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:

<?php

/**
 * Short description - one line (optional)
 *
 * Long description (optional)
 *
 * Documentation annotations (optional)
 *
 * Code analysis annotations (optional)
 *
 * Application annotations (optional)
 *
 * @param string $foo only if some optional description is needed
 * @param int $bar only if some optional description is needed
 * @return bool only if some optional description is needed
 * @throws \MyException\BarException
 * @throws \MyException\FooException
 */
public function myMethod(string $foo, int $bar): bool;

Structure for properties and constants:

<?php

/**
 * Short description - one line (optional)
 *
 * Long description (optional)
 *
 * Documentation annotations (optional)
 *
 * Code analysis annotations (optional)
 *
 * Application annotations (optional)
 *
 * @var string optional description
 */
private $foo;

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.

/**
 * @ManyToMany(targetEntity="Phonenumber")
 * @JoinTable(
 *   name="users_phonenumbers",
 *   joinColumns={@JoinColumn(name="user_id", referencedColumnName="id")},
 *   inverseJoinColumns={@JoinColumn(name="phonenumber_id", referencedColumnName="id", unique=true)},
 * )
 * @Foo
 **/

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.

<?php

use DateTime;
use DateTimeImmutable;

/**
 * @param DateTimeImmutable $date calendar date
 * @param array<string> $events
 * @param int|null $interval
 * @return DateTime
 */
public function myMethod(DateTimeImmutable $date, array $events, int $interval = null): DateTime
{
	// ...
}

@param

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

<?php

use DateTime;

/**
 * @param string $foo optional description
 * @param int $bar optional description
 * @param DateTime ...$dates optional description
 */
public function myMethod(string $foo, int $bar, DateTime ...$dates)
{
	// ...
}

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

<?php

/** @var string optional description */
private $foo;

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.

<?php

/** @var Foo $foo optional description */
$foo = $container->getService('foo');

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

forrest79 / phpcs

Maintainers

Details

README

Installation

How to use it:

PSR-4 settings

Custom sniffs

Exceptions\ExceptionDeclarationSniff

Forrest79CodingStandard.Exceptions.ExceptionDeclarationSniff.NotEndingWithException

Forrest79CodingStandard.Exceptions.ExceptionDeclarationSniff.NotChainable

Forrest79CodingStandard.Exceptions.ExceptionDeclarationSniff.IncorrectExceptionDirectory

Methods\MethodStructureSniff

Forrest79CodingStandard.Methods.MethodStructureSniff.AlphabeticalOrder

NamingConventions\MethodStructureSniff

Forrest79CodingStandard.NamingConventions.ValidVariableNameSniff.NotCamelCaps

Nette\FinalInjectMethodSniff

Forrest79CodingStandard.Nette.FinalInjectMethodSniff.MissingFinal

Nette\ParentCallSniff

Forrest79CodingStandard.Nette.ParentCallSniff.MissingParent

Nette\PresenterMethodsSniff

Forrest79CodingStandard.Nette.PresenterMethodsSniff.NotProtected

General naming conventions

General formatting conventions

PHP files

Strings

Arrays

Namespaces

Types

Interfaces

Scalar types

Variables

Properties

Constants

Functions

Argument list

Return type

Anonymous functions

Methods

Control structures

Expressions

Closures and callables

Exceptions

PHPDoc

Annotation blocks

Short+long description

Documentation annotations

Code analysis annotations

Application annotations

Multi-line annotations

Allowed types for @param, @return, @var

Mixed

Array/collection

Type

@param

@return

@var

@throws

Constants