1. 引言

本規(guī)范由編程原則組成，融合并提煉了開發(fā)人員長(zhǎng)時(shí)間積累下來(lái)的成熟經(jīng)驗(yàn)，意在幫助形成良好一致的編程風(fēng)格。以達(dá)到事半功倍的效果，如果有需要本文檔會(huì)不定期更新。

2. 適用范圍

Php項(xiàng)目開發(fā)。本規(guī)范作為基本規(guī)范，如采用第三方開發(fā)框架（如Yii、ThinkPHP）則以第三方框架規(guī)范為準(zhǔn)則（如有）。

3. 標(biāo)準(zhǔn)化的重要性和好處

當(dāng)一個(gè)軟件項(xiàng)目嘗試著遵守公共一致的標(biāo)準(zhǔn)時(shí)，可以使參與項(xiàng)目的開發(fā)人員更容易了解項(xiàng)目中的代碼、弄清程序的狀況。使新的參與者可以很快的適應(yīng)環(huán)境，防止部分參與者出于節(jié)省時(shí)間的需要，自創(chuàng)一套風(fēng)格并養(yǎng)成終生的習(xí)慣，導(dǎo)致其它人在閱讀時(shí)浪費(fèi)過(guò)多的時(shí)間和精力。而且在一致的環(huán)境下，也可以減少編碼出錯(cuò)的機(jī)會(huì)。缺陷是由于每個(gè)人的標(biāo)準(zhǔn)不同，所以需要一段時(shí)間來(lái)適應(yīng)和改變自己的編碼風(fēng)格，暫時(shí)性的降底了工作效率。從使項(xiàng)目長(zhǎng)遠(yuǎn)健康的發(fā)展以及后期更高的團(tuán)隊(duì)工作效率來(lái)考慮暫時(shí)的工作效率降低是值得的，也是必須要經(jīng)過(guò)的一個(gè)過(guò)程。標(biāo)準(zhǔn)不是項(xiàng)目成功的關(guān)鍵，但可以幫助我們?cè)趫F(tuán)隊(duì)協(xié)作中有更高的效率并且更加順利的完成既定的任務(wù)。

1. 程序員可以了解任何代碼，弄清程序的狀況

2. 新人可以很快的適應(yīng)環(huán)境

3. 防止新接觸PHP的人出于節(jié)省時(shí)間的需要，自創(chuàng)一套風(fēng)格并養(yǎng)成終生的習(xí)慣

4. 防止新接觸PHP的人一次次的犯同樣的錯(cuò)誤

5. 在一致的環(huán)境下，人們可以減少犯錯(cuò)的機(jī)會(huì)

6. 程序員們有了一致的敵人

4. PHP編碼規(guī)范與原則

4.1. 代碼標(biāo)記

對(duì)于只含有 php 代碼的文件，我們將在文件結(jié)尾處忽略掉 "?>" 。這是為了防止多余的空格或者其它字符影響到代碼。

不建議使用<? ?>和<?=$variablename?>這種速記形式。

4.2. 注釋

注釋是對(duì)于那些容易忘記作用的代碼添加簡(jiǎn)短的介紹性內(nèi)容。請(qǐng)使用 C 樣式的注釋“/* */”和標(biāo)準(zhǔn) C++ 注釋“//”。

4.2.1文件頭部注釋

● 程序涉及業(yè)務(wù)名稱

● @author    作者

● @version    版本

● @date        最后更新時(shí)間

例如：

程序開發(fā)中難免留下一些臨時(shí)代碼和調(diào)試代碼，此類代碼必須添加注釋，以免日后遺忘。所有臨時(shí)性、調(diào)試性、試驗(yàn)性的代碼，必須添加統(tǒng)一的注釋標(biāo)記“//debug”并后跟完整的注釋信息，這樣可以方便在程序發(fā)布和最終調(diào)試前批量檢查程序中是否還存在有疑問(wèn)的代碼。例如：

4.2.2函數(shù)頭部注釋

4.2.3類的注釋

4.2.4程序代碼注釋

4.3. 書寫規(guī)則

4.3.1. 縮進(jìn)

