========================
PSR-2 Coding Style Guide
========================
.. Note::
| The PSR1 and PSR2 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 `__
This guide extends and expands on
`PSR-1 `__,
the basic coding standard.
The intent of this guide 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.
The style rules herein are derived from commonalities among the various member
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 in the sharing of those rules.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in `RFC
2119 `__.
-----------
1. Overview
-----------
- Code MUST follow a "coding style guide" PSR
[`PSR-1 `__].
- Code MUST use 4 spaces for indenting, not tabs.
- There MUST NOT be a hard limit on line length; the soft limit MUST be
120 characters; lines SHOULD be 80 characters or less.
- There MUST be one blank line after the ``namespace`` declaration, and
there MUST be one blank line after the block of ``use`` declarations.
- Opening braces for classes MUST go on the next line, and closing
braces MUST go on the next line after the body.
- Opening braces for methods MUST go on the next line, and closing
braces MUST go on the next line after the body.
- Visibility MUST be declared on all properties and methods;
``abstract`` and ``final`` MUST be declared before the visibility;
``static`` MUST be declared after the visibility.
- Control structure keywords MUST have one space after them; method and
function calls MUST NOT.
- Opening braces for control structures MUST go on the same line, and
closing braces MUST go on the next line after the body.
- Opening parentheses for control structures MUST NOT have a space
after them, and closing parentheses for control structures MUST NOT
have a space before.
1.1. 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 `__.
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; automated style
checkers MUST warn but MUST NOT error at the soft limit.
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 non-blank lines.
Blank lines MAY be added to improve readability and to indicate related
blocks of code.
There MUST NOT be more than one statement per line.
2.4. Indenting
--------------
Code MUST use an indent of 4 spaces, and MUST NOT use tabs for
indenting.
.. Note::
N.b.: Using only spaces, and not mixing spaces with tabs, helps to
avoid problems with diffs, patches, history, and annotations. The
use of spaces also makes it easy to insert fine-grained
sub-indentation for inter-line alignment.
2.5. Keywords and True/False/Null
---------------------------------
PHP `keywords `__ MUST
be in lower case.
The PHP constants ``true``, ``false``, and ``null`` MUST be in lower
case.
---------------------------------
3. Namespace and Use Declarations
---------------------------------
When present, there MUST be one blank line after the ``namespace``
declaration.
When present, all ``use`` declarations MUST go after the ``namespace``
declaration.
There MUST be one ``use`` keyword per declaration.
There MUST be one blank line after the ``use`` block.
For example:
.. 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.
.. code-block:: php
bar(
$longArgument,
$longerArgument,
$muchLongerArgument
);
---------------------
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 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``
-----------------------
A ``try catch`` block looks like the following. Note the placement of
parentheses, spaces, and braces.
.. code-block:: php
bar(
$arg1,
function ($arg2) use ($var1) {
// body
},
$arg3
);
-------------
7. Conclusion
-------------
There are many elements of style and practice intentionally omitted by
this guide. These include but are not limited to:
- Declaration of global variables and global constants
- Declaration of functions
- Operators and assignment
- Inter-line alignment
- Comments and documentation blocks
- Class name prefixes and suffixes
- Best practices
Future recommendations MAY revise and extend this guide to address those or other
elements of style and practice.