PSR代碼風格指南

代碼風格指南

本手冊是基礎代碼規範(PSR-1)的繼承和擴展。

爲了儘量的提高閱讀其餘人代碼時的效率，下面例舉了一系列的通用規則，特別是有關於PHP代碼風格的。

各個成員項目間的共性組成了這組代碼規範。當開發者們在多個項目中合做時，本指南將會成爲全部這些項目中共用的一組代碼規範。 所以，本指南的益處不在於這些規則自己，而在於在全部項目中共用這些規則。

RFC 2119中的必須(MUST)，不可(MUST NOT)，建議(SHOULD)，不建議(SHOULD NOT)，能夠/可能(MAY)等關鍵詞將在本節用來作一些解釋性的描述。

1. 概述

• 代碼必須遵照 PSR-1。

• 代碼必須使用4個空格來進行縮進，而不是用製表符。

• 一行代碼的長度不建議有硬限制；軟限制必須爲120個字符，建議每行代碼80個字符或者更少。

• 在命名空間(namespace)的聲明下面必須有一行空行，而且在導入(use)的聲明下面也必須有一行空行。

• 類(class)的左花括號必須放到其聲明下面自成一行，右花括號則必須放到類主體下面自成一行。

• 方法(method)的左花括號必須放到其聲明下面自成一行，右花括號則必須放到方法主體的下一行。

• 全部的屬性(property)和方法(method) 必須有可見性聲明；抽象(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. 結論

本指南有意的省略了許多元素的代碼風格。主要包括：

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

• 函數聲明

• 操做符和賦值

• 行間對齊

• 註釋和文檔塊

• 類名的前綴和後綴

• 最佳實踐

之後的代碼規範中可能會修正或擴展本指南中規定的代碼風格。