摘要：編碼樣式指南翻譯薛粲授權許可這份文檔是的非官方譯文。編碼樣式指南擴展和擴充了基礎編碼規范。概述代碼必須遵循一份編碼樣式指南。行不得對行寬設置硬性限制。對行寬的軟性限制必須是個字符超出時自動樣式檢查必須發出警告但不得產生錯誤。

翻譯：薛粲
授權許可：CC BY-NC 4.0

這份文檔是《PSR-2: Coding Style Guide》的非官方譯文。

《PSR-2：編碼樣式指南》擴展和擴充了《PSR-1：基礎編碼規范》。

這份指南的初衷是減少當我們閱讀不同作者編寫的代碼時遇到的認知差異。它期望通過列舉了一組可供共同遵循的規則用于格式化 PHP 源代碼來實現這一目的。

英文原文使用的關鍵詞 "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 以及 "OPTIONAL" 遵循 RFC 2119 的描述。譯文中根據上下文可能會使用不同的詞匯來對應這些關鍵詞，并加粗顯示。

代碼必須遵循一份 PSR 編碼樣式指南 PSR-1。

代碼必須使用 4 個空格而不是制表符作為縮進。

不得對行寬進行硬性限制；軟性限制必須是 120 個字符；每行應該包含 80 個或者更少的字符。

在 namespace 聲明之后必須有一個空行，在 use 聲明之后也必須有一個空行。

類的左花括號必須在下一行，右花括號必須在內容后的下一行。

方法的左花括號必須在下一行，右花括號必須在內容后的下一行。

必須為所有屬性和方法聲明訪問控制；abstract 和 final 必須在訪問控制之前；static 必須在訪問控制之后。

在控制結構的保留字后必須有一個空格；在方法和函數調用之后不得有空格。

控制結構的左花括號必須在同一行，右花括號必須在內容后的下一行。

控制結構的左括號之后不得有空格，右括號之前不得有空格。

這個例子作為一個簡明的示例，涵蓋了一些后面提及的規則：

 $b) {
            $foo->bar($arg1);
        } else {
            BazClass::bar($arg2, $arg3);
        }
    }

    final public static function bar()
    {
        // 方法內容
    }
}

代碼必須遵循 PSR-1 規范列出的所有規則。

所有 PHP 源文件必須使用 Unix LF (linefeed) 作為換行符。

所有 PHP 源文件必須以一個空行結束。

對于只包含 PHP 的文件，必須省略用于指示 PHP 段結束的 ?> 標記。

不得對行寬設置硬性限制。

對行寬的軟性限制必須是 120 個字符；超出時自動樣式檢查必須發出警告但不得產生錯誤。

行不應該超過 80 個字符；超過的行應該分割為多個不超過 80 個字符的行。

非空的行不得以空白字符結束。

可以添加空行用于指出代碼塊的關聯性以提升代碼的可讀性。

一行不得包含超過一個語句。

代碼必須使用 4 個空格用于縮進，不得使用制表符用于縮進。

只使用空格，不混用空格和制表符，能夠幫助避免查看差異、打補丁、查看歷史以及批注時潛在的問題。使用空格還讓跨行對齊時插入細粒度的子縮進更加容易。

PHP 保留字必須使用小寫。

PHP 常量 true、false 以及 null 必須使用小寫。

如果存在，必須在 namespace 聲明后加一個空行。

如果存在，所有 use 聲明必須在 namespace 聲明之后。

每個聲明必須要有一個 use 保留字。

在 use 塊之后必須有一個空行。

例如：

4. 類、屬性和方法
術語“類”指代所有的類、接口和 trait。
4.1. Extends 和 Implements
保留字 extends 和 implements 必須與類名位于同一行。
類的起始花括號必須獨自一行；結束花括號必須在內容結束后的下一行。

implements 列表可以分割為多行，這些行縮進一次。當這樣做時，第一個條目必須在下一行，且每行必須只包含一個接口。

4.2. 屬性
必須為所有屬性聲明訪問控制。
不得使用保留字 var 聲明屬性。
一條語句不得聲明超過一個屬性。
不應該使用單個下劃線作為 protected 或 private 屬性的訪問控制的前綴。
屬性聲明看類似下面的例子。

4.3. 方法
必須為所有方法聲明訪問控制。
不應該使用單個下劃線作為 protected 或 private 方法的訪問控制的前綴。
方法名后不得使用空格。左花括號必須獨占一行，右花括號必須在內容之后的行。左括號后不得緊接一個空格，右括號前不得放置一個空格。
方法的聲明類似下面的示例。請留意其中括號、逗號、空格以及花括號的位置：

