PHP的PSR規範中文版

FIG組織在制定跟PHP相關規範，簡稱PSR。目前已有4個代碼規範，近期抽空翻譯成了中文版。建議做PHP的同學都關注一下。
文檔倉庫地址：https://github.com/hfcorriez/fig-standards

所有已接受的規範參考：https://github.com/hfcorriez/fig-standards/tree/zh_CN/%E6%8E%A5%E5%8F%97

代碼樣式規範

本指南的意圖是為了減少不同開發人員在瀏覽代碼時減少認知的差異。 為此列舉一組如何格式化PHP代碼的共用規則。

各個成員項目的共性組成了本文的樣式規則。當不同的開發人員在不同的項目中合作時，將會在這些不同的項目中使用一個共同的標準。 因此，本指南的好處不在於規則本身，而在於共用這些規則。

在 RFC 2119中的特性關鍵詞"必須"(MUST)，“不可”(MUST NOT)，“必要”(REQUIRED)，“將會”(SHALL)，“不會”(SHALL NOT)，“應當”(SHOULD)，“不應”(SHOULD NOT)，“推薦”(RECOMMENDED)，“可以”(MAY)和“可選”(OPTIONAL)在這文檔中將被用來描述。

1. 大綱

• 代碼必須遵守 PSR-1。

• 代碼必須使用4個空格的縮排，而不是定位字元。

• 一行代碼長度不應硬性限制；軟式節流必須為120個字元；也應當是80個字元或者更少。

• 在namespace聲明下面必須有一個空行，並且use聲明代碼塊下面也必須有一個空行。

• 類的左花括弧必須放到下一行，右花括弧必須放在類主體的下一行。

• 方法的左花括弧必須放在下一行，右花括弧必須放在方法主體下面。

• 所有的屬性和方法必須有可見度(譯者註：Public, Protect, Private)聲明；abstract和final聲明必須在可見度之前；static聲明必須在可見度之後。

• 控制結構的關鍵詞必須在後面有一個空格； 方法和函數不可有。

• 控制結構的左花括弧必須放在同一行，右花括弧必須放在控制主體的下一行。

• 控制結構的左括弧後面不可有空格，右括弧之前不可有空格。

1.1. 樣本

本樣本包含上面的一些規則簡單展示：

<?phpnamespace 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. 概括

2.1 基礎代碼規範

代碼必須遵守 PSR-1 的所有規則。

2.2 檔案

所有的PHP檔案必須使用Unix LF(換行)作為行結束符。

所有PHP檔案必須以一個空行結束。

純PHP代碼的檔案關閉標籤?>必須省略

2.3. 行

行長度不可有硬限制。

行長度的軟式節流必須是120個字元；對於軟式節流，自動樣式檢查必須警告但不可報錯。

行實際長度不應超過80個字元；較長的行應當被拆分成多個不超過80個字元的後續行。

在非空行後面不可有空格。

空行可以用來改善可讀性和區分相關的代碼塊。

一行不應多於一個語句。

2.4. 縮排

代碼必須使用4個空格的縮排，並且不可使用定位字元作為縮排。

注意：只用空格，不和定位字元混合使用，將會對避免代碼差異，補丁，曆史和註解中的一些問題有協助。使用空格還可以使調整細微的縮排來改進行間對齊變得非常簡單。

2.5. 關鍵詞和 True/False/Null

PHP keywords 必須使用小寫。

PHP常量true, false和null必須使用小寫。

3. Namespace和Use聲明

如果存在，namespace聲明之後必須有一個空行。

如果存在，所有的use聲明必須放在namespace聲明的下面。

一個use關鍵字必須只用於一個聲明。

在use聲明代碼塊後面必須有一個空行。

樣本:

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

4. 類，屬性和方法

術語“類”指所有的類，介面和特性（traits）。

4.1. 擴充和繼承

一個類的extends和implements關鍵詞必須和類名在同一行。

類的左花括弧必須放在下面自成一行；右花括弧必須放在類主體的後面自成一行。

