Zend Framework 的 PHP 編碼通訊協定

[摘自 Zend Framework 官方文檔]  

C.2. PHP File 檔案格式  
C.2.1.  常規  
    對於只包含有 PHP 代碼的檔案，結束標誌（"?>"）是不允許存在的，PHP自身不需要（"?>"）, 這樣做, 可以防止它的末尾的被意外地注入相應。  
    重要： 由 __HALT_COMPILER() 允許的任意的二進位代碼的內容被 Zend Framework 中的 PHP 檔案或由它們產生的檔案禁止。這個功能的使用只對一些安裝指令碼開放。 

C.2.2.  縮排 
    縮排由四個空格組成，禁止使用定位字元 TAB 。 

C.2.3.  行的最大長度  
    一行 80 字元以內是比較合適，就是說，ZF 的開發人員應當努力在可能的情況下保持每行代碼少於 80 個字元，在有些情況下，長點也可以, 但最多為 120 個字元。  

C.2.4.  行結束標誌  
    行結束標誌遵循 Unix 文字檔的約定，行必需以單個分行符號（LF）結束。分行符號在檔案中表示為 10，或16進位的 0x0A。  
    註：不要使用 蘋果作業系統的斷行符號（0x0D）或 Windows 電腦的斷行符號換行組合如（0x0D,0x0A）。  

C.3.  命名規範  
C.3.1.  類  
    Zend Framework 的類命名總是對應於其所屬檔案的目錄結構的，ZF 標準庫的根目錄是 “Zend/”，ZF 特別（extras）庫的根目錄是 "ZendX/"，所有 Zend Framework 的類在其下按等級存放。  
    類名只允許有字母數字字元，在大部分情況下不鼓勵使用數字。底線只允許做路徑分隔字元；例如 Zend/Db/Table.php 檔案裡對應的類名稱是 Zend_Db_Table。  
    如果類名包含多個單詞，每個單詞的第一個字母必須大寫，連續的大寫是不允許的，例如 “Zend_PDF” 是不允許的，而 "Zend_Pdf" 是可接受的。  
    這些約定為 Zend Framework 定義了一個偽命名空間機制。如果對開發人員在他們的程式中切實可行，Zend Framework 將採用 PHP 命名空間特性（如果有的話）。  
    參見在標準和特別庫中類名作為類名約定的例子。 重要： 依靠 ZF 庫展開的代碼，但又不是標準或特別庫的一部分（例如程式碼或不是 Zend 發行的庫），不要以 "Zend_" 或 "ZendX_" 開頭。  

C.3.2.  檔案名稱  
    對於其它檔案，只有字母數字字元、底線和虛線（"-"）可用，空格是絕對不允許的。  
    包含任何 PHP 代碼的任何檔案應當以 ".php" 副檔名結尾，眾所周知的視圖指令碼除外。下面這些例子給出 Zend Framework 類可接受的檔案名稱：  
    Zend/Db.php 
    Zend/Controller/Front.php 
    Zend/View/Helper/FormRadio.php 
檔案名稱必須遵循上述的對應類名的規則。  

C.3.3.  函數和方法  
    函數名只包含字母數字字元，底線是不允許的。數字是允許的但大多數情況下不鼓勵。  
    函數名總是以小寫開頭，當函數名包含多個單詞，每個子的首字母必須大寫，這就是所謂的 “駝峰” 格式。  
    我們一般鼓勵使用冗長的名字，函數名應當長到足以說明函數的意圖和行為。  
    這些是可接受的函數名的例子：  
    filterInput() 
    getElementById() 
    widgetFactory() 

    對於物件導向編程，執行個體或靜態變數的訪問器總是以 "get" 或 "set" 為首碼。在設計模式實現方面，如單態模式（singleton）或原廠模式（factory）， 方法的名字應當包含模式的名字，這樣名字更能描述整個行為。  
    在對象中的方法，聲明為 "private" 或 "protected" 的， 名稱的首字元必須是一個單個的底線，這是唯一的底線在方法名字中的用法。聲明為 "public" 的從不包含底線。  
    全域函數 (如："floating functions") 允許但大多數情況下不鼓勵，建議把這類函數封裝到靜態類裡。  

C.3.4.  變數  
    變數只包含數字字母字元，大多數情況下不鼓勵使用數字，底線不接受。  
    聲明為 "private" 或 "protected" 的執行個體變數名必須以一個單個底線開頭，這是唯一的底線在程式中的用法，聲明為 "public" 的不應當以底線開頭。  
    對函數名（見上面 3.3 節）一樣，變數名總以小寫字母開頭並遵循“駝峰式”命名規範。  
    我們一般鼓勵使用冗長的名字，這樣容易理解代碼，開發人員知道把資料存到哪裡。除非在小迴圈裡，不鼓勵使用簡潔的名字如 "$i" 和 "$n" 。如果一個迴圈超過 20 行代碼，索引的變數名必須有個具有描述意義的名字。  

