Code Style Guide

This guide expands and complements the basic coding standard PSR-1.

The purpose of this guide is to reduce cognitive resistance when visually perceiving code written by different authors. To do this, a list of common rules and expectations regarding the formatting of PHP-code.

The stylistic rules presented here are obtained on the basis of summarizing the experience of various projects. When different authors collaborate on multiple projects, it is useful to apply a single set of guidelines for these projects. Thus, the benefits of this guide are not in the rules as such, but in their prevalence.

The keywords “MUST BE” / “MUST” (“MUST”), “MUST NOT” / “NOT SHOULD” (“MUST NOT”), “REQUIRED”, “NEED” (“SHALL”), “NOT” ALLOWED (SHALL NOT), FOLLOW (SHOULD, NOT SUB) ("OPTIONAL") in this document should be treated as described in RFC 2119.

1. Overview

• You must follow the PSR Style Guide [PSR-1].

• For indents it is necessary to use 4 spaces, not tabs.

• It is NOT allowed to strictly limit the length of the string; soft string limit MUST be 120 characters; strings SHOULD be done no longer than 80 characters.

• MUST leave one blank line after the namespace declaration ( namespace ), and MUST leave one blank line after the use statement block.

• Opening curly brackets of classes MUST be transferred to the next line, and closing curly brackets to the next line after the body.

• Opening curly brackets of methods MUST be transferred to the next line, and closing curly brackets to carry to the next line after the body.

• Visibility MUST be declared for all properties and methods; abstract and final MUST be set before the visibility modifier; static MUST be set after the visibility modifier.

• After the keywords of the management structures, it is necessary to put one space; and after the names of functions and methods are NOT ALLOWED.

• The opening curly brackets of control structures MUST be left on the same line, and the closed curly brackets should be moved to the next line after the body.

• It is NOT POSSIBLE to put a space after the opening parentheses of the control structures, and IT IS NOT POSSIBLE to put a space before the closing parentheses of the control structures.

1.1. Example

