Zend Framework的PHP編碼標準

作者：酒肉穿腸過 2013-05-27 10:14:21

開發后端前端

Zend Framework的PHP編碼標準，摘自 Zend Framework 官方文檔，本文由酒肉穿腸過編譯。

[摘自 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" 定義的全局常量。

#p#

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）。

#p#

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 是故意忽略的。

#p#

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]

原文鏈接：http://my.oschina.net/wzwitblog/blog/132235

責任編輯：林師授來源：酒肉穿腸過的博客