<?phpnamespace Vendor\Package;use FooClass;use BarClass as Bar;use OtherVendor\OtherPackage\BazClass;class ClassName extends ParentClass implements \ArrayAccess, \Countable{    // constants, properties, methods}

implements一個列表可以被拆分為多個有一次縮排的後續行。如果這麼做，列表的第一項必須要放在下一行，並且每行必須只有一個介面。

<?phpnamespace 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. 屬性

所有的屬性必須聲明可見度。

var關鍵詞不可用來聲明屬性。

一個語句不可聲明多個屬性。

屬性名稱不應使用單個底線作為首碼來表明保護或私人的可見度。

一個屬性聲明看起來應該下面這樣的。

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

4.3. 方法

所有的方法必須聲明可見度。

方法名不應只使用單個底線來表明是保護或私人的可見度。

方法名在聲明之後不可跟隨一個空格。左花括弧必須放在下面自成一行，並且右花括弧必須放在方法主體的下面自成一行。左括弧後面不可有空格，右括弧前面不可有空格。

一個方法定義看來應該像下面這樣。 注意括弧，逗號，空格和花括弧：

<?phpnamespace Vendor\Package;class ClassName{    public function fooBarBaz($arg1, &$arg2, $arg3 = [])    {        // method body    }}

4.4. 方法參數

在參數列表中，逗號之前不可有空格，逗號之後必須要有一個空格。

方法中有預設值的參數必須放在參數列表的最後面。

<?phpnamespace Vendor\Package;class ClassName{    public function foo($arg1, &$arg2, $arg3 = [])    {        // method body    }}

參數列表可以被分為多個有一次縮排的多個後續行。如果這麼做，列表的第一項必須放在下一行，並且每行必須只放一個參數。

當參數列表被分為多行，右括弧和左花括弧必須夾帶一個空格放在一起自成一行。

<?phpnamespace Vendor\Package;class ClassName{    public function aVeryLongMethodName(        ClassTypeHint $arg1,        &$arg2,        array $arg3 = []    ) {        // method body    }}

4.5. abstract，final和 static

如果存在，abstract和final聲明必須放在可見度聲明前面。

如果存在，static聲明必須跟著可見度聲明。

<?phpnamespace Vendor\Package;abstract class ClassName{    protected static $foo;    abstract protected function zim();    final public static function bar()    {        // method body    }}

4.6. 調用方法和函數

要調用一個方法或函數，在方法或者函數名和左括弧之間不可有空格，左括弧之後不可有空格，右括弧之前不可有空格。函數列表中，逗號之前不可有空格，逗號之後必須有一個空格。

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

參數列表可以被拆分成多個有一個縮排的後續行。如果這麼做，列表中的第一項必須放在下一行，並且每一行必須只有一個參數。

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

5. 控制結構

對於控制結構的樣式規則概括如下：

• 控制結構關鍵詞之後必須有一個空格
• 左括弧之後不可有空格
• 右括弧之前不可有空格
• 在右括弧和左花括弧之間必須有一個空格
• 代碼主體必須有一次縮排
• 右花括弧必須主體的下一行

每個結構的主體必須被括在花括弧裡。這結構看上去更標準化，並且當加新行的時候可以減少引入錯誤的可能性。

5.1. if，elseif，else

一個if結構看起來應該像下面這樣。注意括弧，空格，花括弧的位置；並且else和elseif和前一個主體的右花括弧在同一行。

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

關鍵詞elseif應該替代else if使用以保持所有的控制關鍵詞像一個單詞。

5.2. switch，case

一個switch結構看起來應該像下面這樣。注意括弧，空格和花括弧。case語句必須從switch處縮排，並且break關鍵字（或其他中止關鍵字）必須和case主體縮排在同級。如果一個非空的case主體往下落空則必須有一個類似// no break的注釋。

<?phpswitch ($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

一個while語句看起來應該像下面這樣。注意括弧，空格和花括弧的位置。

<?phpwhile ($expr) {    // structure body}

同樣的，一個do while語句看起來應該像下面這樣。注意括弧，空格和花括弧的位置。

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

5.4. for

一個for語句看起來應該像下面這樣。注意括弧，空格和花括弧的位置。

<?phpfor ($i = 0; $i < 10; $i++) {    // for body}

5.5. foreach

一個foreach語句看起來應該像下面這樣。注意括弧，空格和花括弧的位置。

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

5.6. try, catch

一個try catch語句看起來應該像下面這樣。注意括弧，空格和花括弧的位置。

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

6. 閉包

閉包在聲明時function關鍵詞之後必須有一個空格，並且use之前也需要一個空格。

左花括弧必須在同一行，右花括弧必須在主體的下一行。

參數列表和變數列表的左括弧之後不可有空格，其右括弧之前也不可有空格。

在參數列表和變數列表中，逗號之前不可有空格，逗號之後必須有空格。

閉包帶預設值的參數必須放在參數列表後面。

一個閉包聲明看起來應該像下面這樣。注意括弧，空格和花括弧的位置。

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

參數和變數列表可以被分成多個帶一次縮排的後續行。如果這麼做，列表的第一項必須放在下一行，並且一行必須只放一個參數或變數。

當最終列表（不管是參數還是變數）被分成多行，右括弧和左花括弧必須夾帶一個空格放在一起自成一行。

下面是一個參數和變數列表被分割成多行的樣本。

<?php$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};

注意如果在函數或者方法中把閉包作為一個參數調用，如上格式規則同樣適用。

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

7. 結論

在該指南中有很多風格的元素和做法有意被忽略掉。這些包括但不局限於：

• 全域變數和全域常量的聲明

• 方法聲明

• 操作符和賦值

• 行間對齊

• 注釋和文檔塊

• 類名給你首碼和尾碼

• 最佳實務

以後的建議可以修改和擴充該指南以滿足這些或其他風格的元素和實踐。

附錄A 調查

為了寫這個風格指南，我們採用了調查個項目以確定共同的做法。這個調查在這裡供他人查看。

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%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.htmlvoting,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,no,no,no,?,yes,no,yesindent_type,4,4,4,4,4,tab,4,tab,tab,2,4,tab,4,4,4,4,4,4,tab,tab,4,tabline_length_limit_soft,75,75,75,75,no,85,120,120,80,80,80,no,100,80,80,?,?,120,80,120,no,150line_length_limit_hard,85,85,85,85,no,no,no,no,100,?,no,no,no,100,100,?,120,120,no,no,no,noclass_names,studly,studly,studly,studly,studly,studly,studly,studly,studly,studly,studly,lower_under,studly,lower,studly,studly,studly,studly,?,studly,studly,studlyclass_brace_line,next,next,next,next,next,same,next,same,same,same,same,next,next,next,next,next,next,next,next,same,next,nextconstant_names,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,uppertrue_false_null,lower,lower,lower,lower,lower,lower,lower,lower,lower,upper,lower,lower,lower,upper,lower,lower,lower,lower,lower,upper,lower,lowermethod_names,camel,camel,camel,camel,camel,camel,camel,camel,camel,camel,camel,lower_under,camel,camel,camel,camel,camel,camel,camel,camel,camel,camelmethod_brace_line,next,next,next,next,next,same,next,same,same,same,same,next,next,same,next,next,next,next,next,same,next,nextcontrol_brace_line,same,same,same,same,same,same,next,same,same,same,same,next,same,same,next,same,same,same,same,same,same,nextcontrol_space_after,yes,yes,yes,yes,yes,no,yes,yes,yes,yes,no,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yesalways_use_control_braces,yes,yes,yes,yes,yes,yes,no,yes,yes,yes,no,yes,yes,yes,yes,no,yes,yes,yes,yes,yes,yeselse_elseif_line,same,same,same,same,same,same,next,same,same,next,same,next,same,next,next,same,same,same,same,same,same,nextcase_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/2function_space_after,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,noclosing_php_tag_required,no,no,no,no,no,no,no,no,yes,no,no,no,no,yes,no,no,no,no,no,yes,no,noline_endings,LF,LF,LF,LF,LF,LF,LF,LF,?,LF,?,LF,LF,LF,LF,?,,LF,?,LF,LF,LFstatic_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,noblank_line_after_php,no,no,no,no,yes,no,no,no,no,yes,yes,no,no,yes,?,yes,yes,no,yes,no,yes,noclass_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 = "使用定位字元"，2 or 4 = "空格數量"

line_length_limit_soft: 行長度的“軟”限制，用字元。 ? = 不表示或者數字 no 意為不限制.

line_length_limit_hard: 行長度的"硬"限制，用字元。 ? = 不表示或者數字, no 意為不限制.

class_names: 類名如何命名 lower = 只是小寫, lower_under = 小寫加底線, studly = 駱駝型.

class_brace_line: 類的左花括弧是放在同(same)一行還是在下(next)一行？

constant_names: 類常量如何命名？upper = 大寫加底線分隔字元。

true_false_null: 全校寫或者全大寫？

method_names: 方法名如何命名？camel = 駝峰式, lower_under = 小寫加底線分隔字元。

method_brace_line: 方法的左花括弧在同(same)一行還是在下(next)一行？

control_brace_line: 控制結構的左花括弧在同(same)一行還是在下(next)一行？

control_space_after: 控制結構關鍵詞後是否有空格？

always_use_control_braces: 控制結構總是使用花括弧？

else_elseif_line: 當使用else和elseif，是否放在同(same)一行還是在下(next)一行？

case_break_indent_from_switch: case和break分別從swith語句處縮排多少次？

function_space_after: 函數調用的函數名和左括弧是否有空格？

closing_php_tag_required: 如過是純PHP檔案，關閉標籤?>是否需要？

line_endings: 使用何種的行結束符？

static_or_visibility_first: 在定義方法的時候static和可見度誰在前面？

control_space_parens: 在控制結構運算式中，左括弧後面和右括弧前面是否要有一個空格？yes = if ( $expr ), no =if ($expr).

blank_line_after_php: PHP的開始標籤後面是否需要一個空行？

class_method_control_brace: 左花括弧在類，方法和控制結構中的位置。

A.3. 調查結果

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