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.