diff --git a/source/development/guidelines.rst b/source/development/guidelines.rst index 8a0f5766..c220f503 100644 --- a/source/development/guidelines.rst +++ b/source/development/guidelines.rst @@ -14,4 +14,5 @@ Coding Guidelines guidelines/basics guidelines/psr1 guidelines/psr2 + guidelines/psr12 guidelines/peps diff --git a/source/development/guidelines/psr12.rst b/source/development/guidelines/psr12.rst new file mode 100644 index 00000000..951ad84c --- /dev/null +++ b/source/development/guidelines/psr12.rst @@ -0,0 +1,1163 @@ +========================== +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 + +