PSR-1 · web開發者知識體系

# 基本代碼規范本篇規范制定了代碼基本元素的相關標準，以確保共享的PHP代碼間具有較高程度的技術互通性。關鍵詞 “必須”(“MUST”)、“一定不可/一定不能”(“MUST NOT”)、“需要”(“REQUIRED”)、 “將會”(“SHALL”)、“不會”(“SHALL NOT”)、“應該”(“SHOULD”)、“不該”(“SHOULD NOT”)、 “推薦”(“RECOMMENDED”)、“可以”(“MAY”)和”可選“(“OPTIONAL”)的詳細描述可參見 RFC 2119 。 ## 1. 概覽 PHP代碼文件必須以 <?php 或 <?= 標簽開始； PHP代碼文件必須以不帶BOM的 UTF-8 編碼； PHP代碼中應該只定義類、函數、常量等聲明，或其他會產生從屬效應的操作（如：生成文件輸出以及修改.ini配置文件等），二者只能選其一；命名空間以及類必須符合 PSR 的自動加載規范：PSR-0 或 PSR-4 中的一個；類的命名必須遵循 StudlyCaps 大寫開頭的駝峰命名規范；類中的常量所有字母都必須大寫，單詞間用下劃線分隔；方法名稱必須符合 camelCase 式的小寫開頭駝峰命名規范。 ## 2. 文件 ### 2.1. PHP標簽 PHP代碼必須使用 <?php ?> 長標簽或 <?= ?> 短輸出標簽；一定不可使用其它自定義標簽。 ### 2.2. 字符編碼 PHP代碼必須且只可使用不帶BOM的UTF-8編碼。 ### 2.3. 從屬效應（副作用）一份PHP文件中應該要不就只定義新的聲明，如類、函數或常量等不產生從屬效應的操作，要不就只有會產生從屬效應的邏輯操作，但不該同時具有兩者。 “從屬效應”(side effects)一詞的意思是，僅僅通過包含文件，不直接聲明類、函數和常量等，而執行的邏輯操作。 “從屬效應”包含卻不僅限于：生成輸出、直接的 require 或 include、連接外部服務、修改 ini 配置、拋出錯誤或異常、修改全局或靜態變量、讀或寫文件等。以下是一個反例，一份包含聲明以及產生從屬效應的代碼： <?php // 從屬效應：修改 ini 配置 ini_set('error_reporting', E_ALL); // 從屬效應：引入文件 include "file.php"; // 從屬效應：生成輸出 echo "<html>\n"; // 聲明函數 functionfoo(){ // 函數主體部分 } 下面是一個范例，一份只包含聲明不產生從屬效應的代碼： <?php // 聲明函數 functionfoo(){ // 函數主體部分 } // 條件聲明**不**屬于從屬效應 if (! function_exists('bar')) { functionbar(){ // 函數主體部分 } } ## 3. 命名空間和類命名空間以及類的命名必須遵循 PSR-0. 根據規范，每個類都獨立為一個文件，且命名空間至少有一個層次：頂級的組織名稱（vendor name）。類的命名必須遵循 StudlyCaps 大寫開頭的駝峰命名規范。 PHP 5.3及以后版本的代碼必須使用正式的命名空間。例如： <?php // PHP 5.3及以后版本的寫法 namespace Vendor\Model; class Foo{ } 5.2.x及之前的版本應該使用偽命名空間的寫法，約定俗成使用頂級的組織名稱（vendor name）如 Vendor_ 為類前綴。 <?php // 5.2.x及之前版本的寫法 class Vendor_Model_Foo{ } ## 4. 類的常量、屬性和方法此處的“類”指代所有的類、接口以及可復用代碼塊（traits） ### 4.1. 常量類的常量中所有字母都必須大寫，詞間以下劃線分隔。參照以下代碼： <?php namespace Vendor\Model; class Foo{ const VERSION = '1.0'; const DATE_APPROVED = '2012-06-01'; } ### 4.2. 屬性類的屬性命名可以遵循大寫開頭的駝峰式 ($StudlyCaps)、小寫開頭的駝峰式 ($camelCase) 又或者是下劃線分隔式 ($under_score)，本規范不做強制要求，但無論遵循哪種命名方式，都應該在一定的范圍內保持一致。這個范圍可以是整個團隊、整個包、整個類或整個方法。 ### 4.3. 方法方法名稱必須符合 camelCase() 式的小寫開頭駝峰命名規范。