PHP PSR specification Chinese version_php basics-php手册-php.cn

Document warehouse address:https://github.com/hfcorriez/fig-standards

Chinese version of PSR specification

Why Norm

The excerpt translates an official sentence. This organization aims to find a collaborative programming environment by discussing the commonalities between our code projects. method.

This reminds me of this passage in an article "Why Google Enforces Strict Code Standards":

Copy codeThe code is as follows :

        
In Google, I can view any code, enter all Google code libraries, and I have permission to view them. In fact, very few people have this kind of authority. However, what surprised me was that so many coding standards—indentation, naming, file structure, comment style—all made it surprisingly easy for me to read any piece of code and understand them easily. This shocked me—because I thought these norms were trivial. They couldn't possibly have done that much—yet they did. When you find that you can understand a piece of code just by looking at the basic syntax structure of the program, this kind of time saving cannot but be shocking!

Dear readers, I don’t need to say more about the regulations.

Write it at the end
Specifications are not obligatory. Of course, you can also choose your own way, but using specifications will make your cooperation easier. Nowadays, the writing of various more modern applications is no longer like before. An application generally consists of many modules. If the specifications are not implemented, it will only make the understanding and communication of the entire project more complicated.

If you use specifications, the benefits to the project and yourself are of course self-evident.

All accepted specification references: https://github.com/ hfcorriez/fig-standards/tree/zh_CN/Accept

Code Style Specification

The intention of this guide is to reduce the confusion between different developers browsing the code. to reduce cognitive differences. This enumerates a set of common rules for how to format PHP code.
The commonalities of each member project form the style rules of this article. When different developers collaborate on different projects, a common standard will be used across these different projects. Therefore, the benefit of this guide lies not in the rules themselves, but in sharing them.
The characteristic keywords in RFC 2119 are "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The words "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" and "OPTIONAL" will be used in this document.

1. Outline

Code must comply with PSR-1.

Code must use 4 spaces indentation, not tabs.
There should be no hard limit on the length of a line of code; the soft limit must be 120 characters; it should also be 80 characters or less.
There must be a blank line below the namespace declaration, and there must also be a blank line below the use declaration block.
The left curly brace of the class must be placed on the next line, and the right curly brace must be placed on the next line of the class body.
The left curly brace of a method must be placed on the next line, and the closing curly brace must be placed below the method body.
All properties and methods must have visibility (Translator's Note: Public, Protect, Private) declarations; abstract and final declarations must be before visibility; static declarations must be after visibility.
The keywords of the control structure must be followed by a space; methods and functions are not allowed.
The left curly brace of the control structure must be placed on the same line, and the right curly brace must be placed on the next line of the control body.
There must be no spaces after the left bracket of the control structure and no spaces before the right bracket.

1.1. Example
This example contains a simple display of some of the above rules:

Copy codeThe code is as follows:

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()
{
// method body
}
}

2. Summary
2.1 Basic Code Specifications
Code must comply with all rules of PSR-1.

2.2 Files
All PHP files must use Unix LF (line feed) as the line terminator.

All PHP files must end with a blank line.

File closing tag for pure PHP code?> must be omitted

2.3. Lines
There cannot be a hard limit on line length.

The soft limit on line length must be 120 characters; the automatic style checker must warn but not error about the soft limit.

The actual length of a

line should not exceed 80 characters; longer lines should be split into subsequent lines of no more than 80 characters.

There must be no spaces after non-blank lines.

Blank lines can be used to improve readability and distinguish related blocks of code.

There should be no more than one statement per line.

2.4. Indentation
Code must use 4 spaces for indentation, and tab characters cannot be used as indentation.

Note: Using only spaces, not mixed with tabs, will help avoid some problems in code differences, patches, history and comments. Using whitespace also makes it very easy to adjust subtle indentations to improve alignment between lines.

2.5. Keywords and True/False/Null
PHP keywords must be lowercase.

PHP constants true, false and null must be lowercase.

3. Namespace and Use declarations
If present, there must be a blank line after the namespace declaration.

If present, all use statements must be placed below the namespace statement.

A use keyword must be used in only one declaration.

There must be a blank line after the use declaration block.

Example:

Copy codeThe code is as follows:

namespace Vendor\Package;

use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

// ... additional PHP code ...

4. Classes, Properties and Methods
The term "class" refers to all classes, interfaces and characteristics (traits).

4.1. Extension and inheritance
The extends and implements keywords of a class must be on the same line as the class name.

The left curly brace of the class must be placed on its own line below; the right curly brace must be placed on its own line after the class body.

Copy codeThe code is as follows:

namespace Vendor\Package;
use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

class ClassName extends ParentClass implements \ArrayAccess, \Countable
{
// constants, properties, methods
}

