PHP File 文件格式

對于只包含有 PHP 代碼的文件，結(jié)束標(biāo)志（"?>"）是不允許存在的，PHP自身不需要（"?>"）, 這樣做, 可以防止它的末尾的被意外地注入相應(yīng)。

重要：?由?__HALT_COMPILER()?允許的任意的二進(jìn)制代碼的內(nèi)容被 Zend Framework 中的 PHP 文件或由它們產(chǎn)生的文件禁止。 這個(gè)功能的使用只對一些安裝腳本開放。

縮進(jìn)由四個(gè)空格組成，禁止使用制表符 TAB 。

行的最大長度

一行 80 字符以內(nèi)是比較合適，就是說，ZF 的開發(fā)者應(yīng)當(dāng)努力在可能的情況下保持每行代碼少于 80 個(gè)字符，在有些情況下，長點(diǎn)也可以, 但最多為 120 個(gè)字符。

行結(jié)束標(biāo)志

行結(jié)束標(biāo)志遵循 Unix 文本文件的約定，行必需以單個(gè)換行符（LF）結(jié)束。換行符在文件中表示為 10，或16進(jìn)制的 0x0A。

注：不要使用 蘋果操作系統(tǒng)的回車（0x0D）或 Windows 電腦的回車換行組合如（0x0D,0x0A）。

?

命名約定

Zend Framework 的類命名總是對應(yīng)于其所屬文件的目錄結(jié)構(gòu)的，ZF 標(biāo)準(zhǔn)庫的根目錄是 “Zend/”，ZF 特別（extras）庫的根目錄是 "ZendX/"，所有 Zend Framework 的類在其下按等級存放。

類名只允許有字母數(shù)字字符，在大部分情況下不鼓勵(lì)使用數(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_" 開頭。

文件名

對于其它文件，只有字母數(shù)字字符、下劃線和短橫線（"-"）可用，空格是絕對不允許的。

包含任何 PHP 代碼的任何文件應(yīng)當(dāng)以 ".php" 擴(kuò)展名結(jié)尾，眾所周知的視圖腳本除外。下面這些例子給出 Zend Framework 類可接受的文件名：

Zend/Db.phpZend/Controller/Front.phpZend/View/Helper/FormRadio.php                

文件名必須遵循上述的對應(yīng)類名的規(guī)則。

函數(shù)和方法

函數(shù)名只包含字母數(shù)字字符，下劃線是不允許的。數(shù)字是允許的但大多數(shù)情況下不鼓勵(lì)。

函數(shù)名總是以小寫開頭，當(dāng)函數(shù)名包含多個(gè)單詞，每個(gè)子的首字母必須大寫，這就是所謂的 “駝峰” 格式。

我們一般鼓勵(lì)使用冗長的名字，函數(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ù)情況下不鼓勵(lì)，建議把這類函數(shù)封裝到靜態(tài)類里。

變量只包含數(shù)字字母字符，大多數(shù)情況下不鼓勵(lì)使用數(shù)字，下劃線不接受。

聲明為 "private" 或 "protected" 的實(shí)例變量名必須以一個(gè)單個(gè)下劃線開頭，這是唯一的下劃線在程序中的用法，聲明為 "public" 的不應(yīng)當(dāng)以下劃線開頭。

對函數(shù)名（見上面 3.3 節(jié)）一樣，變量名總以小寫字母開頭并遵循“駝峰式”命名約定。

我們一般鼓勵(lì)使用冗長的名字，這樣容易理解代碼，開發(fā)者知道把數(shù)據(jù)存到哪里。除非在小循環(huán)里，不鼓勵(lì)使用簡潔的名字如 "$i" 和 "$n" 。如果一個(gè)循環(huán)超過 20 行代碼，索引的變量名必須有個(gè)具有描述意義的名字。

常量包含數(shù)字字母字符和下劃線，數(shù)字允許作為常量名。

常量名的所有字母必須大寫。

常量中的單詞必須以下劃線分隔，例如可以這樣 EMBED_SUPPRESS_EMBED_EXCEPTION 但不許這樣EMBED_SUPPRESSEMBEDEXCEPTION。

常量必須通過 "const" 定義為類的成員，強(qiáng)烈不鼓勵(lì)使用 "define" 定義的全局常量。

編碼風(fēng)格

PHP 代碼劃分（Demarcation）

PHP 代碼總是用完整的標(biāo)準(zhǔn)的 PHP 標(biāo)簽定界：

<?php?>

短標(biāo)簽（ ）是不允許的，只包含 PHP 代碼的文件，不要結(jié)束標(biāo)簽 （參見 常規(guī)）。

字符串

字符串文字

當(dāng)字符串是文字(不包含變量)，應(yīng)當(dāng)用單引號（ apostrophe ）來括起來：

$a = 'Example String';                    

包含單引號（'）的字符串文字

當(dāng)文字字符串包含單引號（apostrophe ）就用雙引號括起來，特別在 SQL 語句中有用：

$sql = "SELECT `id`, `name` from `people` WHERE `name`='Fred' OR `name`='Susan'";                    

在轉(zhuǎn)義單引號時(shí)，上述語法是首選的，因?yàn)楹苋菀组喿x。