C.3.5.  常量  
    常量包含數字字母字元和底線，數字允許作為常量名。  
    常量名的所有字母必須大寫。  
    常量中的單詞必須以底線分隔，例如可以這樣 EMBED_SUPPRESS_EMBED_EXCEPTION 但不許這樣 EMBED_SUPPRESSEMBEDEXCEPTION。  
    常量必須通過 "const" 定義為類的成員，強烈不鼓勵使用 "define" 定義的全域常量。  

C.4.  編碼風格  
C.4.1. PHP 代碼劃分（Demarcation） 
    PHP 代碼總是用完整的標準的 PHP 標籤定界：  
<?php 

?> 
短標籤（ ）是不允許的，只包含 PHP 代碼的檔案，不要結束標籤 （參見 Section C.2.1, “ 常規 ”）。  

C.4.2.  字串  
C.4.2.1.  字串文字  
    當字串是文字(不包含變數)，應當用單引號（ apostrophe ）來括起來：  
    $a = 'Example String'; 

C.4.2.2.  包含單引號（'）的字串文字  
    當文字字串包含單引號（apostrophe ）就用雙引號括起來，特別在 SQL 陳述式中有用：  
    $sql = "SELECT `id`, `name` from `people` WHERE `name`='Fred' OR `name`='Susan'"; 
    在轉義單引號時，上述文法是首選的，因為很容易閱讀。  

C.4.2.3.  變數替換  
    變數替換有下面這些形式：  
    $greeting = "Hello $name, welcome back!"; 
    $greeting = "Hello {$name}, welcome back!"; 
    為保持一致，這個形式不允許：  
    $greeting = "Hello ${name}, welcome back!"; 

C.4.2.4.  字串串連  
    字串必需用 "." 操作符串連，在它的前後加上空格以提高可讀性： 
    $company = 'Zend' . ' ' . 'Technologies'; 
    當用 "." 操作符連接字串，鼓勵把代碼可以分成多個行，也是為提高可讀性。在這些例子中，每個連續的行應當由 whitespace 來填補，例如 "." 和 "=" 對齊：  
$sql = "SELECT `id`, `name` FROM `people` " 
     . "WHERE `name` = 'Susan' " 
     . "ORDER BY `name` ASC "; 

C.4.3.  數組  
C.4.3.1.  數字索引數組  
    索引不能為負數，建議數組索引從 0 開始。  
    當用 array 函式宣告有索引的數組，在每個逗號的後面間隔空格以提高可讀性：  
    $sampleArray = array(1, 2, 3, 'Zend', 'Studio'); 

    可以用 "array" 聲明多行有索引的數組，在每個連續行的開頭要用空格填補對齊：  
$sampleArray = array(1, 2, 3, 'Zend', 'Studio', 
                     $a, $b, $c, 
                     56.44, $d, 500); 

C.4.3.2.  關聯陣列  
    當用聲明關聯陣列，array 我們鼓勵把代碼分成多行，在每個連續行的開頭用空格填補來對齊鍵和值：  
$sampleArray = array('firstKey'  => 'firstValue', 
                     'secondKey' => 'secondValue'); 
C.4.4.  類  
C.4.4.1.  類的聲明  
    用 Zend Framework 的命名規範來命名類。  
    花括弧應當從類名下一行開始(the "one true brace" form)。  
    每個類必須有一個符合 PHPDocumentor 標準的文檔塊。  
    類中所有代碼必需用四個空格的縮排。  
    每個 PHP 檔案中只有一個類。  
    放另外的代碼到類裡允許但不鼓勵。在這樣的檔案中，用兩行空格來分隔類和其它代碼。  

下面是個可接受的類的例子： // 459 9506 － 441 9658 下次從這裡開始  
/** 
 * Documentation Block Here 
 */ 
class SampleClass 
{ 
    // 類的所有內容 
    // 必需縮排四個空格 
} 

C.4.4.2.  類成員變數  
    必須用Zend Framework的變數名約定來命名類成員變數。  
    變數的聲明必須在類的頂部，在方法的上方聲明。  
    不允許使用 var （因為 ZF 是基於 PHP 5 的 ），要用 private、 protected 或 public。 直接存取 public 變數是允許的但不鼓勵，最好使用訪問器 （set/get）。  

C.4.5.  函數和方法  
C.4.5.1.  函數和方法聲明  
    必須用Zend Framework的函數名約定來命名函數。  
    在類中的函數必須用 private、 protected 或 public 聲明它們的可見度。  
    象類一樣，花括弧從函數名的下一行開始(the "one true brace" form)。  
    函數名和括參數的圓括弧中間沒有空格。  
    強烈反對使用全域函數。  
下面是可接受的在類中的函式宣告的例子：  
/** 
 * Documentation Block Here 
 */ 
class Foo 
{ 
    /** 
     * Documentation Block Here 
     */ 
    public function bar() 
    { 
        // 函數的所有內容 
        // 必需縮排四個空格 
    } 
} 
註： 傳址（Pass-by-reference）是在方法聲明中允許的唯一的參數傳遞機制。   

/** 
 * Documentation Block Here 
 */ 
class Foo 
{ 
    /** 
     * Documentation Block Here 
     */ 
    public function bar(&$baz) 
    {} 
} 