每個(gè)縮進(jìn)的單位約定是一個(gè)TAB(8個(gè)空白字符寬度)，需每個(gè)參與項(xiàng)目的開發(fā)人員在編輯器(UltraEdit、EditPlus、Zend Studio等)中進(jìn)行強(qiáng)制設(shè)定，以防在編寫代碼時(shí)遺忘而造成格式上的不規(guī)范。

本縮進(jìn)規(guī)范適用于PHP、JavaScript中的函數(shù)、類、邏輯結(jié)構(gòu)、循環(huán)等。

4.3.2. 大括號(hào){}、if和switch

首括號(hào)與關(guān)鍵詞同行，尾括號(hào)與關(guān)鍵字同列；

if結(jié)構(gòu)中，else和elseif與前后兩個(gè)大括號(hào)同行，左右各一個(gè)空格。另外，即便if后只有一行語(yǔ)句，仍然需要加入大括號(hào)，以保證結(jié)構(gòu)清晰；

switch結(jié)構(gòu)中，通常當(dāng)一個(gè)case塊處理后，將跳過(guò)之后的case塊處理，因此大多數(shù)情況下需要添加break。break的位置視程序邏輯，與case同在一行，或新起一行均可，但同一switch體中，break的位置格式應(yīng)當(dāng)保持一致。

以下是符合上述規(guī)范的例子：

4.3.3. 運(yùn)算符、小括號(hào)、空格、關(guān)鍵詞和函數(shù)

每個(gè)運(yùn)算符與兩邊參與運(yùn)算的值或表達(dá)式中間要有一個(gè)空格，唯一的特例是字符連接運(yùn)算符號(hào)兩邊不加空格；

左括號(hào)“(” 應(yīng)和函數(shù)關(guān)鍵詞緊貼在一起，除此以外應(yīng)當(dāng)使用空格將“(”同前面內(nèi)容分開；

右括號(hào)“)”除后面是“)”或者“.”以外，其他一律用空格隔開它們；

除字符串中特意需要，一般情況下，在程序以及HTML中不出現(xiàn)兩個(gè)連續(xù)的空格；

任何情況下，PHP程序中不能出現(xiàn)空白的帶有TAB或空格的行，即：這類空白行應(yīng)當(dāng)不包含任何TAB或空格。同時(shí)，任何程序行尾也不能出現(xiàn)多余的TAB或空格。多數(shù)編輯器具有自動(dòng)去除行尾空格的功能，如果習(xí)慣養(yǎng)成不好，可臨時(shí)使用它，避免多余空格產(chǎn)生；

每段較大的程序體，上、下應(yīng)當(dāng)加入空白行，兩個(gè)程序塊之間只使用1個(gè)空行，禁止使用多行。

程序塊劃分盡量合理，過(guò)大或者過(guò)小的分割都會(huì)影響他人對(duì)代碼的閱讀和理解。一般可以以較大函數(shù)定義、邏輯結(jié)構(gòu)、功能結(jié)構(gòu)來(lái)進(jìn)行劃分。少于15行的程序塊，可不加上下空白行；

說(shuō)明或顯示部分中，內(nèi)容如含有中文、數(shù)字、英文單詞混雜，應(yīng)當(dāng)在數(shù)字或者英文單詞的前后加入空格。

根據(jù)上述原則，以下舉例說(shuō)明正確的書寫格式：

4.3.4. 函數(shù)定義

● 參數(shù)的名字和變量的命名規(guī)范一致；

● 函數(shù)定義中的左小括號(hào)，與函數(shù)名緊挨，中間無(wú)需空格；

● 開始的左大括號(hào)與函數(shù)定義為同一行，中間加一個(gè)空格，不要另起一行；

● 具有默認(rèn)值的參數(shù)應(yīng)該位于參數(shù)列表的后面；

● 函數(shù)調(diào)用與定義的時(shí)候參數(shù)與參數(shù)之間加入一個(gè)空格；

● 必須仔細(xì)檢查并切實(shí)杜絕函數(shù)起始縮進(jìn)位置與結(jié)束縮進(jìn)位置不同的現(xiàn)象。

例如，符合標(biāo)準(zhǔn)的定義：

不符合標(biāo)準(zhǔn)的定義：

4.3.5. 引號(hào)

PHP中單引號(hào)和雙引號(hào)具有不同的含義，最大的幾項(xiàng)區(qū)別如下：