implementsA list can be split into multiple subsequent lines with one indentation. If you do this, the first item in the list must be placed on the next line, and there must be only one interface per line.

Copy codeThe code is as follows:

namespace Vendor\Package;

use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

class ClassName extends ParentClass implements
\ArrayAccess,
\Countable,
\Serializable
{
// constants, properties, methods
}

4.2. Properties
All properties must declare visibility.

The var keyword cannot be used to declare attributes.

One statement cannot declare multiple attributes.

Attribute names should not be prefixed with a single underscore to indicate protected or private visibility.

A property declaration should look like this.

Copy codeThe code is as follows:

namespace Vendor\Package;

class ClassName
{
public $foo = null;
}

4.3. Methods
All methods must declare visibility.

Method names should not use only a single underscore to indicate protected or private visibility.

The method name cannot be followed by a space after the declaration. The opening curly brace must be placed on its own line below, and the closing curly brace must be placed on its own line below the method body. There must be no spaces after the left bracket and no spaces before the right bracket.

A method definition should look like the following. Note the parentheses, commas, spaces and curly braces:

Copy codeThe code is as follows:

namespace Vendor\Package;

class ClassName
{
public function fooBarBaz($arg1, &$arg2, $arg3 = [])
{
// method body
}
}

4.4. Method parameters
In the parameter list, there must be no space before the comma, and there must be one space after the comma.

Parameters with default values in the method must be placed at the end of the parameter list.

Copy codeThe code is as follows:

namespace Vendor\Package;

class ClassName
{
public function foo($arg1, &$arg2, $arg3 = [])
{
// method body
}
}

The parameter list can be divided into multiple subsequent lines with one indentation. If you do this, the first item in the list must be placed on the next line, and only one parameter must be placed on each line.

When the parameter list is divided into multiple lines, the right bracket and the left curly bracket must be placed on a single line with a space between them.

Copy codeThe code is as follows:

namespace Vendor\Package;

class ClassName
{
public function aVeryLongMethodName(
ClassTypeHint $arg1,
&$arg2,
array $arg3 = []
) {
// method body
}
}

4.5. abstract, final and static
If present, abstract and final declarations must be placed before the visibility declaration.

If present, a static declaration must be followed by a visibility declaration.

Copy codeThe code is as follows:

namespace Vendor\Package;

abstract class ClassName
{
protected static $foo;

abstract protected function zim();

final public static function bar()
{
// method body
}
}

4.6. Calling methods and functions
To call a method or function, there must be no spaces between the method or function name and the left bracket, no spaces after the left bracket, and no spaces before the right bracket. In the function list, there must be no space before the comma and there must be one space after the comma.

bar();
$foo->bar($arg1);
Foo::bar($arg2, $arg3);
The parameter list can be split into Multiple following lines have an indent. If you do this, the first item in the list must be placed on the next line, and each line must have exactly one argument.

Copy codeThe code is as follows:

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

5. Control structure
The style rules for control structures are summarized as follows:

There must be a space after the control structure keyword
There must be no space after the left bracket
There must be no space before the right bracket
There must be a space between the right bracket and the left curly bracket
Code The body must be indented once
The closing curly brace must be one line below the body
The body of each structure must be enclosed in curly braces. This structure looks more standardized and reduces the possibility of introducing errors when adding new lines.

5.1. if, elseif, else

An if structure should look like the following. Pay attention to the placement of parentheses, spaces, and curly braces; and else and elseif are on the same line as the closing curly brace of the previous body.

Copy codeThe code is as follows:

        
        if ($expr1) {
        
// if body
        
} elseif ($expr2) {
        
// elseif body
        
} else {
        
// else body;
        
}

The keyword elseif should be used instead of else if to keep all control keywords as one word.

5.2. switch, case

A switch structure should look like the following. Pay attention to the parentheses, spaces and curly braces. The case statement must be indented from the switch, and the break keyword (or other break keyword) must be indented at the same level as the case body. If a non-empty case body falls down, there must be a comment like // no break.

Copy codeThe code is as follows:

        
        switch ($expr) {
        
case 0:
        
echo 'First case, with a break';
        
break;
        
case 1:
        
echo 'Second case, which falls through';
        
// no break
        
case 2:
        
case 3:
        
case 4:
        
echo 'Third case, return instead of break';
        
return;
        
default:
        
echo 'Default case';
        
break;
        
}

5.3. while, do while
A while statement should look like the following. Pay attention to the placement of parentheses, spaces, and curly braces.

Copy codeThe code is as follows:

        
        while ($expr) {
        
// structure body
        
}

Similarly, a do while statement should look like the following. Pay attention to the placement of parentheses, spaces, and curly braces.

Copy codeThe code is as follows:

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

5.4. for
A for statement should look like the following. Pay attention to the placement of parentheses, spaces, and curly braces.