傳址在調用時是嚴格禁止的。  
傳回值不能在圓括弧中，這妨礙可讀性而且如果將來方法被修改成傳址方式，代碼會有問題。  

/** 
 * Documentation Block Here 
 */ 
class Foo 
{ 
    /** 
     * WRONG 
     */ 
    public function bar() 
    { 
        return($this->bar); 
    } 

    /** 
     * RIGHT 
     */ 
    public function bar() 
    { 
        return $this->bar; 
    } 
} 

C.4.5.2.  函數和方法的用法  
    函數的參數應當用逗號和緊接著的空格分開，下面可接受的調用的例子中的函數帶有三個參數：  
    threeArguments(1, 2, 3); 
    傳址方式在調用的時候是嚴格禁止的，參見函數的聲明一節如何正確使用函數的傳址方式。  
    帶有數組參數的函數，函數的調用可包括 "array" 提示並可以分成多行來提高可讀性，同時，書寫數組的標準仍然適用：  
threeArguments(array(1, 2, 3), 2, 3); 
threeArguments(array(1, 2, 3, 'Zend', 'Studio', 
                     $a, $b, $c, 
                     56.44, $d, 500), 2, 3); 

C.4.6.  控制語句  
C.4.6.1. if/Else/Elseif 
    使用 if and elseif 的控制語句在條件陳述式的圓括弧前後都必須有一個空格。  
    在圓括弧裡的條件陳述式，操作符必須用空格分開，鼓勵使用多重圓括弧以提高在複雜的條件中劃分邏輯組合。  
    前花括弧必須和條件陳述式在同一行，後花括弧單獨在最後一行，其中的內容用四個空格縮排。  
if ($a != 2) { 
    $a = 2; 
} 

    對包括"elseif" 或 "else"的 "if" 語句，和 "if" 結構的格式類似， 下面的例子樣本 "if" 語句， 包括 "elseif" 或 "else" 的格式約定：  
if ($a != 2) { 
    $a = 2; 
} else { 
    $a = 7; 
} 

if ($a != 2) { 
    $a = 2; 
} elseif ($a == 3) { 
    $a = 4; 
} else { 
    $a = 7; 
} 

    在有些情況下， PHP 允許這些語句不用花括弧，但在(ZF) 代碼標準裡，它們（"if"、 "elseif" 或 "else" 語句）必須使用花括弧。  
    "elseif" 是允許的但強烈不鼓勵，我們支援 "else if" 組合。  

C.4.6.2. Switch 
    在 "switch" 結構裡的控制語句在條件陳述式的圓括弧前後必須都有一個單個的空格。  
    "switch" 裡的代碼必須有四個空格縮排，在"case"裡的代碼再縮排四個空格。  
switch ($numPeople) { 
    case 1: 
        break; 

    case 2: 
        break; 

    default: 
        break; 
} 

switch 語句應當有 default。  
    註： 有時候，在 falls through 到下個 case 的 case 語句中不寫 break or return 很有用。 為了區別於 bug，任何 case 語句中，所有不寫 break or return 的地方應當有一個 "// break intentionally omitted" 這樣的注釋來表明 break 是故意忽略的。   

C.4.7.  注釋文檔  
C.4.7.1.  格式  
    所有文檔塊 ("docblocks") 必須和 phpDocumentor 格式相容，phpDocumentor 格式的描述超出了本文檔的範圍，關於它的詳情，參考：http://phpdoc.org/。  
    所有類檔案必須在檔案的頂部包含檔案級 （"file-level"）的 docblock ，在每個類的頂部放置一個 "class-level" 的 docblock。下面是一些例子：  

C.4.7.2.  檔案  
    每個包含 PHP 代碼的檔案必須至少在檔案頂部的 docblock 包含這些 phpDocumentor 標籤：  
/** 
 * 檔案的簡短描述 
 * 
 * 檔案的詳細描述（如果有的話）... ... 
 * 
 * LICENSE: 一些 license 資訊 
 * 
 * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com) 
 * @license    http://framework.zend.com/license/3_0.txt   BSD License 
 * @version    $Id:$ 
 * @link       http://framework.zend.com/package/PackageName 
 * @since      File available since Release 1.5.0 
*/ 

C.4.7.3.  類  
    每個類必須至少包含這些 phpDocumentor 標籤：  
/** 
 * 類的簡述 
 * 
 * 類的詳細描述 （如果有的話）... ... 
 * 
 * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com) 
 * @license    http://framework.zend.com/license/   BSD License 
 * @version    Release: @package_version@ 
 * @link       http://framework.zend.com/package/PackageName 
 * @since      Class available since Release 1.5.0 
 * @deprecated Class deprecated in Release 2.0.0 
 */ 

C.4.7.4.  函數  
    每個函數，包括對象方法，必須有最少包含下列內容的文檔塊（docblock）：  
    函數的描述  
    所有參數  
    所有可能的傳回值  

    因為訪問級已經通過 "public"、 "private" 或 "protected" 聲明， 不需要使用 "@access"。  
    如果函數/方法拋出一個異常，使用 @throws 於所有已知的異常類：  
    @throws exceptionclass [description]