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

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

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

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

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

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

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

代碼必須使用 4 個(gè)空格而不是制表符作為縮進(jìn)。

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

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

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

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

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

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

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

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

這個(gè)例子作為一個(gè)簡(jiǎn)明的示例，涵蓋了一些后面提及的規(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 源文件必須以一個(gè)空行結(jié)束。

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

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

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

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

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

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

一行不得包含超過(guò)一個(gè)語(yǔ)句。

代碼必須使用 4 個(gè)空格用于縮進(jìn)，不得使用制表符用于縮進(jìn)。

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

PHP 保留字必須使用小寫(xiě)。

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

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

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

每個(gè)聲明必須要有一個(gè) use 保留字。

在 use 塊之后必須有一個(gè)空行。

例如：

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

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

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

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

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

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

4.5. abstract、final 以及 static

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

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

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

左括號(hào)之后不得有空格

右括號(hào)之前不得有空格

右括號(hào)和左花括號(hào)直接必須有一個(gè)空格

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

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


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

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

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

一個(gè) switch 結(jié)構(gòu)看起來(lái)形如下面的示例。請(qǐng)留意其中括號(hào)、空格以及花括號(hào)的位置。case 語(yǔ)句必須相對(duì) switch 縮進(jìn)一次，保留字 break (或其它用于終止的保留字)必須與 case 塊的縮進(jìn)層次相同。當(dāng) case 塊中穿透行為是設(shè)計(jì)需要的時(shí)候，必須添加類似 // no break 的注釋。

5.3. while 和 do while

一個(gè) while 語(yǔ)句看起來(lái)形如下面的示例。請(qǐng)留意其中括號(hào)、空格以及花括號(hào)的位置。

類似的，do while 語(yǔ)句看起來(lái)形如下面的示例。請(qǐng)留意其中括號(hào)、空格以及花括號(hào)的位置。

5.4. for

一個(gè) for 語(yǔ)句看起來(lái)形如下面的示例。請(qǐng)留意其中括號(hào)、空格以及花括號(hào)的位置。

5.5. foreach

一個(gè) foreach 語(yǔ)句看起來(lái)形如下面的示例。請(qǐng)留意其中括號(hào)、空格以及花括號(hào)的位置。
 $value) {
    // foreach body
}
5.6. try 和 catch

一個(gè) try catch 塊看起來(lái)形如下面的示例。請(qǐng)留意其中括號(hào)、空格以及花括號(hào)的位置。

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

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

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

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

函數(shù)的聲明

操作符和賦值

跨行對(duì)齊

注釋和文檔塊

類名的前綴和后綴

最佳實(shí)踐


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