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

翻譯：薛粲
授權(quán)許可：CC BY-NC 4.0

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

《PSR-2：編碼樣式指南》擴展和擴充了《PSR-1：基礎(chǔ)編碼規(guī)范》。

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

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

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

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

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

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

類的左花括號必須在下一行，右花括號必須在內(nèi)容后的下一行。

方法的左花括號必須在下一行，右花括號必須在內(nèi)容后的下一行。

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

在控制結(jié)構(gòu)的保留字后必須有一個空格；在方法和函數(shù)調(diào)用之后不得有空格。

控制結(jié)構(gòu)的左花括號必須在同一行，右花括號必須在內(nèi)容后的下一行。

控制結(jié)構(gòu)的左括號之后不得有空格，右括號之前不得有空格。

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

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

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

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

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

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

對于只包含 PHP 的文件，必須省略用于指示 PHP 段結(jié)束的 ?> 標(biāo)記。

不得對行寬設(shè)置硬性限制。

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

行不應(yīng)該超過 80 個字符；超過的行應(yīng)該分割為多個不超過 80 個字符的行。

非空的行不得以空白字符結(jié)束。

可以添加空行用于指出代碼塊的關(guān)聯(lián)性以提升代碼的可讀性。

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

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

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

PHP 保留字必須使用小寫。

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

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

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

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

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

例如：

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

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

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

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

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

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

4.5. abstract、final 以及 static

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

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

控制結(jié)構(gòu)保留字之后必須有一個空格

左括號之后不得有空格

右括號之前不得有空格

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

結(jié)構(gòu)體必須縮進一次

右花括號必須在內(nèi)容后的下一行


每個結(jié)構(gòu)的內(nèi)容必須使用花括號包裹。這能讓控制結(jié)構(gòu)看起來更加標(biāo)準(zhǔn)，并能減少向結(jié)構(gòu)體中加入新語句導(dǎo)致錯誤的可能性。
5.1. if、elseif 和 else

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

應(yīng)該使用保留字 elseif 代替 else if，這樣，所有控制結(jié)構(gòu)的保留字看起來都是單個單詞。
5.2. switch 和 case

一個 switch 結(jié)構(gòu)看起來形如下面的示例。請留意其中括號、空格以及花括號的位置。case 語句必須相對 switch 縮進一次，保留字 break (或其它用于終止的保留字)必須與 case 塊的縮進層次相同。當(dāng) case 塊中穿透行為是設(shè)計需要的時候，必須添加類似 // 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 前后必須各有一個空格。
左花括號必須與閉包聲明同一行，右花括號必須在內(nèi)容結(jié)束后另起一行。
參數(shù)表和變量表的左括號之后不得留空格，右括號之前不得留空格。
參數(shù)表和變量表中逗號之前不得留空格，逗號之后必須留有一個空格。
閉包中具有默認(rèn)值的參數(shù)必須位于參數(shù)表的最后。
一個閉包聲明看起來形如下面的示例。請留意其中括號、逗號、空格以及花括號的位置。
$closureWithArgs = function ($arg1, $arg2) {
    // body
};

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

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

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

函數(shù)的聲明

操作符和賦值

跨行對齊

注釋和文檔塊

類名的前綴和后綴

最佳實踐


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