PHP的PSR規格中文版_php基礎

文件倉庫位址：https://github.com/hfcorriez/fig-standards

PSR規範中文版

• PSR-0自動載入
• PSR-1基本程式碼規範
• PSR-2程式碼樣式
• PSR-3日誌介面

為何規範

摘錄翻譯了官方的一句話本組織旨在透過討論我們程式碼專案的共同點以找出一個協作程式設計的方法。

在此想到了一篇文章《Google為何要執行嚴格的代碼規範》中有這麼一段話：

複製程式碼 程式碼如下:

在谷歌，我可以查看任何的程式碼，進入所有谷歌的程式碼庫，我有權查看它們。事實上，這種權限是很少人能擁有的。但是，讓我感到驚訝的卻是，如此多的編碼規範—縮進，命名，文件結構，註釋風格—這一切讓我出乎意料的輕鬆的閱讀任意一段代碼，並輕易的看懂它們。這讓我震驚—因為我以為這些規範是微不足道的東西。它們不可能有這麼大的作用—但它們卻扮演了這麼大的角色。當你發現只要透過看程式的基本語法結構就能讀懂一段程式碼，這種時間上的節省不能不讓人震撼！

各位看官我就不用多說關於規範的事情了。

寫在最後
規範不是義務的，當然你也可以選擇自己的方式，但使用規範會讓你的合作更輕鬆。如今各種更現代化應用的編寫已不像從前，一個應用一般都有非常多的模組組成，如果不執行規範，只會讓整個專案的理解和溝通更加複雜。

若使用了規範，對專案和自己的好處當然不言而喻的。

所有已接受的規範參考：https://github.com/ hfcorriez/fig-standards/tree/zh_CN/接受

程式碼樣式規格

本指南的意圖是為了減少不同開發者在瀏覽程式碼時減少認知的差異。為此列舉一組如何格式化PHP程式碼的共用規則。
各個成員項目的共通性組成了本文的樣式規則。當不同的開發者在不同的專案中合作時，將會在這些不同的專案中使用一個共同的標準。因此，本指南的好處不在於規則本身，而在於共用這些規則。
在RFC 2119中的特性關鍵字"必須"(MUST)，「不可」(MUST NOT)，「必要」(REQUIRED)，「將會」(SHALL)，「不會」(SHALL NOT)， 「應當」(SHOULD)，「不應」(SHOULD NOT)，「推薦」(RECOMMENDED)，「可以」(MAY)和「可選」(OPTIONAL)在這文檔中將被用來描述。

1. 大綱

程式碼必須遵守 PSR-1。

程式碼必須使用4個空格的縮排，而不是製表符。
一行程式碼長度不應硬性限制；軟限制必須為120個字元；也應是80個字元或更少。
在namespace聲明下面必須有一個空白行，而use宣告程式碼區塊下方也必須有一個空行。
類別的左花括號必須放到下一行，右花括號必須放在類別主體的下一行。
方法的左花括號必須放在下一行，右花括號必須放在方法主體下方。
所有的屬性和方法必須有可見性(譯者註：Public, Protect, Private)聲明；abstract和final聲明必須在可見性之前；static聲明必須在可見性之後。
控制結構的關鍵字必須在後面有一個空格； 方法和函數不可有。
控制結構的左花括號必須放在同一行，右花括號必須放在控制主體的下一行。
控制結構的左括號後面不可有空格，右括號之前不可有空格。

1.1. 範例
本範例包含上面的一些規則簡單展示：

