代碼風格指南

翻譯自：

https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md

PSR-2 在 PSR-1 的基礎上進行了繼承和擴展

1. 概述

代碼 必須 遵循 PSR-1 規範

代碼 必須 使用 4個空格 的縮進，而不是製表符 tab

一行代碼長度 不可 有硬性限制，軟限制必須爲120個字符，也應當是80個字符或者更少

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

類的開始花括號 必須 放到下一行，結束花括號 必須 放在類主體的下一行

方法的開始花括號 必須 放在下一行，結束花括號 必須 放在方法主體下面

所有的屬性和方法的可見性 必須 顯式(譯者注：Public, Protect, Private)聲明，abstract 和 final 聲明必須在顯式聲明可見性之前，static 聲明必須在顯式聲明可見性之後

控制結構（譯者注：for，while 等）的關鍵詞 必須 在後面有一個空格；方法和函數 必須 沒有

控制結構（譯者注：for，while 等）的開始花括號 必須 放在同一行，結束花括號 必須 放在控制主體的下一行

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

1.1. 示例

對於上述規則的一些示例：

<?php
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. 常規

2.1 基礎編碼規範

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

2.2 文件

所有的 PHP 文件 必須 使用 Unix LF (換行)作爲行結束符

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

只有 PHP 代碼的文件關閉標籤 ?> 必須 省略

2.3 行

每行的長度 不可 有硬性限制

每行長度的軟限制必須是 120 個字符，對於軟限制，自動樣式檢查器 必須 警告但 不可 報錯

每行實際長度 不應該 超過 80 個字符，較長的行 應該 被拆分成多個不超過 80 個字符的後續行

在非空行後面 不可 有空格

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

每行 不可 多於一個語句

2.4 縮進

代碼 必須 使用 4個空格 的縮進，並且 不可 使用製表符 tab 作爲縮進

注意：只用空格，不與製表符 tab 混合使用，將會對避免代碼差異，補丁，歷史和註解中的一些問題有幫助。使用空格還可以使調整細微的縮進來改進行間對齊變得簡單

2.5 關鍵詞 `keywords` 和 `True/False/Null`

PHP 的關鍵詞 keywords 必須 用小寫

PHP 中的常量 true，false，null 必須 全部小寫

3. `Namespace` 和 `Use` 聲明

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

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

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

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

例：

<?php
namespace Vendor\Package;

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

// ... additional PHP code ...

4. 類 `class`，屬性 `property`，方法 `method`

類 class 指所有的類 class，接口 interface 和特性 trait

4.1. 繼承 `extends` 和接口實現 `implements`

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

類的開始花括號 必須 放在下面自成一行，結束花括號 必須 放在類主體的後面自成一行

<?php
namespace Vendor\Package;

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

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

接口實現 implements 的列表 可以 被拆分爲多個有一次縮進的後續行。如果這麼做，接口列表的第一個接口名 必須 要放在下一行，並且每行 必須 只有一個接口。

<?php
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. 屬性 `property`

所有的屬性 必須 顯式聲明可見性

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

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

屬性名稱 不應該 使用單個下劃線作爲前綴來表明保護或私有的可見性

一個屬性聲明應該像這樣：

<?php
namespace Vendor\Package;

class ClassName
{
    public $foo = null;
}

4.3. 方法 `method`

所有的方法 必須 顯式聲明可見性

方法名 不應該 使用單個下劃線作爲前綴來表明保護或私有的可見性

方法名在聲明之後 不可 跟隨一個空格。開始花括號 必須 放在下面自成一行，並且結束花括號 必須 放在方法主體的下面自成一行

左括號後面 不可 有空格，右括號前面 不可 有空格

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

<?php
namespace Vendor\Package;

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

4.4. 方法參數 `Method Arguments`

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

方法中有默認值的參數 必須 放在參數列表的最後面

<?php
namespace Vendor\Package;

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

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

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

<?php
namespace Vendor\Package;

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

4.5. `abstract`，`final` 和 `static`

如果存在，abstract 和 final 聲明 必須 放在可見性聲明之前

如果存在，static 聲明 必須 放在可見性聲明後一個

<?php
namespace Vendor\Package;

abstract class ClassName
{
    protected static $foo;

    abstract protected function zim();

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

4.6. 方法 `method` 和函數 `function` 調用

當進行函數或方法調用的時候，在方法或者函數名與左括號之間 不可 有空格，左括號之後 不可 有空格，右括號之前 不可 有空格

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

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

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

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

5. 控制結構 `Control Structures`

對於控制結構通常的樣式規則如下：

控制結構關鍵詞之後 必須 有一個空格

左括號之後 不可 有空格

右括號之前 不可 有空格

在右括號和開始花括號之間 必須 有一個空格

代碼主體 必須 有一次縮進

結束花括號 必須 在主體的下一行

結構的主體部分 必須 被括在花括號裏，這使結構體看起來更加標準，減少了在主體部分中加入新行時出現錯誤的可能

5.1. `if`，`elseif`，`else`

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

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

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

5.2. `switch`，`case`

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

<?php
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`

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

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

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

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

5.4. `for`

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

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

5.5. `foreach`

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

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

5.6. `try`，`catch`

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

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

6. 閉包 `Closures`

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

開始花括號 必須 與 function 在同一行，結束花括號 必須 在主體的下一行

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

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

閉包帶默認值的參數 必須 放在參數列表後面

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

<?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. 結論

該指南中有很多風格的元素和做法被故意忽略掉。這些包括下面的等等：

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

方法聲明

操作符和賦值

行間對齊

註釋和文檔塊

類名給你前綴和後綴

最佳實踐

敲了快兩個小時。。要瘋了（生無可戀）。。

Arno_好久不見

發佈了29 篇原創文章 · 獲贊 5 · 訪問量 5萬+

私信關注

PSR-2 代碼風格指南

代碼風格指南

1. 概述

1.1. 示例

2. 常規

2.1 基礎編碼規範

2.2 文件

2.3 行

2.4 縮進

2.5 關鍵詞 keywords 和 True/False/Null

3. Namespace 和 Use 聲明

4. 類 class，屬性 property，方法 method

4.1. 繼承 extends 和接口實現 implements

4.2. 屬性 property

4.3. 方法 method

4.4. 方法參數 Method Arguments

4.5. abstract，final 和 static

4.6. 方法 method 和函數 function 調用

5. 控制結構 Control Structures

5.1. if，elseif，else

5.2. switch，case

5.3. while，do while

5.4. for

5.5. foreach

5.6. try，catch

6. 閉包 Closures