Zend Framework的PHP編碼標(biāo)準(zhǔn)
[摘自 Zend Framework 官方文檔]
C.2. PHP File 文件格式
C.2.1. 常規(guī)
對于只包含有 PHP 代碼的文件，結(jié)束標(biāo)志（"?>"）是不允許存在的，PHP自身不需要（"?>"）, 這樣做, 可以防止它的末尾的被意外地注入相應(yīng)。
重要： 由 __HALT_COMPILER() 允許的任意的二進(jìn)制代碼的內(nèi)容被 Zend Framework 中的 PHP 文件或由它們產(chǎn)生的文件禁止。這個(gè)功能的使用只對一些安裝腳本開放。
C.2.2. 縮進(jìn)
縮進(jìn)由四個(gè)空格組成，禁止使用制表符 TAB 。
C.2.3. 行的最大長度
一行 80 字符以內(nèi)是比較合適，就是說，ZF 的開發(fā)者應(yīng)當(dāng)努力在可能的情況下保持每行代碼少于 80 個(gè)字符，在有些情況下，長點(diǎn)也可以, 但最多為 120 個(gè)字符。
C.2.4. 行結(jié)束標(biāo)志
行結(jié)束標(biāo)志遵循 Unix 文本文件的約定，行必需以單個(gè)換行符（LF）結(jié)束。換行符在文件中表示為 10，或16進(jìn)制的 0x0A。
注：不要使用 蘋果操作系統(tǒng)的回車（0x0D）或 Windows 電腦的回車換行組合如（0x0D,0x0A）。
C.3. 命名約定
C.3.1. 類
Zend Framework 的類命名總是對應(yīng)于其所屬文件的目錄結(jié)構(gòu)的，ZF 標(biāo)準(zhǔn)庫的根目錄是 “Zend/”，ZF 特別（extras）庫的根目錄是 "ZendX/"，所有 Zend Framework 的類在其下按等級存放。
類名只允許有字母數(shù)字字符，在大部分情況下不鼓勵使用數(shù)字。下劃線只允許做路徑分隔符；例如 Zend/Db/Table.php 文件里對應(yīng)的類名稱是 Zend_Db_Table。
如果類名包含多個(gè)單詞，每個(gè)單詞的第一個(gè)字母必須大寫，連續(xù)的大寫是不允許的，例如 “Zend_PDF” 是不允許的，而 "Zend_Pdf" 是可接受的。
這些約定為 Zend Framework 定義了一個(gè)偽命名空間機(jī)制。如果對開發(fā)者在他們的程序中切實(shí)可行，Zend Framework 將采用 PHP 命名空間特性（如果有的話）。
參見在標(biāo)準(zhǔn)和特別庫中類名作為類名約定的例子。 重要： 依靠 ZF 庫展開的代碼，但又不是標(biāo)準(zhǔn)或特別庫的一部分（例如程序代碼或不是 Zend 發(fā)行的庫），不要以 "Zend_" 或 "ZendX_" 開頭。
C.3.2. 文件名
對于其它文件，只有字母數(shù)字字符、下劃線和短橫線（"-"）可用，空格是絕對不允許的。
包含任何 PHP 代碼的任何文件應(yīng)當(dāng)以 ".php" 擴(kuò)展名結(jié)尾，眾所周知的視圖腳本除外。下面這些例子給出 Zend Framework 類可接受的文件名：
Zend/Db.php
Zend/Controller/Front.php
Zend/View/Helper/FormRadio.php
文件名必須遵循上述的對應(yīng)類名的規(guī)則。
C.3.3. 函數(shù)和方法
函數(shù)名只包含字母數(shù)字字符，下劃線是不允許的。數(shù)字是允許的但大多數(shù)情況下不鼓勵。
函數(shù)名總是以小寫開頭，當(dāng)函數(shù)名包含多個(gè)單詞，每個(gè)子的首字母必須大寫，這就是所謂的 “駝峰” 格式。
我們一般鼓勵使用冗長的名字，函數(shù)名應(yīng)當(dāng)長到足以說明函數(shù)的意圖和行為。
這些是可接受的函數(shù)名的例子：
filterInput()
getElementById()
widgetFactory()
對于面向?qū)ο缶幊?，?shí)例或靜態(tài)變量的訪問器總是以 "get" 或 "set" 為前綴。在設(shè)計(jì)模式實(shí)現(xiàn)方面，如單態(tài)模式（singleton）或工廠模式（factory）， 方法的名字應(yīng)當(dāng)包含模式的名字，這樣名字更能描述整個(gè)行為。
在對象中的方法，聲明為 "private" 或 "protected" 的， 名稱的首字符必須是一個(gè)單個(gè)的下劃線，這是唯一的下劃線在方法名字中的用法。聲明為 "public" 的從不包含下劃線。
全局函數(shù) (如："floating functions") 允許但大多數(shù)情況下不鼓勵，建議把這類函數(shù)封裝到靜態(tài)類里。
C.3.4. 變量
變量只包含數(shù)字字母字符，大多數(shù)情況下不鼓勵使用數(shù)字，下劃線不接受。
聲明為 "private" 或 "protected" 的實(shí)例變量名必須以一個(gè)單個(gè)下劃線開頭，這是唯一的下劃線在程序中的用法，聲明為 "public" 的不應(yīng)當(dāng)以下劃線開頭。
對函數(shù)名（見上面 3.3 節(jié)）一樣，變量名總以小寫字母開頭并遵循“駝峰式”命名約定。
我們一般鼓勵使用冗長的名字，這樣容易理解代碼，開發(fā)者知道把數(shù)據(jù)存到哪里。除非在小循環(huán)里，不鼓勵使用簡潔的名字如 "$i" 和 "$n" 。如果一個(gè)循環(huán)超過 20 行代碼，索引的變量名必須有個(gè)具有描述意義的名字。
C.3.5. 常量
常量包含數(shù)字字母字符和下劃線，數(shù)字允許作為常量名。
常量名的所有字母必須大寫。
常量中的單詞必須以下劃線分隔，例如可以這樣 EMBED_SUPPRESS_EMBED_EXCEPTION 但不許這樣 EMBED_SUPPRESSEMBEDEXCEPTION。
常量必須通過 "const" 定義為類的成員，強(qiáng)烈不鼓勵使用 "define" 定義的全局常量。
#p#
C.4. 編碼風(fēng)格
C.4.1. PHP 代碼劃分（Demarcation）
PHP 代碼總是用完整的標(biāo)準(zhǔn)的 PHP 標(biāo)簽定界：
- <?php
- ?>
短標(biāo)簽（ ）是不允許的，只包含 PHP 代碼的文件，不要結(jié)束標(biāo)簽 （參見 Section C.2.1, “ 常規(guī) ”）。
C.4.2. 字符串
C.4.2.1. 字符串文字
當(dāng)字符串是文字(不包含變量)，應(yīng)當(dāng)用單引號（ apostrophe ）來括起來：
- $a = 'Example String';
C.4.2.2. 包含單引號（'）的字符串文字
當(dāng)文字字符串包含單引號（apostrophe ）就用雙引號括起來，特別在 SQL 語句中有用：
- $sql = "SELECT `id`, `name` from `people` WHERE `name`='Fred' OR `name`='Susan'";
在轉(zhuǎn)義單引號時(shí)，上述語法是首選的，因?yàn)楹苋菀组喿x。
C.4.2.3. 變量替換
變量替換有下面這些形式：
- $greeting = "Hello $name, welcome back!";
- $greeting = "Hello {$name}, welcome back!";
為保持一致，這個(gè)形式不允許：
- $greeting = "Hello ${name}, welcome back!";
C.4.2.4. 字符串連接
字符串必需用 "." 操作符連接，在它的前后加上空格以提高可讀性：
- $company = 'Zend' . ' ' . 'Technologies';
當(dāng)用 "." 操作符連接字符串，鼓勵把代碼可以分成多個(gè)行，也是為提高可讀性。在這些例子中，每個(gè)連續(xù)的行應(yīng)當(dāng)由 whitespace 來填補(bǔ)，例如 "." 和 "=" 對齊：
- $sql = "SELECT `id`, `name` FROM `people` "
- . "WHERE `name` = 'Susan' "
- . "ORDER BY `name` ASC ";
C.4.3. 數(shù)組
C.4.3.1. 數(shù)字索引數(shù)組
索引不能為負(fù)數(shù)，建議數(shù)組索引從 0 開始。
當(dāng)用 array 函數(shù)聲明有索引的數(shù)組，在每個(gè)逗號的后面間隔空格以提高可讀性：
- $sampleArray = array(1, 2, 3, 'Zend', 'Studio');
可以用 "array" 聲明多行有索引的數(shù)組，在每個(gè)連續(xù)行的開頭要用空格填補(bǔ)對齊：
- $sampleArray = array(1, 2, 3, 'Zend', 'Studio',
- $a, $b, $c,
- 56.44, $d, 500);
C.4.3.2. 關(guān)聯(lián)數(shù)組
當(dāng)用聲明關(guān)聯(lián)數(shù)組，array 我們鼓勵把代碼分成多行，在每個(gè)連續(xù)行的開頭用空格填補(bǔ)來對齊鍵和值：
- $sampleArray = array('firstKey' => 'firstValue',
- 'secondKey' => 'secondValue');
C.4.4. 類
C.4.4.1. 類的聲明
用 Zend Framework 的命名約定來命名類。
花括號應(yīng)當(dāng)從類名下一行開始(the "one true brace" form)。
每個(gè)類必須有一個(gè)符合 PHPDocumentor 標(biāo)準(zhǔn)的文檔塊。
類中所有代碼必需用四個(gè)空格的縮進(jìn)。
每個(gè) PHP 文件中只有一個(gè)類。
放另外的代碼到類里允許但不鼓勵。在這樣的文件中，用兩行空格來分隔類和其它代碼。
下面是個(gè)可接受的類的例子： // 459 9506 － 441 9658 下次從這里開始
- /**
- * Documentation Block Here
- */
- class SampleClass
- {
- // 類的所有內(nèi)容
- // 必需縮進(jìn)四個(gè)空格
- }
C.4.4.2. 類成員變量
必須用Zend Framework的變量名約定來命名類成員變量。
變量的聲明必須在類的頂部，在方法的上方聲明。
不允許使用 var （因?yàn)?ZF 是基于 PHP 5 的 ），要用 private、 protected 或 public。 直接訪問 public 變量是允許的但不鼓勵，最好使用訪問器 （set/get）。
#p#
C.4.5. 函數(shù)和方法
C.4.5.1. 函數(shù)和方法聲明
必須用Zend Framework的函數(shù)名約定來命名函數(shù)。
在類中的函數(shù)必須用 private、 protected 或 public 聲明它們的可見性。
象類一樣，花括號從函數(shù)名的下一行開始(the "one true brace" form)。
函數(shù)名和括參數(shù)的圓括號中間沒有空格。
強(qiáng)烈反對使用全局函數(shù)。
下面是可接受的在類中的函數(shù)聲明的例子：
- /**
- * Documentation Block Here
- */
- class Foo
- {
- /**
- * Documentation Block Here
- */
- public function bar()
- {
- // 函數(shù)的所有內(nèi)容
- // 必需縮進(jìn)四個(gè)空格
- }
- }
注： 傳址（Pass-by-reference）是在方法聲明中允許的唯一的參數(shù)傳遞機(jī)制。
- /**
- * Documentation Block Here
- */
- class Foo
- {
- /**
- * Documentation Block Here
- */
- public function bar(&$baz)
- {}
- }
傳址在調(diào)用時(shí)是嚴(yán)格禁止的。
返回值不能在圓括號中，這妨礙可讀性而且如果將來方法被修改成傳址方式，代碼會有問題。
- /**
- * Documentation Block Here
- */
- class Foo
- {
- /**
- * WRONG
- */
- public function bar()
- {
- return($this->bar);
- }
- /**
- * RIGHT
- */
- public function bar()
- {
- return $this->bar;
- }
- }
C.4.5.2. 函數(shù)和方法的用法
函數(shù)的參數(shù)應(yīng)當(dāng)用逗號和緊接著的空格分開，下面可接受的調(diào)用的例子中的函數(shù)帶有三個(gè)參數(shù)：
- threeArguments(1, 2, 3);
傳址方式在調(diào)用的時(shí)候是嚴(yán)格禁止的，參見函數(shù)的聲明一節(jié)如何正確使用函數(shù)的傳址方式。
帶有數(shù)組參數(shù)的函數(shù)，函數(shù)的調(diào)用可包括 "array" 提示并可以分成多行來提高可讀性，同時(shí)，書寫數(shù)組的標(biāo)準(zhǔn)仍然適用：
- 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 的控制語句在條件語句的圓括號前后都必須有一個(gè)空格。
在圓括號里的條件語句，操作符必須用空格分開，鼓勵使用多重圓括號以提高在復(fù)雜的條件中劃分邏輯組合。
前花括號必須和條件語句在同一行，后花括號單獨(dú)在最后一行，其中的內(nèi)容用四個(gè)空格縮進(jìn)。
- if ($a != 2) {
- $a = 2;
- }
對包括"elseif" 或 "else"的 "if" 語句，和 "if" 結(jié)構(gòu)的格式類似， 下面的例子示例 "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) 代碼標(biāo)準(zhǔn)里，它們（"if"、 "elseif" 或 "else" 語句）必須使用花括號。
"elseif" 是允許的但強(qiáng)烈不鼓勵，我們支持 "else if" 組合。
C.4.6.2. Switch
在 "switch" 結(jié)構(gòu)里的控制語句在條件語句的圓括號前后必須都有一個(gè)單個(gè)的空格。
"switch" 里的代碼必須有四個(gè)空格縮進(jìn)，在"case"里的代碼再縮進(jìn)四個(gè)空格。
- switch ($numPeople) {
- case 1:
- break;
- case 2:
- break;
- default:
- break;
- }
switch 語句應(yīng)當(dāng)有 default。
注： 有時(shí)候，在 falls through 到下個(gè) case 的 case 語句中不寫 break or return 很有用。 為了區(qū)別于 bug，任何 case 語句中，所有不寫 break or return 的地方應(yīng)當(dāng)有一個(gè) "// break intentionally omitted" 這樣的注釋來表明 break 是故意忽略的。
#p#
C.4.7. 注釋文檔
C.4.7.1. 格式
所有文檔塊 ("docblocks") 必須和 phpDocumentor 格式兼容，phpDocumentor 格式的描述超出了本文檔的范圍，關(guān)于它的詳情，參考：http://phpdoc.org/。
所有類文件必須在文件的頂部包含文件級 （"file-level"）的 docblock ，在每個(gè)類的頂部放置一個(gè) "class-level" 的 docblock。下面是一些例子：
C.4.7.2. 文件
每個(gè)包含 PHP 代碼的文件必須至少在文件頂部的 docblock 包含這些 phpDocumentor 標(biāo)簽：
- /**
- * 文件的簡短描述
- *
- * 文件的詳細(xì)描述（如果有的話）... ...
- *
- * 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. 類
每個(gè)類必須至少包含這些 phpDocumentor 標(biāo)簽：
- /**
- * 類的簡述
- *
- * 類的詳細(xì)描述 （如果有的話）... ...
- *
- * @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. 函數(shù)
每個(gè)函數(shù)，包括對象方法，必須有最少包含下列內(nèi)容的文檔塊（docblock）：
函數(shù)的描述
所有參數(shù)
所有可能的返回值
因?yàn)樵L問級已經(jīng)通過 "public"、 "private" 或 "protected" 聲明， 不需要使用 "@access"。
如果函數(shù)/方法拋出一個(gè)異常，使用 @throws 于所有已知的異常類：
- @throws exceptionclass [description]