This example gives a brief overview of some of the rules described below:

 <?php namespace Vendor\Package; use FooInterface; use BarClass as Bar; use OtherVendor\OtherPackage\BazClass; class Foo extends Bar implements FooInterface { public function sampleFunction($a, $b = null) { if ($a === $b) { bar(); } elseif ($a > $b) { $foo->bar($arg1); } else { BazClass::bar($arg2, $arg3); } } final public static function bar() { // тело метода } } 

2. General provisions

2.1 Basic Coding Standard

The code MUST follow the rules described in PSR-1.

2.2 Files

All PHP files MUST use LF line endings (\ n).

All PHP files MUST end in one blank line.

The closing tag ?> MUST be removed from files containing only PHP.

2.3. Strings

It is NOT allowed to strictly limit the length of the string.

A soft string limit MUST be 120 characters; automated style testers MUST warn of a violation of the soft limit, but not consider it a mistake.

DO NOT make lines longer than 80 characters; those lines that are longer SHOULD be split into several lines, no more than 80 characters each.

You MUST leave spaces at the end of non-empty lines.

You can use blank lines to improve readability and designate related code blocks.

MUST NOT write more than one instruction on one line.

2.4. Indentation

The code MUST use an indentation of 4 spaces, and it is NOT POSSIBLE to use tabs for indents.

Nb: The use of single spaces, without the admixture of tabs, helps to avoid problems with diffs, patches, history and authorship of strings. The use of spaces also allows you to easily and accurately make interline alignment alignment.

2.5. Keywords and True / False / Null

PHP keywords MUST be written in lower case.

PHP constants: true , false , and null MUST be written in lower case.

3. Namespaces and use statement

In the presence of a namespace ( namespace ), after its declaration it is necessary to leave one empty string.

In the presence of use operators, it is necessary to locate them after the name is declared.

You MUST use one use statement for one advertisement (import or create a nickname).

MUST leave one blank line after the use statement block.

For example:

 <?php namespace Vendor\Package; use FooClass; use BarClass as Bar; use OtherVendor\OtherPackage\BazClass; // ... additional PHP code ... 

4. Classes, properties and methods

The word "class" refers to all classes, interfaces, and traits.

4.1. Extends and implements

The extends and implements keywords extends placed on the same line as the class name.

The opening curly bracket of a class MUST be transferred to the next line; the closing curly bracket of a class MUST be placed on the next line after the body of the class.

 <?php namespace Vendor\Package; use FooClass; use BarClass as Bar; use OtherVendor\OtherPackage\BazClass; class ClassName extends ParentClass implements \ArrayAccess, \Countable { // константы, свойства, методы } 

The list of implements can be split into several lines, each with one indentation. At the same time, the first interface in the list MUST be transferred to the next line, and in each line MUST specify only one interface.

 <?php namespace Vendor\Package; use FooClass; use BarClass as Bar; use OtherVendor\OtherPackage\BazClass; class ClassName extends ParentClass implements \ArrayAccess, \Countable, \Serializable { // константы, свойства, методы } 

4.2. Properties

Visibility MUST be declared for all properties;

Use the var keyword to declare properties NOT ALLOWED.

MUST NOT specify more than one property in one ad.

DO NOT begin the property name with an underscore to indicate private or protected visibility.

The property declaration looks like the one below.

 <?php namespace Vendor\Package; class ClassName { public $foo = null; } 

4.3. Methods

Visibility MUST be declared for all methods;

DO NOT begin the method name with an underscore to indicate private or protected visibility.

You MUST NOT declare methods with a space after the method name. The opening curly bracket MUST be placed on a separate line; the closing brace MUST be placed on the next line after the body of the method. DO NOT leave a space after the opening parenthesis and before the closing one.

The method declaration looks like the one below. Note the arrangement of commas, spaces, round brackets, braces:

 <?php namespace Vendor\Package; class ClassName { public function fooBarBaz($arg1, &$arg2, $arg3 = []) { // тело метода } } 

4.4. Method Arguments

In the argument list, spaces before commas are NOT ALLOWED, and one space after each comma is REQUIRED.

Method arguments with default values ​​MUST be placed at the end of the argument list.

 <?php namespace Vendor\Package; class ClassName { public function foo($arg1, &$arg2, $arg3 = []) { // тело метода } } 

The argument list MAY be broken up into several lines, each one with a single indent. At the same time, the first argument in the list MUST be transferred to the next line, and in each line MUST specify only one argument.

When the list of arguments is divided into several lines, the closing parenthesis and the opening curly MUST be placed on one separate line, with one space between them.

 <?php namespace Vendor\Package; class ClassName { public function aVeryLongMethodName( ClassTypeHint $arg1, &$arg2, array $arg3 = [] ) { // тело метода } } 

4.5. abstract , final and static

If available, the keywords are abstract and final , MUST be preceded by visibility modifiers.

If the keyword is static , it MUST be followed by the visibility modifier.

 <?php namespace Vendor\Package; abstract class ClassName { protected static $foo; abstract protected function zim(); final public static function bar() { // тело метода } } 

4.6. Function calls and methods

When calling a method or function, spaces between the name of the method or function and the opening parenthesis are NOT ALLOWABLE, as well as spaces after the opening parenthesis and before the closing parenthesis are NOT ALLOWABLE. In the argument list, spaces before commas are NOT ALLOWED, and one space after each comma is REQUIRED.

 <?php bar(); $foo->bar($arg1); Foo::bar($arg2, $arg3); 

The argument list MAY be broken up into several lines, each one with a single indent. At the same time, the first argument in the list MUST be transferred to the next line, and in each line MUST specify only one argument.

 <?php $foo->bar( $longArgument, $longerArgument, $muchLongerArgument ); 

5. Management structures

The general style rules for control structures are:

• After the keyword of the management structure, one space is REQUIRED
• After the opening parenthesis, the space is NOT ALLOWED
• Before the closing parenthesis, the space is NOT ALLOWED
• IT IS NECESSARY one space between the closing parenthesis and the opening brace
• The body of the control structure MUST be shifted by one indent
• The closing brace MUST be placed on the next line after the body

The body of each control structure MUST be enclosed in braces. This standardizes the appearance of control structures and reduces the likelihood of errors when new lines are added to the body.

5.1. if , elseif , else

The if control structure is as shown below. Note the location of the spaces, the parentheses and the curly braces; and that else and elseif are located on the same line with the closing curly bracket of the previous body.

 <?php if ($expr1) { // тело if } elseif ($expr2) { // тело elseif } else { // тело else; } 

Instead of else if SHOULD use elseif so that all keywords of control structures look like one word.

5.2. switch , case

The switch control structure is as shown below. Pay attention to the arrangement of spaces, parentheses and curly brackets: The case expression MUST be shifted by one switch from the switch , and the keyword break (or another terminating keyword) MUST be shifted to the same level as the body of case . When deliberately failing out of a non-empty case comment is REQUIRED like // no break .

 <?php switch ($expr) { case 0: echo 'Первый case, заканчивается на break'; break; case 1: echo 'Второй case, с умышленным проваливанием'; // no break case 2: case 3: case 4: echo 'Третий case, завершается словом return вместо braek'; return; default: echo 'По-умолчанию'; break; } 

5.3. while , do while

The while control structure looks like the one below. Note the location of the spaces, the parentheses and the curly braces:

 <?php while ($expr) { // structure body } 

Similarly, the do while control structure looks like the one below. Note the location of the spaces, the parentheses and the curly braces:

 <?php do { // structure body; } while ($expr); 

5.4. for

The for control structure looks like the one below. Note the location of the spaces, the parentheses and the curly braces:

 <?php for ($i = 0; $i < 10; $i++) { // тело for } 

5.5. foreach

The foreach control structure is as shown below. Note the location of the spaces, the parentheses and the curly braces:

 <?php foreach ($iterable as $key => $value) { // тело foreach } 

5.6. try , catch

The try catch looks like the one below. Note the location of the spaces, the parentheses and the curly braces:

 <?php try { // тело try } catch (FirstExceptionType $e) { // тело catch } catch (OtherExceptionType $e) { // catch body } 

6. Closures

In the closure declaration, there is a REQUIRED problem after the function keyword, as well as before and after the use keyword.

The opening brace MUST be placed on the same line; the closing brace MUST be placed on the next line after the body of the circuit.

No spaces are allowed after the opening parenthesis of a list of arguments or variables, and spaces are NOT allowed before the closing parenthesis of an argument list or variables.

In the list of arguments and in the list of variables, spaces before commas are NOT ALLOWABLE, and there must be one space after each comma.

Arguments for closures with default values ​​MUST be placed at the end of the argument list.

The declaration of the closure is as shown below. Note the arrangement of commas, spaces, round brackets, braces:

 <?php $closureWithArgs = function ($arg1, $arg2) { // тело }; $closureWithArgsAndVars = function ($arg1, $arg2) use ($var1, $var2) { // body }; 

The list of arguments and the list of variables MAY be divided into several lines, each of which with a single copy. At the same time, the first item in the list MUST be transferred to the next line, and in each line MUST specify only one argument or one variable.

When the last list (either of arguments or variables) is divided into several lines, closing the parenthesis and the opening curly MUST be placed on one separate line, with one space between them.

Below are examples of closures with and without arguments, as well as with a list of free variables for several lines.

 <?php $longArgs_noVars = function ( $longArgument, $longerArgument, $muchLongerArgument ) { // тело }; $noArgs_longVars = function () use ( $longVar1, $longerVar2, $muchLongerVar3 ) { // тело }; $longArgs_longVars = function ( $longArgument, $longerArgument, $muchLongerArgument ) use ( $longVar1, $longerVar2, $muchLongerVar3 ) { // тело }; $longArgs_shortVars = function ( $longArgument, $longerArgument, $muchLongerArgument ) use ($var1) { // тело }; $shortArgs_longVars = function ($arg) use ( $longVar1, $longerVar2, $muchLongerVar3 ) { // body }; 

Note that formatting rules also apply when the closure is used directly as an argument when calling a method or function.

 <?php $foo->bar( $arg1, function ($arg2) use ($var1) { // body }, $arg3 ); 

7. Conclusion

Many elements of style and practice have been deliberately omitted in this manual. Here are some of them:

• Declaring global variables and global constants

• Function declaration

• Operators and Assignments

• Alignment inside rows

• Comments and documentation blocks

• Prefixes and suffixes in class names

• Best practics

Future recommendations MAY correct and expand this manual by referring to these or other style elements and practices.

Appendix A. Research

When writing this guide, a group of authors conducted a study to identify common practices in the projects of the participants. This study is stored here for posterity.

A.1. Research data

 url,http://www.horde.org/apps/horde/docs/CODING_STANDARDS,http://pear.php.net/manual/en/standards.php,http://solarphp.com/manual/appendix-standards.style,http://framework.zend.com/manual/en/coding-standard.html,http://symfony.com/doc/2.0/contributing/code/standards.html,http://www.ppi.io/docs/coding-standards.html,https://github.com/ezsystems/ezp-next/wiki/codingstandards,http://book.cakephp.org/2.0/en/contributing/cakephp-coding-conventions.html,https://github.com/UnionOfRAD/lithium/wiki/Spec%3A-Coding,http://drupal.org/coding-standards,http://code.google.com/p/sabredav/,http://area51.phpbb.com/docs/31x/coding-guidelines.html,https://docs.google.com/a/zikula.org/document/edit?authkey=CPCU0Us&hgd=1&id=1fcqb93Sn-hR9c0mkN6m_tyWnmEvoswKBtSc0tKkZmJA,http://www.chisimba.com,n/a,https://github.com/Respect/project-info/blob/master/coding-standards-sample.php,n/a,Object Calisthenics for PHP,http://doc.nette.org/en/coding-standard,http://flow3.typo3.org,https://github.com/propelorm/Propel2/wiki/Coding-Standards,http://developer.joomla.org/coding-standards.html voting,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,no,no,no,?,yes,no,yes indent_type,4,4,4,4,4,tab,4,tab,tab,2,4,tab,4,4,4,4,4,4,tab,tab,4,tab line_length_limit_soft,75,75,75,75,no,85,120,120,80,80,80,no,100,80,80,?,?,120,80,120,no,150 line_length_limit_hard,85,85,85,85,no,no,no,no,100,?,no,no,no,100,100,?,120,120,no,no,no,no class_names,studly,studly,studly,studly,studly,studly,studly,studly,studly,studly,studly,lower_under,studly,lower,studly,studly,studly,studly,?,studly,studly,studly class_brace_line,next,next,next,next,next,same,next,same,same,same,same,next,next,next,next,next,next,next,next,same,next,next constant_names,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper true_false_null,lower,lower,lower,lower,lower,lower,lower,lower,lower,upper,lower,lower,lower,upper,lower,lower,lower,lower,lower,upper,lower,lower method_names,camel,camel,camel,camel,camel,camel,camel,camel,camel,camel,camel,lower_under,camel,camel,camel,camel,camel,camel,camel,camel,camel,camel method_brace_line,next,next,next,next,next,same,next,same,same,same,same,next,next,same,next,next,next,next,next,same,next,next control_brace_line,same,same,same,same,same,same,next,same,same,same,same,next,same,same,next,same,same,same,same,same,same,next control_space_after,yes,yes,yes,yes,yes,no,yes,yes,yes,yes,no,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes always_use_control_braces,yes,yes,yes,yes,yes,yes,no,yes,yes,yes,no,yes,yes,yes,yes,no,yes,yes,yes,yes,yes,yes else_elseif_line,same,same,same,same,same,same,next,same,same,next,same,next,same,next,next,same,same,same,same,same,same,next case_break_indent_from_switch,0/1,0/1,0/1,1/2,1/2,1/2,1/2,1/1,1/1,1/2,1/2,1/1,1/2,1/2,1/2,1/2,1/2,1/2,0/1,1/1,1/2,1/2 function_space_after,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no closing_php_tag_required,no,no,no,no,no,no,no,no,yes,no,no,no,no,yes,no,no,no,no,no,yes,no,no line_endings,LF,LF,LF,LF,LF,LF,LF,LF,?,LF,?,LF,LF,LF,LF,?,,LF,?,LF,LF,LF static_or_visibility_first,static,?,static,either,either,either,visibility,visibility,visibility,either,static,either,?,visibility,?,?,either,either,visibility,visibility,static,? control_space_parens,no,no,no,no,no,no,yes,no,no,no,no,no,no,yes,?,no,no,no,no,no,no,no blank_line_after_php,no,no,no,no,yes,no,no,no,no,yes,yes,no,no,yes,?,yes,yes,no,yes,no,yes,no class_method_control_brace,next/next/same,next/next/same,next/next/same,next/next/same,next/next/same,same/same/same,next/next/next,same/same/same,same/same/same,same/same/same,same/same/same,next/next/next,next/next/same,next/same/same,next/next/next,next/next/same,next/next/same,next/next/same,next/next/same,same/same/same,next/next/same,next/next/next 

A.2. Legend Research

indent_type : indent_type type. tab = "Tab used", 2 or 4 = "number of spaces"

line_length_limit_soft : "Soft" limit on the length of the line in characters. ? = not defined, no no limit.

line_length_limit_hard : A hard limit on the length of a line in characters. ? = not defined, no no limit.

class_names : class names. lower = only lower case, lower_under = lower case and underscores, studly = StudlyCase.

class_brace_line : class_brace_line opening curly bracket of the class go on the same ( same ) line as the word class, or on the next ( next )?

constant_names : How are class constant names written? upper = In upper case with underscores.

true_false_null : true_false_null keywords true , false and null written in lower ( lower ) or upper ( upper ) register?

method_names : How are method names written? camel = camelCase , lower_under = lowercase with underscores.

method_brace_line : method_brace_line opening curly brace of the method go on the same ( same ) line as the word class, or on the next ( next )?

control_brace_line : control_brace_line opening brace of the control structure go on the same ( same ) line as the word class, or on the next ( next )?

control_space_after : Is there a space after the keyword of the control structure?

always_use_control_braces : Do control structures always use curly braces?

else_elseif_line : When using else or elseif , are they located on one ( same ) line with a closing brace or on the next ( next )?

case_break_indent_from_switch : How many horizontal indents does case and break for a switch ?

function_space_after : Does the function call have a space between the function name and the opening parenthesis?

closing_php_tag_required : Do you need a closing tag ?> in files containing only PHP?

line_endings : Type of line endings?

static_or_visibility_first : When declaring a method, is static or a visibility modifier going ahead?

control_space_parens : Are there any spaces inside parentheses of control structures? yes = if ( $expr ) , no = if ($expr) .

blank_line_after_php : Is there an empty line after the PHP opening tag?

class_method_control_brace : On which line is the opening curly bracket of the class, method, and control structure written?

A.3. The result of the study

 indent_type: tab: 7 2: 1 4: 14 line_length_limit_soft: ?: 2 no: 3 75: 4 80: 6 85: 1 100: 1 120: 4 150: 1 line_length_limit_hard: ?: 2 no: 11 85: 4 100: 3 120: 2 class_names: ?: 1 lower: 1 lower_under: 1 studly: 19 class_brace_line: next: 16 same: 6 constant_names: upper: 22 true_false_null: lower: 19 upper: 3 method_names: camel: 21 lower_under: 1 method_brace_line: next: 15 same: 7 control_brace_line: next: 4 same: 18 control_space_after: no: 2 yes: 20 always_use_control_braces: no: 3 yes: 19 else_elseif_line: next: 6 same: 16 case_break_indent_from_switch: 0/1: 4 1/1: 4 1/2: 14 function_space_after: no: 22 closing_php_tag_required: no: 19 yes: 3 line_endings: ?: 5 LF: 17 static_or_visibility_first: ?: 5 either: 7 static: 4 visibility: 6 control_space_parens: ?: 1 no: 19 yes: 2 blank_line_after_php: ?: 1 no: 13 yes: 8 class_method_control_brace: next/next/next: 4 next/next/same: 11 next/same/same: 1 same/same/same: 6