PSR-2 代碼風格規範

代碼風格規範

本篇規範是PSR-1 基本代碼規範的繼承與擴充。

本規範希望通過制定一系列正常化PHP代碼的規則，以減少在瀏覽不同作者的代碼時，因代碼風格的不同而造成不便。

當多名程式員在多重專案中合作時，就需要一個共同的編碼規範，

而本文中的風格規範源自於多個不同項目代碼風格的共同特性，

因此，本規範的價值在於我們都遵循這個編碼風格，而不是在於它本身。

1. 概覽

• 代碼 必須遵循PSR-1 中的編碼規範 。

• 代碼 必須使用4個空格符而不是 tab鍵 進行縮排。

• 每行的字元數 應該軟性保持在80個之內， 理論上 一定不可多於120個， 但 一定不能有硬性限制。

• 每個 namespace命名空間聲明語句和 use聲明語句塊後面， 必須插入一個空白行。

• 類的開始花括弧( {) 必須寫在函式宣告後自成一行，結束花括弧( })也 必須寫在函數主體後自成一行。

• 方法的開始花括弧( {) 必須寫在函式宣告後自成一行，結束花括弧( })也 必須寫在函數主體後自成一行。

• 類的屬性和方法 必須添加存取修飾詞（ private、 protected以及 public）， abstract以及 final 必須聲明在存取修飾詞之前，而 static 必須聲明在存取修飾詞之後。

• 控制結構的關鍵字後 必須要有一個空格符，而調用方法或函數時則 一定不能有。

• 控制結構的開始花括弧( {) 必須寫在聲明的同一行，而結束花括弧( }) 必須寫在主體後自成一行。

• 控制結構的開始左括弧後和結束右括弧前，都 一定不能有空格符。

1.1. 例子

以下例子程式簡單地展示了以上大部分規範：

 $b) {            $foo->bar($arg1);        } else {            BazClass::bar($arg2, $arg3);        }    }    final public static function bar()    {        // method body    }}

1. 通則

2.1 基本編碼準則

代碼 必須符合PSR-1 中的所有規範。

2.2 檔案

所有PHP檔案 必須使用 Unix LF (linefeed)作為行的結束符。

所有PHP檔案 必須以一個空白行作為結束。

純PHP代碼檔案 必須省略最後的 ?>結束標籤。

2.3. 行

行的長度 一定不能有硬性的約束。

軟性的長度約束 一定要限制在120個字元以內，若超過此長度，帶代碼規範檢查的編輯器 一定要發出警告，不過 一定不可發出錯誤提示。

每行 不應該多於80個字元，大於80字元的行 應該折成多行。

非空行後 一定不能有多餘的空格符。

空行 可以使得閱讀代碼更加方便以及有助於代碼的分塊。

每行 一定不能存在多於一條語句。

2.4. 縮排

代碼 必須使用4個空格符的縮排， 一定不能用 tab鍵 。

備忘: 使用空格而不是tab鍵縮排的好處在於，

避免在比較代碼差異、打補丁、重閱代碼以及注釋時產生混淆。

並且，使用空格縮排，讓對齊變得更方便。

2.5. 關鍵字 以及 True/False/Null

PHP所有 關鍵字 必須全部小寫。

常量 true、 false和 null也 必須全部小寫。

1. namespace 以及 use 聲明

namespace聲明後 必須 插入一個空白行。

所有 use必須 在 namespace後聲明。

每條 use聲明語句 必須 只有一個 use關鍵詞。

use聲明語句塊後 必須 要有一個空白行。

例如：

    
 
         
  
類、屬性和方法
    
 
    
此處的“類”泛指所有的class類、介面以及traits可複用代碼塊。
    
4.1. 擴充與繼承
    
關鍵詞 extends和 implements 必須寫在類名稱的同一行。 
    
類的開始花括弧 必須獨佔一行，結束花括弧也 必須在類主體後獨佔一行。 
    
    
 implements的繼承列表也 可以分成多行，這樣的話，每個繼承介面名稱都 必須分開獨立成行，包括第一個。 
    
    
4.2. 屬性
    
每個屬性都 必須添加存取修飾詞。 
    
一定不可使用關鍵字 var聲明一個屬性。 
    
每條語句 一定不可定義超過一個屬性。 
    
不要使用底線作為首碼，來區分屬性是 protected 或 private。 
    
以下是屬性聲明的一個範例：
    
    
4.3. 方法
    
所有方法都 必須添加存取修飾詞。 
    
不要使用底線作為首碼，來區分方法是 protected 或 private。 
    
方法名稱後 一定不能有空格符，其開始花括弧 必須獨佔一行，結束花括弧也 必須在方法主體後單獨成一行。參數左括弧後和右括弧前 一定不能有空格。 
    
一個標準的方法聲明可參照以下範例，留意其括弧、逗號、空格以及花括弧的位置。
    
    
4.4. 方法的參數
    
參數列表中，每個逗號後面 必須要有一個空格，而逗號前面 一定不能有空格。 
    
有預設值的參數， 必須放到參數列表的末尾。 
    
    
參數列表 可以分列成多行，這樣，包括第一個參數在內的每個參數都 必須單獨成行。 
    
拆分成多行的參數列表後，結束括弧以及方法開始花括弧 必須 寫在同一行，中間用一個空格分隔。
    
    
4.5. abstract、 final、 以及 static 
    
需要添加 abstract或 final聲明時， 必須寫在存取修飾詞前，而 static則 必須寫在其後。 
    
    
4.6. 方法及函數調用
    
方法及函數調用時，方法名或函數名與參數左括弧之間 一定不能有空格，參數右括弧前也 一定不能有空格。每個參數前 一定不能有空格，但其後 必須有一個空格。 
    
bar($arg1);Foo::bar($arg2, $arg3);
    
參數 可以分列成多行，此時包括第一個參數在內的每個參數都 必須單獨成行。 
    
bar(    $longArgument,    $longerArgument,    $muchLongerArgument);
    
        
         
         
控制結構
    
        
    
控制結構的基本規範如下：
    
        
         
         
控制結構關鍵詞後 必須有一個空格。 
     
         
左括弧 (後 一定不能有空格。 
     
         
右括弧 )前也 一定不能有空格。 
     
         
右括弧 )與開始花括弧 {間 一定有一個空格。 
     
         
結構體主體 一定要有一次縮排。 
     
         
結束花括弧 } 一定在結構體主體後單獨成行。 
    
        
    
         
每個結構體的主體都 必須被包含在成對的花括弧之中， 
     