4.4. 方法參數
參數列表中，每個逗號之前不得有空格，逗號之后必須跟著一個空格。
具有默認值的方法參數必須位于參數列表的最后面。

參數列表可以分割為多行，這些行只需縮進一次。當使用這種方式的時候，列表中的第一個參數必須位于新行，且每行必須只包含一個參數。
當參數列表被分割為多行時，右括號和左花括號必須放在同一行，中間用一個空格隔開。

4.5. abstract、final 以及 static

如果存在，abstract 和 final 聲明必須出現在訪問控制聲明之前。
如果存在，static 聲明必須出現在訪問控制聲明之后。

4.6. 方法和函數調用
當進行一個方法或函數調用時，在方法名或函數名與左括號之間不得用空格隔開，左括號之后不得有空格。參數列表中，每個逗號前不得有空格，每個逗號之后必須有個空格。
bar($arg1);
Foo::bar($arg2, $arg3);
參數列表可以分割為多行，這些行只需縮進一次。當使用這種方式的時候，列表中的第一個參數必須位于新行，且每行必須只包含一個參數。
bar(
    $longArgument,
    $longerArgument,
    $muchLongerArgument
);
5. 控制結構
與控制結構相關的基本樣式原則如下：

控制結構保留字之后必須有一個空格

左括號之后不得有空格

右括號之前不得有空格

右括號和左花括號直接必須有一個空格

結構體必須縮進一次

右花括號必須在內容后的下一行


每個結構的內容必須使用花括號包裹。這能讓控制結構看起來更加標準，并能減少向結構體中加入新語句導致錯誤的可能性。
5.1. if、elseif 和 else

一個 if 結構看起來形如下面的示例。請留意其中括號、空格以及花括號的位置；留意 else 和 elseif 與之前內容的右花括號位于同一行。

應該使用保留字 elseif 代替 else if，這樣，所有控制結構的保留字看起來都是單個單詞。
5.2. switch 和 case

一個 switch 結構看起來形如下面的示例。請留意其中括號、空格以及花括號的位置。case 語句必須相對 switch 縮進一次，保留字 break (或其它用于終止的保留字)必須與 case 塊的縮進層次相同。當 case 塊中穿透行為是設計需要的時候，必須添加類似 // no break 的注釋。

5.3. while 和 do while

一個 while 語句看起來形如下面的示例。請留意其中括號、空格以及花括號的位置。

類似的，do while 語句看起來形如下面的示例。請留意其中括號、空格以及花括號的位置。

5.4. for

一個 for 語句看起來形如下面的示例。請留意其中括號、空格以及花括號的位置。

5.5. foreach

一個 foreach 語句看起來形如下面的示例。請留意其中括號、空格以及花括號的位置。
 $value) {
    // foreach body
}
5.6. try 和 catch

一個 try catch 塊看起來形如下面的示例。請留意其中括號、空格以及花括號的位置。

6. 閉包
閉包聲明中保留字 function 之后必須有一個空格，保留字 use 前后必須各有一個空格。
左花括號必須與閉包聲明同一行，右花括號必須在內容結束后另起一行。
參數表和變量表的左括號之后不得留空格，右括號之前不得留空格。
參數表和變量表中逗號之前不得留空格，逗號之后必須留有一個空格。
閉包中具有默認值的參數必須位于參數表的最后。
一個閉包聲明看起來形如下面的示例。請留意其中括號、逗號、空格以及花括號的位置。
$closureWithArgs = function ($arg1, $arg2) {
    // body
};

$closureWithArgsAndVars = function ($arg1, $arg2) use ($var1, $var2) {
    // body
};
參數表和變量表可以跨行書寫，后續的行縮進一次。當這么做時，每行必須只包含一個參數或變量。
當最后的列表（不管是參數表還是變量表）跨行書寫時，右括號和左花括號必須放在同一行，用一個空格隔開。
下面的示例分別展示了參數表和變量表跨行書寫的各種情況下應該是怎樣的。

請注意這條格式規則也適用于閉包被直接在函數或方法調用中作為參數的情況。
bar(
    $arg1,
    function ($arg2) use ($var1) {
        // body
    },
    $arg3
);
7. 后記
這份規范有意的忽略了一些樣式和實踐準則，這些內容包括但不限于：

全局變量和全局常量的聲明

函數的聲明

操作符和賦值

跨行對齊

注釋和文檔塊

類名的前綴和后綴

最佳實踐


后續的推薦標準可以修訂和擴展這份指南來涵蓋這部分或更多其它的樣式和實踐準則。
附錄 A：問卷調查
在起草這份指南是，PHP FIG 小組對其有成員項目進行了問卷調查以決定哪些實踐行為是最普遍的。原文在附錄中包含了問卷調查的情況，譯文略。