FIG-PHP PSR規範系列1-基礎編碼規範

1. FIG-PHP與PSR簡介

FIG-PHP制定了一系列PHP開發規範，簡稱PSR，這裡FIG是架構互操作工作群組（Framework Interoperability Group）的簡稱，PSR是PHP標準推薦（PHP Standard Recommendation）的縮寫。FIG-PHP工作群組最初是源於項目代表討論兩個項目之間的共性時，找出可以共事的方式。主要的受眾是雙方項目組，但PHP界的其他人也在觀望。如果其他人願意採用這裡的規範，那麼歡迎，但這並非工作群組的目標。工作群組中沒人會告訴你如何來建造應用。

截止到2015.07, PSR共有五個規範文檔發布，分別是：

PSR-0 自動載入（2014.10.21被廢棄，替代規範為PSR-4）

PSR-1 基礎編碼規範

PSR-2 編碼風格

PSR-3 日誌介面

PSR-4 改進的自動載入

PSR-7 HTTP訊息介面

下面將分多個系列來學習這些規範, 本文檔是系列1。

2. PSR-1: 基礎編碼規範

本規範討論一些基礎的代碼規範，以便將來代碼共用時不同代碼之間能有更高程度的技術互操作。

本規範中的必須(MUST)，不可(MUST NOT)，應當(SHOULD)，不應當(SHOULD NOT)，可以/可能(MAY)等關鍵詞的含義可參見RFC 2119。

2.1 概述

源檔案必須（MUST）只使用

源檔案中php代碼的編碼格式必須（MUST）只使用不帶位元組順序標記(BOM)的UTF-8。備忘：更多BOM資料可參見參考資料[BOM]。

一個源檔案建議只用來做聲明（類(class)，函數(function)，常量(constant)等）或者只用來做一些輔助作用的操作（例如：輸出資訊，修改.ini配置等）,但不應當（SHOULD NOT）同時做這兩件事。

命名空間(namespace)和類(class) 必須遵循一種PSR自動載入規範: PSR-0或PSR-4。（譯者註：由於PSR-0已經被廢棄，因此這裡事實上等同於必須遵循PSR-4規範。）

類名(class name) 必須使用StudlyCaps寫法。

（譯者註：參見參考資料[StudlyCaps]， StudlyCaps是一種大小寫字母可任意變化，其中一些字母可被忽略的一種寫法。例如訊息可能隱藏在大寫字母與小寫字母中，例如"ShoEboX"大寫字母可拼出"SEX", 小寫祖母可拼出"hobo", webmail服務商Hotmail最初被寫為HoTMaiL, 大寫字母可拼出HTML。）

類(class)中的常量必須只由大寫字母和底線(_)組成。

方法名(method name) 必須使用camelCase（駝峰式)寫法。

2.2 檔案

2.2.1 PHP標籤

PHP代碼必須只使用長標籤()或者短輸出式標籤()；而不可使用其他標籤。

2.2.2 字元編碼

PHP代碼的編碼格式必須只使用不帶位元組順序標記(BOM)的UTF-8。

2.2.3 輔助作用

一個源檔案建議只用來做聲明（類(class)，函數(function)，常量(constant)等）或者只用來做一些輔助作用的操作（例如：輸出資訊，修改.ini配置等）,但不建議同時做這兩件事。

短語 輔助作用(side effects)的意思是與聲明（類(class)，函數(function)，常量(constant)等）沒有直接關係的一些執行邏輯。

（譯者註：[PSR-1-翻譯1]中將side effects翻譯為副作用，[PSR-1-翻譯2]中翻譯為從屬效應 , 都感覺不知所云，這裡翻譯為輔助作用應當更好）。

（譯者註：原文中的merely from including the file沒有弄清楚是什麼意思，留待以後確認）。

輔助作用包含但不局限於：產生輸出，顯式地使用require或include，串連外部服務，修改ini配置，觸發錯誤或異常，修改全域或者靜態變數，讀取或修改檔案等等。

下面是一個既包含聲明又有輔助作用的樣本檔案；即應避免的例子：

\n";// 聲明function foo(){    // 函數體}

下面是一個僅包含聲明的樣本檔案；即應提倡的例子：

  
2.3 空間名(namespace)和類名(class name)
  
    命名空間(namespace)和類(class)必須遵循一種自動載入規範PSR-0或PSR-4.
  
    這意味著一個源檔案中只能有一個類(class)，並且在命名空間中至少要有一級：即一個頂級的組織名(vendor name)。
  
   類名(class name) 必須使用StudlyCaps寫法。
  
   PHP5.3之後的代碼必須使用正式的命名空間(namespace) 
  
例子：
  
  

  
PHP5.2.x之前的代碼建議用偽命名空間Vendor_作為類名(class name)的首碼
  
  

  
2.4 類的常量、屬性和方法
  
    術語類(class)指所有的類(class)，介面(interface)和trait。
  
2.4.1 常量
  
    類常量必須（MUST）只由大寫字母和底線(_)組成。 例子：
  
  
2.4.2 屬性
  
    類的屬性命名可以遵循$StulyCaps，$camelCase或者$under_score中的某一種風格，本規範不做強制要求，但無論遵循哪種命名方式，都應當（SHOULD）在一定的範圍內保持一致。這個範圍可以是整個團隊、整個包、整個類或整個方法。
  
2.4.3 方法
  
    方法名必須（MUST）使用camelCase風格來聲明。
 3. 參考資料  
  
[BOM] 一個bom頭引發的血案, 
  
[PHP-FIG] php-fig, http://www.php-fig.org/
  
[PSR-1-翻譯1] PSR-1基本代碼規範, https://github.com/hfcorriez/fig-standards/blob/zh_CN/%E6%8E%A5%E5%8F%97/PSR-1-basic-coding-standard.md
  
[PSR-1-翻譯2] PHP PSR-1 基本代碼規範(中文版), http://segmentfault.com/a/1190000002521577
  
[PSR-4] FIG-PHP PSR規範系列4-自動載入, 
  
[RFC2119] Key words for use in RFCs to Indicate Requirement Levels, March 1997, http://www.ietf.org/rfc/rfc2119.txt
  
[RFC2119-阮一峰] RFC2119：表示要求的動詞, http://www.ruanyifeng.com/blog/2007/03/rfc2119.html 
  
[StudlyCaps] Studly caps, https://en.wikipedia.org/wiki/Studly_caps