這能讓結構體更加結構話，以及減少加入新行時，出錯的可能性。
    
    
5.1. if、 elseif和 else 
    
         
標準的 if結構如下代碼所示，留意 括弧、空格以及花括弧的位置， 
     
注意 else和 elseif都與前面的結束花括弧在同一行。 
    
    
    
應該使用關鍵詞 elseif代替所有 else if，以使得所有的控制關鍵字都像是單獨的一個詞。 
    
5.2. switch和 case 
    
         
標準的 switch結構如下代碼所示，留意括弧、空格以及花括弧的位置。 
     
 case語句 必須相對 switch進行一次縮排，而 break語句以及 case內的其它語句都 必須 相對 case進行一次縮排。 
     
如果存在非空的 case直穿語句，主體裡必須有類似 // no break的注釋。 
    
    
    
5.3. while和 do while 
    
一個規範的 while語句應該如下所示，注意其 括弧、空格以及花括弧的位置。 
    
    
標準的 do while語句如下所示，同樣的，注意其 括弧、空格以及花括弧的位置。 
    
    
5.4. for 
    
標準的 for語句如下所示，注意其 括弧、空格以及花括弧的位置。 
    
    
5.5. foreach 
    
標準的 foreach語句如下所示，注意其 括弧、空格以及花括弧的位置。 
    
 $value) {    // foreach body}
    
5.6. try, catch 
    
標準的 try catch語句如下所示，注意其 括弧、空格以及花括弧的位置。 
    
    
              
         
               
閉包
    
              
    
閉包聲明時，關鍵詞 function後以及關鍵詞 use的前後都 必須要有一個空格。 
    
開始花括弧 必須寫在聲明的同一行，結束花括弧 必須緊跟主體結束的下一行。 
    
參數列表和變數列表的左括弧後以及右括弧前， 必須不能有空格。 
    
參數和變數列表中，逗號前 必須不能有空格，而逗號後 必須要有空格。 
    
閉包中有預設值的參數 必須放到列表的後面。 
    
標準的閉包聲明語句如下所示，注意其 括弧、逗號、空格以及花括弧的位置。
    
    
參數列表以及變數列表 可以分成多行，這樣，包括第一個在內的每個參數或變數都 必須單獨成行，而列表的右括弧與閉包的開始花括弧 必須放在同一行。 
    
以下幾個例子，包含了參數和變數列表被分成多行的多情況。
    
    
注意，閉包被直接用作函數或方法調用的參數時，以上規則仍然適用。
    
bar(    $arg1,    function ($arg2) use ($var1) {        // body    },    $arg3);
    
                
         
                 
總結
    
                
    
以上規範難免有疏忽，其中包括但不僅限於：
    
                
         
                 
 
全域變數和常量的定義
 
     
                 
 
函數的定義
 
     
                 
 
操作符和賦值
 
     
                 
 
行內對齊
 
     
                 
 
注釋和文檔描述塊
 
     
                 
 
類名的首碼及尾碼
 
     
                 
 
最佳實務
 
    
                
    
本規範之後的修訂與擴充將彌補以上不足。