複製程式碼 程式碼如下:

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)
    {
     ();
        } elseif ($a > $b) {
            $foo-phpcngt  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個空格的縮排，且不可使用製表符作為縮排。

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

2.5. 關鍵字和 True/False/Null
PHP keywords 必須使用小寫。

PHP常數true, false和null必須使用小寫。

3. Namespace和Use宣告
如果存在，namespace宣告之後必須有一個空白行。

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

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

在use聲明程式碼區塊後面必須有一個空白行。

範例:

複製程式碼 程式碼如下:

namespace Vendor\Package;

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

// ... additional PHP code ...

4. 類，屬性和方法
術語「類」指所有的類，介面和特性（traits）。

4.1. 擴充和繼承
一個類別的extends和implements關鍵字必須和類別名稱在同一行。

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

複製程式碼 程式碼如下:

namespace Vendor\Package;
use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

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

implements一個清單可以被拆分為多個有一次縮排的後續行。如果這麼做，則清單的第一項必須放在下一行，且每行必須只有一個介面。

複製程式碼 程式碼如下:

namespace Vendor\Package;

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

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

4.2. 屬性
所有的屬性必須宣告可見性。

var關鍵字不可用來聲明屬性。

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

屬性名稱不應使用單一底線作為前綴來表示保護或私有的可見性。

一個屬性宣告看起來應該下面的。

複製程式碼 程式碼如下:

namespace Vendor\Package;

class ClassName
{
    public $foo = null;
}

4.3. 方法
所有的方法必須宣告可見性。

方法名稱不應只使用單一底線來表示是保護或私有的可見性。

方法名稱在宣告之後不可跟隨一個空格。左花括號必須放在下面自成一行，且右花括號必須放在方法主體的下方自成一行。左括號後面不可有空格，右括號前面不可有空格。

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

複製程式碼 程式碼如下:

namespace Vendor\Package;

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

4.4. 方法參數
在參數清單中，逗號之前不可有空格，逗號之後必須要有一個空格。

方法中有預設值的參數必須放在參數清單的最後面。

複製程式碼 程式碼如下:

namespace Vendor\Package;

class ClassName
{
    public function foo($arg1, &$arg2, $arg3 = [])
    {
        // meth >

參數清單可以被分成多個有一次縮排的多個後續行。如果這麼做，則清單的第一項必須放在下一行，且每行必須只放一個參數。

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

複製程式碼 程式碼如下:

namespace Vendor\Package;

class ClassName
{
    public function aVeryLongMethodName(
        ClassTypeHint $arg1,
        &$2,
        // method body
    }
}

4.5. abstract，final和 static
如果存在，abstract和final聲明必須放在可見性聲明前面。

如果存在，static聲明必須跟著可見性聲明。

複製程式碼 程式碼如下:

namespace Vendor\Package;

abstract class ClassName
{
    protected static $foo;

    abstract protected function zim();

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

4.6. 呼叫方法和函數
要呼叫一個方法或函數，在方法或函數名稱和左括號之間不可有空格，左括號之後不可有空格，右括號之前不可有空格。函數列表中，逗號之前不可有空格，逗號之後必須有一個空格。

 bar();
$foo->bar($arg1);
Foo::bar($arg2, $arg3);
參數清單可以被分割成多個有一個縮排的後續行。如果這麼做，則清單中的第一項必須放在下一行，而且每一行必須只有一個參數。

複製程式碼 程式碼如下:

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

5. 控制結構
控制結構的樣式規則概括如下：

控制結構關鍵字之後必須有一個空格
左括號之後不可有空格
右括號之前不可有空格
在右括號和左花括號之間必須有一個空格
代碼主體必須有一次縮排
右花括號必須主體的下一行
每個結構的主體必須被括在花括號裡。這個結構看起來更標準化，並且當加新行的時候可以減少引入錯誤的可能性。

5.1. if，elseif，else

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

複製程式碼 程式碼如下:

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

關鍵字elseif應該取代else if使用以保持所有的控制關鍵字像一個字。

5.2. switch，case

一個switch結構看起來應該像下面。注意括號，空格和花括號。 case語句必須從switch處縮排，且break關鍵字（或其他中止關鍵字）必須和case主體縮排在同級。如果一個非空的case主體往下落空則必須有一個類似// no break的註解。

複製程式碼 程式碼如下:

 switch ($expr) {
    case 0:
        echo 'First case, with a break';
break;
    case 1:
         case 1:
        echo 'Second case, which falls through';
        // no     echo 'Third case, return instead of break';
        return;
    default:
         while，do while
一個while語句看起來應該像下面。注意括號，空格和花括號的位置。

複製程式碼 程式碼如下:

 while ($expr) {
    // structure body
}

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

複製程式碼 程式碼如下:

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

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

複製程式碼 程式碼如下:

for ($i = 0; $i     // for body
}

5.5. foreach

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

複製程式碼 程式碼如下:

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

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

複製程式碼 程式碼如下:

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

6. 閉包

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

左花括號必須在同一行，右花括號必須在主體的下一行。

參數清單和變數清單的左括號之後不可有空格，其右括號之前也不可有空格。

在參數清單和變數清單中，逗號之前不可有空格，逗號之後必須有空格。

閉包帶預設值的參數必須放在參數清單後面。

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

複製程式碼 程式碼如下:

$closureWithArgs = function ( $arg1, $arg2) {
    // body
};
$closureWithArgsAndVars = function ($arg1, $arg2) use ($var1, $var2) {
    // body
};

參數和變數清單可以被分成多個帶一次縮排的後續行。如果這麼做，則清單的第一項必須放在下一行，且一行必須只放一個參數或變數。

當最終清單（不管是參數還是變數）被分成多行，右括號和左花括號必須夾帶一個空格放在一起自成一行。

下面是一個參數和變數列表被分割成多行的範例。

複製程式碼 程式碼如下:

 $longArgs_noVars = function (
    $longArgument,
  menth $longerArgument,
  $longArgument,
  ment $longerArgument,
 BR>   // body
};

$noArgs_longVars = function () use (
    $longVar1,
    $longerVar2,
    $muchLongerVar3
) {
   // body
;

>

$longArgs_longVars = function (
    $longArgument,
    $longerArgument,
    $muchLongerArgument
)  >) {
   // body
};

$longArgs_shortVars = function (
    $longArgument,
    $longerArgument,
    $muchLongerArgument
) use ($var1) {
   // body
};

$shortArgs_longVars = function ($arg) use (
    $longVar1,
    $longerVar2,
    $muchLongerVar3
) {
  }; /div>
注意如果在函數或方法中把閉包當作一個參數調用，如上格式規則同樣適用。

複製程式碼 程式碼如下:

 $foo->bar(
    $arg1,
    function ($arg2) use ($var1) {
        // body
    },
    $arg3
div>div>

7. 結論
在該指南中有很多風格的元素和做法有意被忽略掉。這些包括但不局限於：

全域變數和全域常數的宣告

方法宣告

操作符與賦值

行間對齊

註解與文件區塊

類別名稱給你前綴和後綴

最佳實務

以後的建議可以修改和擴展該指南以滿足這些或其他風格的元素和實踐。

附錄A 調查
為了寫這個風格指南，我們採用了調查個項目以確定共同的做法。這個調查在這裡供他人查看。

A.1。調查資料
url，http://www.horde.org/apps/horde/docs/CODING_STANDARDS，http://pear.php.net/manual/en/standards.php，http://solarphp.com /manual/appendix-standards.style，http://framework.zend.com/manual/en/coding-standard.html，http://symfony.com/doc/2.0/contributing/code/standards.html，http ://www.ppi.io/docs/coding-standards.html，https://github.com/ezsystems/ezp-next/wiki/codingstandards，http://book.cakephp.org/2.0/en/contributing /cakephp-coding-conventions.html，https://github.com/UnionOfRAD/lithium/wiki/Spec:-Coding，http://drupal.org/coding-standards，http://code.google.com/ p/sabredav/，http://area51.phpbb.com/docs/31x/coding-guidelines.html，https://docs.google.com/a/zikula.org/document/edit?authkey=CPUCU0Us&hgd=1&id =1fcqb93Sn-hR9c0mkN6m_tyWnmEvo​​swKBtSc0tKkZmJA，http://www.chisimba.com，n/a，https://github.com/Respect/project-info/blob/master/coding-https://github.com/Respect/project-info/blob/master/coding--Bdardar-sample.ES/ a，對象PHP 健身操，http://doc.nette.org/en/coding-standard，http://flow3.typo3.org，https://github.com/propelorm/Propel2/wiki/Coding-Standards ，http： //developer.joomla.org/coding-standards。html
投票，是，是，是，是，是，是，是，是，是，是，是，是，是，是，是，否，否，否，？，是，否，是縮排類型,4,4,4,4,4,製表符,4,製表符,製表符,2,4,製表符,4,4,4,4,4,4,製表符,製表符,4,製表符
line_length_limit_soft,75,75,75,75,no,85,120,120,80,80,80,no,100,80,80,?,?,120, 80,120,no,150
line_length_limit_hard,85,85,85, 85,不,不,不,不,100,?,不,不,不,100,100,?,120,120,不,不,不,不class_names,studly,studly,studly,studly,studly,studly,學習，學習，學習，學習，學習，下一個，學習，降低，學習，學習，學習，學習，學習，學習，學習，學習，學習，學習，學習，學習，學習，學習
class_brace_line，下一個，下一個，下一個，下一個，下一個，相同，下一個，相同，相同，相同，相同，下一個，下一個，下一個，下一個，下一個，下一個，下一個，下一個，相同，下一個，下一個
constant_names，上，上，上，上，上，上，上，上，上，上，上，上，上，上，上，上，上，上，上，上，上，上
true_false_null，下，下，下，下，下，下，下，下，下，上、下、下、下、上、下、下、下、下、下、上、下、下
方法名稱，駱駝，駱駝，駱駝，駱駝，駱駝，駱駝，駱駝，駱駝，駱駝，駱駝，駱駝，lower_under，駱駝，駱駝，駱駝，駱駝，駱駝，駱駝，駱駝，駱駝，駱駝，駱駝
method_brace_line，下一個，下一個，下一個，下一個，下一個，相同，下一個，相同，相同，相同，相同，下一個，下一個，相同，下一個，下一個，下一個，下一個，下一個，相同，下一個，下一個control_brace_line，相同，相同，相同，相同，相同，相同，下一個，相同，相同，相同，相同，下一個，相同，相同，下一個，相同，相同，相同，相同，相同，相同，下一個
control_space_after，是，是，是，是，是，否，是，是，是，是，否，是，是，是，是，是，是，是，是，是，是，是
always_use_control_braces，是，是，是，是，是，是，否，是，是，是，否，是，是，是，是，不，是，是，是，是，是，是
else_elseif_line，相同，相同，相同，相同，相同，相同，下一個，相同，相同，下一個，相同，下一個，相同，下一個，下一個，相同，相同，相同，相同，相同，相同，下一個
case_break_indent_from_switch,0/1,0/1,0/1,1/ 2,1/2,1/2,1/2,1/1, 1/1,1/2,1/2,1/1,1/2,1/2,1/2,1/2, 1/2,1/2,0/1,1/1,1/ 2,1/2
function_space_after,不,不,不,不,不,不,不,不,不,不,不,不,不,不,不,不,不,不,不,不,不，不
close_php_tag_required，不，不，不，不，不，不，不，不，是，不，不，不，不，是，不，不，不，不，不，是，不，無
line_endings,LF,LF,LF,LF,LF,LF,LF,LF,?,LF,?,LF,LF, LF,LF,?,,LF,?,LF,LF,LF
static_or_visibility_first,靜態,?,靜態,任一,任一,任一,可見性,可見性,可見性,任一,靜態,任一,?,可見性,?,?,任一,任一,可見性,可見性,靜態,?
control_space_parens ,不,不,不,不,不,不,是,不,不,不,不,不,不,是,?,不,不,不,不,不,不,不
blank_line_after_php,no ,不,不,不,是,不,不,不,不,是,是,不,不,是,?,是,是,否,是,否,是,否
class_method_control_brace,下一個/下一個/相同，下一個/下一個/相同，下一個/下一個/相同，下一個/下一個/相同，下一個/下一個/相同，相同/相同/相同，下一個/下一個/下一個，相同/相同/相同，相同/相同/相同,相同/相同/相同,相同/相同/相同,下一個/下一個/下一個,下一個/下一個/相同,下一個/相同/相同,下一個/下一個/下一個,下一個/下一個/相同,下一個/下一個/相同,下一個/下一個/相同，下一個/下一個/相同，相同/相同/相同，下一個/下一個/相同，下一個/下一個/下一個
A.2 。調查說明
indent_type: 縮排類型。tab = "使用製表符"，2 or 4 = "空格數量"

line_length_limit_soft: 行長度的「軟」限制，用字元。 ? = 不表示或數字 no 意為不限制.

line_length_limit_hard: 行長度的"硬"限制，用字元。 ? = 不表示或數字, no 意為不限制.

class_names: 類別名稱如何命名 lower = 只是小寫, lower_under = 小寫加底線, studly = 駱駝型.

class_brace_line: 類別的左花括號是放在同(same)一行還是在下(next)一行？

constant_names: 類別常數如何命名？ upper = 大寫加上底線分隔符號。

true_false_null: 全校寫還是全大寫？

method_names: 方法名稱如何命名？ camel = 駝峰式, lower_under = 小寫加上底線分隔符號。

method_brace_line: 方法的左花括號在同(same)一行還是在下(next)一行？

control_brace_line: 控制結構的左花括號在同(same)一行還是在下(next)一行？

control_space_after: 控制結構關鍵字後面是否有空格？

always_use_control_braces: 控制結構總是使用花括號？

else_elseif_line: 使用else和elseif，是否放在同(same)一行或下(next)一行？

case_break_indent_from_switch: case和break分別從swith語句縮排幾次？

function_space_after: 函數呼叫的函數名稱和左括號是否有空格？

closing_php_tag_required: 如過是純PHP文件，關閉標籤?>是否需要？

line_endings: 使用何種的行結束符號？

static_or_visibility_first: 在定義方法的時候static和可見性誰在前面？

control_space_parens: 在控制結構表達式中，左括號後面和右括號前面是否要有一個空格？ yes = if ( $expr ), no =if ($expr).

blank_line_after_php: PHP的開始標籤後面是否需要一個空白行？

class_method_control_brace: 左花括號在類，方法與控制結構中的位置。

A.3。調查結果
indent_type:
    tab: 7
    2: 1
    4: 14
line_length_limit_soft:
    ?: 2
line_length_limit_soft:
    ?: 2
line_length_limit_soft:
  >    80: 6
    85: 1
    100: 1
    120: 4
    150: 1
line_length_limit_hard:    150: 1
line_length_limit_hard:    85: 4
    100: 3
    120: 2
class_names:
    ?: 1
    lower: 1
  
lower_under: 105>下一個: 16
    同上: 6
constant_names:
    上方: 22
true_false_null:
    下部: 19
 : BR >    lower_under: 1
method_brace_line:
    下一個: 15
    相同: 7
control_brace_line:
    是：20
always_use_control_braces：
    否：3
    是：19
else_elseif_line：
    下一個：19
else_elseif_line：
    下一個：6
>    0/1 : 4
    1/1: 4
    1/2: 14
function_space_after:
    否：
line_endings :
    ?: 5
    LF: 17
static_or_visibility_first:
    ?: 5
    任一：7
    ?: 5
    任一：7
    ?: 5
    任一：7
  >control_space_parens:
?: 1
    否: 19
    是: 2
blank_line_after_php:
    ?: 1
  BR>    下一個/下一個/下一個：4
    下一個/下一個/相同：11
    下一個/相同/相同：1
   相同/相同/相同：6