PHP 程式碼風格規範 PSR-2 （中文版）

阿新 • • 發佈：2018-12-13

PHP 程式碼風格規範 PSR-2

本篇規範是 PSR-1 基本程式碼規範的繼承與擴充套件。本規範希望通過制定一系列規範化PHP程式碼的規則，以減少在瀏覽不同作者的程式碼時，因代碼風格的不同而造成不便。當多名程式設計師在多個專案中合作時，就需要一個共同的編碼規範，而本文中的風格規範源自於多個不同專案程式碼風格的共同特性，因此，本規範的價值在於我們都遵循這個編碼風格，而不是在於它本身。

關鍵詞 “必須”("MUST")、“一定不可/一定不能”("MUST NOT")、“需要”("REQUIRED")、 “將會”("SHALL")、“不會”("SHALL NOT")、“應該”("SHOULD

")、“不該”("SHOULD NOT")、 “推薦”("RECOMMENDED")、“可以”("MAY")和”可選“("OPTIONAL")的詳細描述可參見 RFC 2119 。

1. 概述

程式碼必須遵守 PSR-1。
程式碼必須使用4個空格來進行縮排，而不是用製表符。
每行應該保持在80個字元以內，軟限制必須是120個字元，但一定不能有硬性限制。
在名稱空間(namespace)的宣告下面必須有一行空行，並且在匯入(use)的宣告下面也必須有一行空行。
類(class)的左花括號({)必須放到其宣告下面自成一行，右花括號(})則必須放到類主體下面自成一行。
方法(method)的左花括號({

)必須放到其宣告下面自成一行，右花括號(})則必須放到方法主體的下一行。
在所有的屬性和方法上都必須宣告可見性(譯者注：private，protected以及public)；abstract和final必須宣告在可見性之前；static必須宣告在可見性之後。
在控制結構關鍵字的後面必須有一個空格；而方法(method)和函式(function)的關鍵字的後面不可有空格。
控制結構的左花括號必須跟其放在同一行，右花括號必須放在該控制結構程式碼主體的下一行。
控制結構的左括號之後不可有空格，右括號之前也不可有空格。

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()
    {
        // 方法主體
    }
}

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)宣告程式碼塊後面必須有一行空行。

示例：

<?php
namespace Vendor\Package;

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

// ... 其它PHP程式碼 ...

4. 類(class)，屬性(property)和方法(method)

術語“類”指所有的類(class)，介面(interface)和特性(trait)。

4.1. 擴充套件(extend)和實現(implement)

一個類的擴充套件(extend)和實現(implement)關鍵詞必須和類名(class name)在同一行。

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

<?php
namespace Vendor\Package;

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

class ClassName extends ParentClass implements \ArrayAccess, \Countable
{
    // 常量、屬性、方法
}

實現(implement)列表可以被拆分為多個縮進了一次的子行。如果要拆成多個子行，列表的第一項必須要放在下一行，並且每行必須只有一個介面(interface)。

<?php
namespace Vendor\Package;

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

class ClassName extends ParentClass implements
    \ArrayAccess,
    \Countable,
    \Serializable
{
    // 常量、屬性、方法
}

4.2. 屬性(property)

所有的屬性(property)都必須宣告其可見性。

變數(var)關鍵字不可用來宣告一個屬性(property)。

一條語句不可宣告多個屬性(property)。

屬性名(property name) 不推薦用單個下劃線作為字首來表明其保護(protected)或私有(private)的可見性。

一個屬性(property)宣告看起來應該像下面這樣。

<?php
namespace Vendor\Package;

class ClassName
{
    public $foo = null;
}

4.3. 方法(method)

所有的方法(method)都必須宣告其可見性。

方法名(method name) 不推薦用單個下劃線作為字首來表明其保護(protected)或私有(private)的可見性。

方法名(method name)在其聲明後面不可有空格跟隨。其左花括號必須放在下面自成一行，且右花括號必須放在方法主體的下面自成一行。左括號後面不可有空格，且右括號前面也不可有空格。

一個方法(method)宣告看來應該像下面這樣。注意括號，逗號，空格和花括號的位置：

<?php
namespace Vendor\Package;

class ClassName
{
    public function fooBarBaz($arg1, &$arg2, $arg3 = [])
    {
        // 方法主體部分
    }
}

4.4. 方法(method)的引數

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

方法(method)中有預設值的引數必須放在引數列表的最後面。

<?php
namespace Vendor\Package;

class ClassName
{
    public function foo($arg1, &$arg2, $arg3 = [])
    {
        // 方法主體部分
    }
}

引數列表可以被拆分為多個縮進了一次的子行。如果要拆分成多個子行，引數列表的第一項必須放在下一行，並且每行必須只有一個引數。

當引數列表被拆分成多個子行，右括號和左花括號之間必須又一個空格並且自成一行。

<?php
namespace Vendor\Package;

class ClassName
{
    public function aVeryLongMethodName(
        ClassTypeHint $arg1,
        &$arg2,
        array $arg3 = []
    ) {
        // 方法主體部分
    }
}

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()
    {
        // 方法主體部分
    }
}

4.6.

呼叫方法和函式

呼叫一個方法或函式時，在方法名或者函式名和左括號之間不可有空格，左括號之後不可有空格，右括號之前也不可有空格。引數列表中，逗號之前不可有空格，逗號之後則必須有一個空格。

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


引數列表可以被拆分成多個縮進了一次的子行。如果拆分成子行，列表中的第一項必須放在下一行，並且每一行必須只能有一個引數。

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

5.

控制結構

下面是對於控制結構程式碼風格的概括：控制結構的關鍵詞之後必須有一個空格。控制結構的左括號之後不可有空格。控制結構的右括號之前不可有空格。控制結構的右括號和左花括號之間必須有一個空格。控制結構的程式碼主體必須進行一次縮排。控制結構的右花括號必須主體的下一行。每個控制結構的程式碼主體必須被括在花括號裡。這樣可是使程式碼看上去更加標準化，並且加入新程式碼的時候還可以因此而減少引入錯誤的可能性。

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語句必須要縮排一級，而break關鍵字（或其他中止關鍵字）必須和case結構的程式碼主體在同一個縮排層級。如果一個有主體程式碼的case結構故意的繼續向下執行則必須要有一個類似於// 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.

閉包

宣告閉包時所用的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.

以上規範難免有疏忽，其中包括但不僅限於：

全域性變數和全域性常量的宣告
函式宣告
操作符和賦值
行間對齊
註釋和文件塊
類名的字首和字尾
最佳實踐

以後的程式碼規範中可能會修正或擴充套件本指南中規定的程式碼風格。

PHP 程式碼風格規範 PSR-2 （中文版）