單引號(hào)中，任何變量($var)、特殊轉(zhuǎn)義字符(如“ ”等)不會(huì)被解析，因此PHP的解析速度更快，轉(zhuǎn)義字符僅僅支持“’”和“”這樣對(duì)單引號(hào)和反斜杠本身的轉(zhuǎn)義；

雙引號(hào)中，變量($var)值會(huì)代入字符串中，特殊轉(zhuǎn)義字符也會(huì)被解析成特定的單個(gè)字符，還有一些專門針對(duì)上述兩項(xiàng)特性的特殊功能性轉(zhuǎn)義，例如“$”和“{$array[‘key’]}。這樣雖然程序編寫更加方便，但同時(shí)PHP的解析也很慢；

數(shù)組中，如果下標(biāo)不是整型，而是字符串類型，請(qǐng)務(wù)必用單引號(hào)將下標(biāo)括起，正確的寫法為$array[‘key’]，而不是$array[key]，因?yàn)椴徽_的寫法會(huì)使PHP解析器認(rèn)為key是一個(gè)常量，進(jìn)而先判斷常量是否存在，不存在時(shí)才以“key”作為下標(biāo)帶入表達(dá)式中，同時(shí)出發(fā)錯(cuò)誤事件，產(chǎn)生一條Notice級(jí)錯(cuò)誤。

因此，在絕大多數(shù)可以使用單引號(hào)的場(chǎng)合，禁止使用雙引號(hào)。依據(jù)上述分析，可以或必須使用單引號(hào)的情況包括但不限于下述：

● 字符串為固定值，不包含“ ”等特殊轉(zhuǎn)義字符；

● 數(shù)組的固定下標(biāo)，例如$array[‘key’]；

● 表達(dá)式中不需要帶入變量，例如$string = ‘test’;，而非$string = “test$var”；

例外的，在正則表達(dá)式(用于preg_系列函數(shù)和ereg系列函數(shù))中，Discuz!全部使用雙引號(hào)，這是為了人工分析和編寫的方便，并保持正則表達(dá)式的統(tǒng)一，減少不必要的分析混淆。

數(shù)據(jù)庫(kù)SQL語(yǔ)句中，所有數(shù)據(jù)必須加單引號(hào)，無(wú)論數(shù)值還是字串，以避免可能的注入漏洞和SQL錯(cuò)誤。正確的寫法為：

所有數(shù)據(jù)在插入數(shù)據(jù)庫(kù)之前，均需要進(jìn)行addslashes()處理，以免特殊字符未經(jīng)轉(zhuǎn)義在插入數(shù)據(jù)庫(kù)的時(shí)候出現(xiàn)錯(cuò)誤。Discuz!中如果已經(jīng)引入了文件 common.inc.php，則所有通過(guò) GET, POST, FILE,取得的變量默認(rèn)情況下已經(jīng)使用了addslashes()進(jìn)行了轉(zhuǎn)義，不必重復(fù)進(jìn)行。如果數(shù)據(jù)處理必要(例如用于直接顯示)，可以使用 stripslashes() 恢復(fù)，但數(shù)據(jù)在插入數(shù)據(jù)庫(kù)之前必須再次進(jìn)行轉(zhuǎn)義。