變量替換

變量替換有下面這些形式：

$greeting = "Hello $name, welcome back!";$greeting = "Hello {$name}, welcome back!";                    

為保持一致，這個(gè)形式不允許：

$greeting = "Hello ${name}, welcome back!";                    

字符串連接

字符串必需用 "." 操作符連接，在它的前后加上空格以提高可讀性：

$company = 'Zend' . ' ' . 'Technologies';                    

當(dāng)用 "." 操作符連接字符串，鼓勵(lì)把代碼可以分成多個(gè)行，也是為提高可讀性。在這些例子中，每個(gè)連續(xù)的行應(yīng)當(dāng)由 whitespace 來填補(bǔ)，例如 "." 和 "=" 對齊：

$sql = "SELECT `id`, `name` FROM `people` "     . "WHERE `name` = 'Susan' "     . "ORDER BY `name` ASC ";                    

數(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);                    

關(guān)聯(lián)數(shù)組

當(dāng)用聲明關(guān)聯(lián)數(shù)組，array 我們鼓勵(lì)把代碼分成多行，在每個(gè)連續(xù)行的開頭用空格填補(bǔ)來對齊鍵和值：

$sampleArray = array('firstKey'  => 'firstValue',                     'secondKey' => 'secondValue');                    

類的聲明

用 Zend Framework 的命名約定來命名類。

花括號應(yīng)當(dāng)從類名下一行開始(the "one true brace" form)。

每個(gè)類必須有一個(gè)符合 PHPDocumentor 標(biāo)準(zhǔn)的文檔塊。

類中所有代碼必需用四個(gè)空格的縮進(jìn)。

每個(gè) PHP 文件中只有一個(gè)類。

放另外的代碼到類里允許但不鼓勵(lì)。在這樣的文件中，用兩行空格來分隔類和其它代碼。

下面是個(gè)可接受的類的例子： // 459 9506 － 441 9658 下次從這里開始

/** * Documentation Block Here */class SampleClass{    // 類的所有內(nèi)容    // 必需縮進(jìn)四個(gè)空格}                    

類成員變量

必須用Zend Framework的變量名約定來命名類成員變量。

變量的聲明必須在類的頂部，在方法的上方聲明。

不允許使用 var （因?yàn)?ZF 是基于 PHP 5 的 ），要用 private、 protected 或 public。 直接訪問 public 變量是允許的但不鼓勵(lì)，最好使用訪問器 （set/get）。

函數(shù)和方法

函數(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)格禁止的。

返回值不能在圓括號中，這妨礙可讀性而且如果將來方法被修改成傳址方式，代碼會(huì)有問題。

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

函數(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);                    

控制語句

if/Else/Elseif

使用 if and elseif 的控制語句在條件語句的圓括號前后都必須有一個(gè)空格。

在圓括號里的條件語句，操作符必須用空格分開，鼓勵(lì)使用多重圓括號以提高在復(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)烈不鼓勵(lì)，我們支持 "else if" 組合。

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è) "http:// break intentionally omitted" 這樣的注釋來表明 break 是故意忽略的。

注釋文檔

所有文檔塊 ("docblocks") 必須和 phpDocumentor 格式兼容，phpDocumentor 格式的描述超出了本文檔的范圍，關(guān)于它的詳情，參考：» http://phpdoc.org/。

所有類文件必須在文件的頂部包含文件級 （"file-level"）的 docblock ，在每個(gè)類的頂部放置一個(gè) "class-level" 的 docblock。下面是一些例子：

每個(gè)包含 PHP 代碼的文件必須至少在文件頂部的 docblock 包含這些 phpDocumentor 標(biāo)簽：

/** * 文件的簡短描述 * * 文件的詳細(xì)描述（如果有的話）... ... * * LICENSE: 一些 license 信息 * * @copyright  Copyright (c) 2005-2011 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*/                    

每個(gè)類必須至少包含這些 phpDocumentor 標(biāo)簽：

/** * 類的簡述 * * 類的詳細(xì)描述 （如果有的話）... ... * * @copyright  Copyright (c) 2005-2011 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 */                    

每個(gè)函數(shù)，包括對象方法，必須有最少包含下列內(nèi)容的文檔塊（docblock）：

函數(shù)的描述

所有參數(shù)

所有可能的返回值

因?yàn)樵L問級已經(jīng)通過 "public"、 "private" 或 "protected" 聲明， 不需要使用 "@access"。

如果函數(shù)/方法拋出一個(gè)異常，使用 @throws 于所有已知的異常類：

@throws exceptionclass [description]                    

來源：http://framework.zend.com/manual/zh/coding-standard.php-file-formatting.html