Copy codeThe code is as follows:

        
        for ($i = 0; $i // for body
        
}

5.5. foreach

A foreach statement should look like the following. Pay attention to the placement of parentheses, spaces, and curly braces.

Copy codeThe code is as follows:

        
        foreach ($iterable as $key => $value) {
        
// foreach body
        
}

5.6. try, catch
A try catch statement should look like the following. Pay attention to the placement of parentheses, spaces, and curly braces.

Copy codeThe code is as follows:

        
        try {
        
// try body
        
} catch (FirstExceptionType $e) {
        
// catch body} catch (OtherExceptionType $e) {
        
// catch body
        
}

6. Closure

A closure must have a space after the function keyword when declared, and a space before use.

The opening curly brace must be on the same line, and the closing curly brace must be on the next line after the body.

There must be no spaces after the opening brackets of parameter lists and variable lists, and there must be no spaces before the closing brackets.

In parameter lists and variable lists, there must be no spaces before the comma and there must be spaces after the comma.

Parameters of a closure with default values must be placed after the parameter list.

A closure declaration should look like the following. Pay attention to the placement of parentheses, spaces, and curly braces.

Copy codeThe code is as follows:

        
        $closureWithArgs = function ( $arg1, $arg2) {
        
// body
        
};
        
$closureWithArgsAndVars = function ($arg1, $arg2) use ($var1, $var2) {
        
// body
        
};

Parameter and variable lists can be split into multiple subsequent lines with one indentation. If you do this, the first item in the list must be placed on the next line, and only one parameter or variable must be placed on a line.

When the final list (whether parameters or variables) is divided into multiple lines, the closing bracket and the opening curly bracket must be placed on their own line with a space between them.

The following is an example of a parameter and variable list split into multiple lines.

Copy codeThe code is as follows:

$longArgs_noVars = function (
$longArgument,
$longerArgument,
$muchLongerArgument
) { // body
};

$noArgs_longVars = function () use (
$longVar1,
$longerVar2,
$muchLongerVar3
) {
// body
};

$longArgs_longVars = function (
$longArgument,
$longerArgument,
$muchLongerArgument
) use (
$longVar1,
$longerVar2,
$muchLongerVar3
>) {
// body
};

$longArgs_shortVars = function (
$longArgument,
$longerArgument,
$muchLongerArgument
) use ($var1) {
// body
};

$shortArgs_longVars = function ($arg) use (
$longVar1,
$longerVar2,
$muchLongerVar3
) {
// body
};

Note that if the closure is called as a parameter in a function or method, the above formatting rules also apply.

Copy codeThe code is as follows:

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

7. Conclusion
There are many stylistic elements and practices that have been intentionally left out of this guide. These include but are not limited to:

Declaration of global variables and global constants

Method declaration

Operators and assignment

Alignment between lines

Comments and documentation blocks

The class name gives you the prefix and suffix

Best Practices

Future proposals may modify and expand this guide to meet these or other style elements and practices.

Appendix A Survey
To write this style guide, we used a survey of projects to identify common practices. The survey is here for others to view.

A.1. 调查数据
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:-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. 调查说明
indent_type: 缩进类型。tab = "Use tab character", 2 or 4 = "Number of spaces"

line_length_limit_soft: "soft" limit on line length, in characters. ? = does not mean no or the number no means no limit.

line_length_limit_hard: "hard" limit on line length, in characters. ? = does not mean or number, no means no limit.

class_names: How to name class names lower = just lowercase, lower_under = lowercase plus underline, studly = camel type.

class_brace_line: Should the left brace of a class be placed on the same line or on the next line?

constant_names: How to name class constants? upper = uppercase plus underline delimiter.

true_false_null: All letters or all capital letters?

method_names: How to name method names? camel = camel case, lower_under = lowercase plus underline delimiter.

method_brace_line: Is the opening brace of the method on the same line or on the next line?

control_brace_line: Is the left brace of the control structure on the same line or the next line?

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

always_use_control_braces: Always use braces for control structures?

else_elseif_line: When using else and elseif, should they be placed on the same line or on the next line?

case_break_indent_from_switch: How many times are case and break indented from the switch statement?

function_space_after: Are there spaces in the function name and left bracket of the function call?

closing_php_tag_required: If it is a pure PHP file, is closing the tag?> required?

line_endings: What line endings are used?

static_or_visibility_first: When defining a method, which one comes first, static or visibility?

control_space_parens: In the control structure expression, is there a space after the left bracket and before the right bracket? yes = if ( $expr ), no =if ($expr).

blank_line_after_php: Is a blank line required after the PHP start tag?

class_method_control_brace: The position of the left curly brace in classes, methods and control structures.

A.3. 调查结果
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