緩存文件中，一般對(duì)緩存數(shù)據(jù)的值采用 addcslashes($string, ''')進(jìn)行轉(zhuǎn)義。

4.4. 命名原則

命名是程序規(guī)劃的核心。古人相信只要知道一個(gè)人真正的名字就會(huì)獲得凌駕于那個(gè)人之上的不可思議的力量。只要你給事物想到正確的名字，就會(huì)給你以及后來(lái)的人帶來(lái)比代碼更強(qiáng)的力量。

名字就是事物在它所處的生態(tài)環(huán)境中一個(gè)長(zhǎng)久而深遠(yuǎn)的結(jié)果?？偟膩?lái)說(shuō)，只有了解系統(tǒng)的程序員才能為系統(tǒng)取出最合適的名字。如果所有的命名都與其自然相適合，則關(guān)系清晰，含義可以推導(dǎo)得出，一般人的推想也能在意料之中。

就一般約定而言，類、函數(shù)和變量的名字應(yīng)該總是能夠描述讓代碼閱讀者能夠容易的知道這些代碼的作用。形式越簡(jiǎn)單、越有規(guī)則，就越容易讓人感知和理解。應(yīng)該避免使用模棱兩可，晦澀不標(biāo)準(zhǔn)的命名。

4.4.1. 變量、對(duì)象、函數(shù)名

變量、對(duì)象、函數(shù)名一律為小寫格式，除非必要，單詞之間一般不使用下劃線“_”進(jìn)行分割；

以標(biāo)準(zhǔn)計(jì)算機(jī)英文為藍(lán)本，杜絕一切拼音、或拼音英文混雜的命名方式；

變量命名只能使用項(xiàng)目中有據(jù)可查的英文縮寫方式，例如可以使用$data而不可使用$data1、$data2這樣容易產(chǎn)生混淆的形式，應(yīng)當(dāng)使用$threaddata、$postdata這樣一目了然容易理解的形式；

可以合理的對(duì)過(guò)長(zhǎng)的命名進(jìn)行縮寫，例如$bio($biography)，$tpp($threadsPerPage)，前提是英文中有這樣既有的縮寫形式，或字母符合英文縮寫規(guī)范；

必須清楚所使用英文單詞的詞性，在權(quán)限相關(guān)的范圍內(nèi)，大多使用$allow***或$is***的形式，前者后面接動(dòng)詞，后者后面接形容詞。

4.4.2. 常量

常量應(yīng)該總是全部使用大寫字母命名，少數(shù)特別必要的情況下，可使用劃線來(lái)分隔單詞；

PHP 的內(nèi)建值 TRUE、FALSE 和NULL必須全部采用大寫字母書寫。

4.5. 變量的初始化與邏輯檢查

任何變量在進(jìn)行累加、直接顯示或存儲(chǔ)前必需進(jìn)行初使化，例如：

判斷一個(gè)無(wú)法確定（不知道是否已被賦值）的變量時(shí)，可用empty()或isset()，而不要直接使用if($switch)的形式，除非你確切的知道此變量一定已經(jīng)被初始化并賦值。

empty()和isset()的區(qū)別為：

● bool empty(mixed var)

? 如果 var 是非空或非零的值，則 empty() 返回 FALSE。換句話說(shuō)，""、0、"0"、NULL、FALSE、array()、var $var; 以及沒(méi)有任何屬性的對(duì)象都將被認(rèn)為是空的，如果 var 為空，則返回 TRUE。

● bool isset(mixed var[, mixed var[, ...]])

? 如果 var 存在則返回 TRUE，否則返回 FALSE。

? 如果已經(jīng)使用 unset() 釋放了一個(gè)變量之后，它將不再是 isset()。若使用 isset() 測(cè)試一個(gè)被設(shè)置成 NULL 的變量，將返回 FALSE。同時(shí)要注意的是一個(gè) NULL 字節(jié)（"?"）并不等同于 PHP 的 NULL 常數(shù)。

判斷一個(gè)變量是否為數(shù)組，請(qǐng)使用is_array()，這種判斷尤其適用于對(duì)數(shù)組進(jìn)行遍歷的操作，例如foreach()，因?yàn)槿绻皇孪扰袛?，foreach()會(huì)對(duì)非數(shù)組類型的變量報(bào)錯(cuò)；

判斷一個(gè)數(shù)組元素是否存在，可使用isset($array[‘key’])，也可使用empty()，兩者異同見上。

4.6. 安全性

PHP中的變量不并不像C語(yǔ)言那樣需要事先聲明，解釋器會(huì)在第一次使用時(shí)自動(dòng)創(chuàng)建他們，同樣類型也不需要指定，解釋器會(huì)根據(jù)上下文環(huán)境自動(dòng)確定。從開發(fā)人員的角度來(lái)看，這無(wú)疑是一種極其方便的處理方法。一個(gè)變量被創(chuàng)建了，就可以在程序中的任何地方使用。這導(dǎo)致的結(jié)果就是開發(fā)人員工經(jīng)常不注意初始化變量。因此，為了提高程序的安全性，我們不能相信任何沒(méi)有明確定義的變量。所有的變量在定義使用前要初使化以防止惡意構(gòu)造提交的變量覆蓋程序中使用的變量。

細(xì)節(jié)可以閱讀（）這篇文檔，該文檔里羅列了PHP常見的安全問(wèn)題，閱讀該文檔是非常有必要的！

4.7. 兼容性

代碼設(shè)計(jì)應(yīng)當(dāng)兼顧PHP 高低版本的特性，當(dāng)前，應(yīng)仍然以PHP 4.0.6作為最低通過(guò)平臺(tái)，盡量不使用高版本PHP 新增的函數(shù)、常數(shù)或者常量。如果使用只在高版本才具備的函數(shù)，必須對(duì)其進(jìn)行二次封裝，自動(dòng)判斷當(dāng)前PHP版本，并自行編寫低版本下的兼容代碼；

對(duì)于個(gè)別函數(shù)，參數(shù)要求或者代碼要求應(yīng)當(dāng)以較為嚴(yán)格的PHP版本為準(zhǔn)；

除非必要，不要使用PHP擴(kuò)展模塊中的函數(shù)。使用時(shí)應(yīng)當(dāng)加入必要的判斷，當(dāng)服務(wù)器環(huán)境不支持此函數(shù)的時(shí)候，進(jìn)行必要的處理。文檔和程序中的功能說(shuō)明中，也應(yīng)加上兼容性說(shuō)明。

4.8. 代碼重用

代碼的有效重用可以減少效率的損失與資源的浪費(fèi)。在開發(fā)軟件項(xiàng)目時(shí)為了避免重復(fù)勞動(dòng)和浪費(fèi)時(shí)間。開發(fā)人員應(yīng)盡量提高現(xiàn)有代碼的重用率，同時(shí)將更多的精力用在新技術(shù)的應(yīng)用和新功能的創(chuàng)新開發(fā)上面。

● 在需要多次使用代碼，并且對(duì)于您希望實(shí)現(xiàn)的任務(wù)沒(méi)有可用的內(nèi)置 PHP 函數(shù)時(shí)，不吝嗇定義函數(shù)或類。開發(fā)者須根據(jù)功能、調(diào)用情況，將函數(shù)和類放置于相應(yīng)的.func.php或.class.php中。超過(guò)3行，實(shí)現(xiàn)相同功能的程序切勿在不同程序中多次出現(xiàn)，這是無(wú)法容忍和回避的問(wèn)題；

● 在任何時(shí)候都不要出現(xiàn)同一個(gè)程序中出現(xiàn)兩段或更多的相似代碼或相同代碼，即便在不同程序中，也應(yīng)盡力避免。開發(fā)者應(yīng)當(dāng)總是有能力找到避免代碼大段(超過(guò)10行)重復(fù)或類似的情況。

需要強(qiáng)調(diào)的是，本部分雖然篇幅較短，但卻是十分需要經(jīng)驗(yàn)，并將花費(fèi)開發(fā)者大量時(shí)間和精力去進(jìn)行優(yōu)化的部分，任何產(chǎn)品開發(fā)者必須時(shí)刻清楚和理解代碼重用的重要性和必要性，切實(shí)在增強(qiáng)產(chǎn)品效率、邏輯性和可讀性上下功夫，這是一名優(yōu)秀軟件開發(fā)者所必須具備的基本素質(zhì)。

4.9. 其他細(xì)節(jié)問(wèn)題

4.9.1. 錯(cuò)誤報(bào)告級(jí)別

在軟件開發(fā)和調(diào)試階段，請(qǐng)使用error_reporting(E_ALL);作為默認(rèn)的錯(cuò)誤報(bào)告級(jí)別，此級(jí)別最為嚴(yán)格，能夠報(bào)告程序中所有的錯(cuò)誤、警告和提示信息，以幫助開發(fā)者檢查和核對(duì)代碼，避免大多數(shù)安全性問(wèn)題和邏輯錯(cuò)誤、拼寫錯(cuò)誤。error_reporting()可以在./include/common.inc.php的頭幾行進(jìn)行設(shè)置。

在軟件發(fā)布時(shí)，請(qǐng)使用error_reporting(E_ERROR | E_WARNING | E_PARSE);作為默認(rèn)的錯(cuò)誤報(bào)告級(jí)別，以利于用戶使用并將無(wú)謂錯(cuò)誤提示信息降至最低。