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

阿新 • • 發佈：2018-10-04

sam HERE else may echo 調用方法 try catch 標準化小寫字母

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 （中文版）

sam HERE else may echo 調用方法 try catch 標準化小寫字母 PHP 代碼風格規範 PSR-2 本篇規範是 PSR-1 基本代碼規範的繼承與擴展。本規範希望通過制定一系列規範化PHP代碼的規則，以減少在瀏覽不同作者的代碼時，因代碼風格的不

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