==========================
PSR-12 Coding Style Guide
==========================
.. Note::
| The PSR1, PSR2 and PSR12 Coding Standards are provided by FIG under a MIT license.
| See license details: http://www.php-fig.org/bylaws/licensing-policies/
| The original content of this page can be found at `php-fig `__
-----------
1. Overview
-----------
This specification extends, expands and replaces `PSR-2 `__,
the coding style guide and requires adherence to `PSR-1 `__,
the basic coding standard.
Like PSR-2, the intent of this specification is to reduce cognitive friction when scanning code from different authors.
It does so by enumerating a shared set of rules and expectations about how to format PHP code.
This PSR seeks to provide a set way that coding style tools can implement,
projects can declare adherence to and developers can easily relate to between different projects.
When various authors collaborate across multiple projects, it helps to have one set of guidelines to be used among all those projects.
Thus, the benefit of this guide is not in the rules themselves but the sharing of those rules.
PSR-2 was accepted in 2012 and since then a number of changes have been made to PHP which has implications for coding style guidelines.
Whilst PSR-2 is very comprehensive of PHP functionality that existed at the time of writing, new functionality is very open to interpretation.
This PSR, therefore, seeks to clarify the content of PSR-2 in a more modern context with new functionality available, and make the errata to PSR-2 binding.
Previous language versions
-------------------------------
Throughout this document, any instructions MAY be ignored if they do not exist in versions of PHP supported by your project.
Example
-------------------------------
This example encompasses some of the rules below as a quick overview:
.. code-block:: php
$b) {
$foo->bar($arg1);
} else {
BazClass::bar($arg2, $arg3);
}
}
final public static function bar()
{
// method body
}
}
----------
2. General
----------
2.1 Basic Coding Standard
-------------------------
Code MUST follow all rules outlined in PSR-1.
The term 'StudlyCaps' in PSR-1 MUST be interpreted as PascalCase where the first letter of
each word is capitalized including the very first letter.
2.2 Files
---------
All PHP files MUST use the Unix LF (linefeed) line ending.
All PHP files MUST end with a single blank line.
The closing ``?>`` tag MUST be omitted from files containing only PHP.
2.3 Lines
---------
There MUST NOT be a hard limit on line length.
The soft limit on line length MUST be 120 characters.
Lines SHOULD NOT be longer than 80 characters; lines longer than that SHOULD
be split into multiple subsequent lines of no more than 80 characters each.
There MUST NOT be trailing whitespace at the end of lines.
Blank lines MAY be added to improve readability and to indicate related
blocks of code except where explicitly forbidden.
There MUST NOT be more than one statement per line.
2.4 Indenting
--------------
Code MUST use an indent of 4 spaces for each indent level, and MUST NOT use
tabs for indenting.
2.5 Keywords and Types
-------------------------
All PHP reserved `keywords `__ and `types `__ MUST be in lower case.
Any new types and keywords added to future PHP versions MUST be in lower case.
Short form of type keywords MUST be used i.e. `bool` instead of `boolean`,
`int` instead of `integer` etc.
---------------------------------------------------------------
3. Declare Statements, Namespace, and Import Statements
---------------------------------------------------------------
The header of a PHP file may consist of a number of different blocks. If present,
each of the blocks below MUST be separated by a single blank line, and MUST NOT contain
a blank line. Each block MUST be in the order listed below, although blocks that are
not relevant may be omitted.
* Opening :code:`
Declare statements MUST contain no spaces and MUST be exactly `declare(strict_types=1)`
(with an optional semi-colon terminator).
Block declare statements are allowed and MUST be formatted as below. Note position of
braces and spacing:
.. code-block:: php
declare(ticks=1) {
// some code
}
-----------------------------------
4. Classes, Properties, and Methods
-----------------------------------
The term "class" refers to all classes, interfaces, and traits.
Any closing brace MUST NOT be followed by any comment or statement on the
same line.
When instantiating a new class, parentheses MUST always be present even when
there are no arguments passed to the constructor.
.. code-block:: php
new Foo();
4.1 Extends and Implements
---------------------------
The `extends` and `implements` keywords MUST be declared on the same line as
the class name.
The opening brace for the class MUST go on its own line; the closing brace
for the class MUST go on the next line after the body.
Opening braces MUST be on their own line and MUST NOT be preceded or followed
by a blank line.
Closing braces MUST be on their own line and MUST NOT be preceded by a blank
line.
.. code-block:: php
bar($arg1);
Foo::bar($arg2, $arg3);
Argument lists MAY be split across multiple lines, where each subsequent line
is indented once. When doing so, the first item in the list MUST be on the
next line, and there MUST be only one argument per line. A single argument being
split across multiple lines (as might be the case with an anonymous function or
array) does not constitute splitting the argument list itself.
.. code-block:: php
bar(
$longArgument,
$longerArgument,
$muchLongerArgument
);
.. code-block:: php
get('/hello/{name}', function ($name) use ($app) {
return 'Hello ' . $app->escape($name);
});
-----------------------------------
5. Control Structures
-----------------------------------
The general style rules for control structures are as follows:
- There MUST be one space after the control structure keyword
- There MUST NOT be a space after the opening parenthesis
- There MUST NOT be a space before the closing parenthesis
- There MUST be one space between the closing parenthesis and the opening
brace
- The structure body MUST be indented once
- The body MUST be on the next line after the opening brace
- The closing brace MUST be on the next line after the body
The body of each structure MUST be enclosed by braces. This standardizes how
the structures look and reduces the likelihood of introducing errors as new
lines get added to the body.
5.1 `if`, `elseif`, `else`
-----------------------------------
An `if` structure looks like the following. Note the placement of parentheses,
spaces, and braces; and that `else` and `elseif` are on the same line as the
closing brace from the earlier body.
.. code-block:: php
$value) {
// foreach body
}
5.6 `try`, `catch`, `finally`
-----------------------------------
A `try-catch-finally` block looks like the following. Note the placement of
parentheses, spaces, and braces.
.. code-block:: php
$b) {
$foo = $a + $b * $c;
}
6.3. Ternary operators
-----------------------------------
The conditional operator, also known simply as the ternary operator, MUST be
preceded and followed by at least one space around both the `?`
and `:` characters:
.. code-block:: php
$variable = $foo ? 'foo' : 'bar';
When the middle operand of the conditional operator is omitted, the operator
MUST follow the same style rules as other binary [comparison][] operators:
.. code-block:: php
$variable = $foo ?: 'bar';
-----------------------------------
7. Closures
-----------------------------------
Closures MUST be declared with a space after the `function` keyword, and a
space before and after the `use` keyword.
The opening brace MUST go on the same line, and the closing brace MUST go on
the next line following the body.
There MUST NOT be a space after the opening parenthesis of the argument list
or variable list, and there MUST NOT be a space before the closing parenthesis
of the argument list or variable list.
In the argument list and variable list, there MUST NOT be a space before each
comma, and there MUST be one space after each comma.
Closure arguments with default values MUST go at the end of the argument
list.
If a return type is present, it MUST follow the same rules as with normal
functions and methods; if the `use` keyword is present, the colon MUST follow
the `use` list closing parentheses with no spaces between the two characters.
A closure declaration looks like the following. Note the placement of
parentheses, commas, spaces, and braces:
.. code-block:: php
bar(
$arg1,
function ($arg2) use ($var1) {
// body
},
$arg3
);
-----------------------------------
8. Anonymous Classes
-----------------------------------
Anonymous Classes MUST follow the same guidelines and principles as closures
in the above section.
.. code-block:: php