一份比較全面的PHP開發編碼規範

一份比較全面的PHP開發編碼規範 這些年來多從事Linux下PHP和C相關的開發，帶過很多項目和團隊，下面是根據經驗整理的PHP編碼規範 ，可以用作給大家的範例和參考，根據需要進行取舍和修改！ （可能最新的一些php5的規範不夠完整，今後有機會保持更新！） 目錄 1 編寫目的 2 整體要求 3 安全規範 3.1 包含檔案 3.1.1 命名規則 3.1.2 存放規則 3.2 安全規則 3.3 一些針對PHP的規則 3.4 其它處理規則 3.4.1 對輸入參數值進行轉義處理 3.4.2 操作大HTML文本 4 編碼規範 4.1 命名規範 4.1.1 變量命名 4.1.2 類 4.1.3 方法或函數 4.1.4 縮寫詞 4.1.5 資料庫表名 4.1.6 資料庫字段 4.2 書寫規則 4.2.1 代碼縮進 4.2.2 大括号{ }書寫規則 4.2.3 小括号( )和函數、關鍵詞等 4.2.4 ＝符号書寫 4.2.5 if else swith for while等書寫 4.2.6 類的構造函數 4.2.7 語句斷行, 每行控制在80個字元以内 4.2.8 不要不可思議的數字 4.2.9 true/false和0/1判斷 4.2.10 避免嵌入式指派 4.2.11 錯誤傳回檢測規則 4.3 程式注釋 4.3.1 程式頭注釋塊 4.3.2 類的注釋 4.3.3 函數和方法的注釋 4.3.4 變量或者語句注釋 4.4 其他規範（建議） 4.4.1 php代碼标記 4.4.2 程式檔案名、目錄名 4.4.3 PHP項目通常的檔案目錄結構 4.4.4 PHP和HTML代碼的分離問題 4.4.5 PHP項目開發中的程式邏輯結構 5 特定環境下PHP編碼特殊規範 5.1 變量定義 5.2 引用的使用 5.3 變量的輸入輸出 1 編寫目的為了更好的提高技術部的工作效率，保證開發的有效性和合理性，并可最大程度的提高程式代碼的可讀 性和可重複利用性，指定此規範。開發團隊根據自己的實際情況，可以對本規範進行補充或裁減。 2 整體要求技術部php開發規範将參照PEAR的規範，基本采用PEAR指定的規範，在其基礎上增加、修改或删除部分适 合具體開發環境的規範。本規範隻針對PHP開發過程中編碼的規範，對于PHP開發項目中檔案、目錄、數 據庫等方面的規範，将不重點涉及。本規範包含了PHP開發時程式編碼中命名規範、代碼縮進規則、控制結構、函數調用、函數定義、注釋、 包含代碼、PHP标記、檔案頭的注釋塊、CVS标記、URL樣例、常量命名等方面的規則。 3 安全規範 3.1 包含檔案 3.1.1 命名規則提取出來具有通用函數的包含檔案，檔案字尾以.inc來命名，表明這是一個包含檔案。如果有多個.inc檔案需要包含多頁面，請把所有.inc檔案封裝在一個檔案裡面，具體到頁面隻需要包換 一個.inc檔案就可以了如:xxx_session.inc xxx_comm..inc xxx_setting.inc mysql_db.inc 把以上檔案以一下方式，封裝在xxx.basic.inc檔案裡面 require_once(”xxx_session.inc”); require_once(”xxx_comm.inc”); require_once(”xxx_setting.inc”); require_once(”mysql_db.inc”); 注：是否需要封裝到一個檔案，視情況而定，如果每個inc的功能是分散到不同的頁面使用的話，就不建 議封裝。 3.1.2 存放規則一般包含檔案不需要直接暴露給使用者，是以應該放在 Web Server通路不到的目錄，避免因為配置問題而 洩露設定資訊。 3.2 安全規則請參考産品安全檢查表。 輸入和輸出檢查是否做了HTML代碼的過濾可能出現的問題：如果有人輸入惡意的HTML代碼，會導緻竊取cookie, 産生惡意登入表單，和破壞網站檢查變量做資料庫操作之前是否做了escape 可能出現的問題：如果一個要寫入查詢語句的字元串變量包含了某些特殊的字元，比如引号(’ ,”)或 者分号(;) 可能造成執行了預期之外的操作。建議采用的方法：使用mysql_escape_string() 或實作類似功能的函數。檢查輸入數值的合法性可能出現的問題：異常的數值會造成問題。如果對輸入的數值不做檢查會造成不合法的或者錯誤的資料 存入UDB、存入其它的資料庫或者導緻意料之外的程式操作發生。舉例：如果程式以使用者輸入的參數值做為檔案名，進行檔案操作，惡意輸入系統檔案名會造成系統損毀。核實對cookie的使用以及對使用者資料的處理可能出現的問題：不正确的cookie使用可能造成使用者資料洩漏通路控制對内部使用的産品或者供合作方使用的産品，要考慮增加通路控制 logs 確定使用者的保密資訊沒有記在log中(例如：使用者的密碼) 確定對關鍵的使用者操作儲存了完整的使用者通路記錄 https 對敏感資料的傳輸要采用https 3.3 一些針對PHP的規則設定 register_globals = off (Y!PHP 已經禁止了register_globals，如果你使用Y!PHP可以不考慮這 項設定) 設定 error_reporting = E_ALL (Y!PHP 的預設設定），并且要修正所有的error和warning 将實際的操作放在被引用的檔案中。把引用檔案放到不可以被直接浏覽的目錄下 3.4 其它處理規則 3.4.1 對輸入參數值進行轉義處理頁面接到參數需要SQL操作，這時候需要做轉義，尤其需要注意”;”。如：$a = ” Let’s go ” ; $sql = “Insert into tmp(col) values(’$a’)” ; 這種情況出現錯誤的不确定性。 3.4.2 操作大HTML文本很多時候需要存放一大段HTML文本供頁面使用，象使用者定制頁頭頁腳等。需要剔除腳本标記，避免執行惡意php代碼。轉換”<"">“号，保證代碼完整。 4 編碼規範 4.1 命名規範制定統一的命名規範對于項目開發來說非常重要，不但可以養成程式員一個良好的開發習慣，還能增加 程式的可讀性、可移植性和可重用性，還能很好的提高項目開發的效率。 4.1.1 變量命名變量命名分為普通變量、靜态變量、局部變量、全局變量、Session變量等方面的命名規則。 4.1.1.1 普通變量普通變量命名遵循以下規則： a． 所有字母都使用小寫； b． 對于一個變量使用多個單詞的，使用’_'作為每個詞的間隔。例如：$base_dir、$red_rose_price等 4.1.1.2 靜态變量靜态變量命名遵循以下規則： a． 靜态變量使用小寫的s_開頭； b． 靜态變量所有字母都使用小寫； c． 多個單詞組成的變量名使用’_'作為每個詞的間隔。例子：$s_base_dir、$s_red_rose_prise等。 4.1.1.3 局部變量局部變量命名遵循以下規則： a． 所有字母使用小寫； b． 變量使用’_'開頭； c． 多個單詞組成的局部變量名使用’_'作為每個詞間的間隔。例子：$_base_dir、$_red_rose_price等。 4.1.1.4 全局變量全局變量應該帶字首’g',知道一個變量的作用域是非常重要的。例如 global $gLOG_LEVEL; global $gLOG_PATH; 4.1.1.5 全局常量全局變量命名遵循以下規則： a． 所有字母使用大寫 b． 全局變量多個單詞間使用’_'作為間隔。例子：$BASE_DIR、$RED_ROSE_PRICE等。 4.1.1.6 session變量 session變量命名遵循以下規則： a． 所有字母使用大寫； b． session變量名使用’S_’開頭； c． 多個單詞間使用’_'間隔。例子：$S_BASE_DIR、$S_RED_ROSE_PRICE等。 4.1.2 類 php中類命名遵循以下規則： a． 以大寫字母開頭； b． 多個單詞組成的變量名，單詞之間不用間隔，各個單詞首字母大寫。例子：class MyClass 或class DbOracle等。 4.1.3 方法或函數方法或函數命名遵循以下規則： a． 首字母小寫； b． 多個單詞間不使用間隔，除第一個單詞外，其他單詞首字母大寫。例子：function myFunction ()或function myDbOracle ()等。 4.1.4 縮寫詞當變量名或者其他命名中遇到縮寫詞時，參照具體的命名規則，而不采用縮寫詞原來的全部大寫的方式 。例子：function myPear（不是myPEAR） functio getHtmlSource（不是getHTMLSource）。 4.1.5 資料庫表名資料庫表名命名遵循以下規範： a． 表名均使用小寫字母； b． 對于普通資料表，使用_t結尾； c． 對于視圖，使用_v結尾； d． 對于多個單詞組成的表名，使用_間隔；例子：user_info_t和book_store_v等 4.1.6 資料庫字段資料庫字段命名遵循以下規範： a． 全部使用小寫； b． 多個單詞間使用_間隔。例子：user_name、rose_price等。 4.2 書寫規則書寫規則是指在編寫php程式時，代碼書寫的規則，包括縮進、結構控制等方面規範： 4.2.1 代碼縮進在書寫代碼的時候，必須注意代碼的縮進規則，我們規定代碼縮進規則如下： a． 使用4個空格作為縮進，而不使用tab縮進（對于ultraedit，可以進行預先設定）例子： for ( $i=0;$i<$count;$i++ ) { echo "test"; } 4.2.2 大括号{ }書寫規則在程式中進行結構控制代碼編寫，如if、for、while、switch等結構，大括号傳統的有兩種書寫習慣， 分别如下： a．{直接跟在控制語句之後，不換行，如 for ($i=0;$i<$count;$i++) { echo "test"; } b．{在控制語句下一行，如 for($i=0;$i<$count;$i++) { echo "test"; } 其中，a是PEAR建議的方式，但是從實際書寫中來講，這并不影響程式的規範和影響用phpdoc實作文檔， 是以可以根據個人習慣來采用上面的兩種方式，但是要求在同一個程式中，隻使用其中一種，以免造成 閱讀的不友善。 4.2.3 小括号( )和函數、關鍵詞等小括号、關鍵詞和函數遵循以下規則： a． 不要把小括号和關鍵詞緊貼在一起，要用一個空格間隔；如if ( $a<$b )； b． 小括号和函數名間沒有空格；如$test = date("ymdhis")； c． 除非必要，不要在Return傳回語句中使用小括号。 如Return $a； 4.2.4 ＝符号書寫在程式中=符号的書寫遵循以下規則： a． 在=符号的兩側，均需留出一個空格；如$a = $b 、if ($a = = $b)等； b． 在一個申明塊，或者實作同樣功能的一個塊中，要求=号盡量上下對其，左邊可以為了保持對齊使用 多個空格，而右邊要求空一個空格；如下例： $testa = $aaa; $testaa = $bbb; $testaaa = $ccc; 4.2.5 if else swith for while等書寫對于控制結構的書寫遵循以下規則： a． 在if條件判斷中，如果用到常量判斷條件，将常量放在等号或不等号的左邊，例如： if ( 6 == $errorNum )，因為如果你在等式中漏了一個等号，文法檢查器會為你報錯，可以很快找到錯 誤位置，這樣的寫法要多注意； b． switch結構中必須要有default塊； c． 在for和wiile的循環使用中，要警惕continue、break的使用，避免産生類似goto的問題； 4.2.6 類的構造函數如果要在類裡面編寫構造函數，必須遵循以下規則： a． 不能在構造函數中有太多實際操作，頂多用來初始化一些值和變量； b． 不能在構造函數中因為使用操作而傳回false或者錯誤，因為在聲明和執行個體化一個對象的時候，是不 能傳回錯誤的； 4.2.7 語句斷行, 每行控制在80個字元以内在代碼書寫中，遵循以下原則： a． 盡量保證程式語句一行就是一句，而不要讓一行語句太長産生折行； b． 盡量不要使一行的代碼太長，一般控制在80個字元以内； c． 如果一行代碼太長，請使用類似 .= 的方式斷行書寫； d． 對于執行資料庫的sql語句操作，盡量不要在函數内寫sql語句，而先用變量定義sql語句，然後在執 行操作的函數中調用定義的變量；例子： $sql = "SELECT username,password,address,age,postcode FROM test_t "; $sql .= " WHERE username='aaa'"; $res = mysql_query($sql); 4.2.8 不要不可思議的數字一個在源代碼中使用了的赤裸裸的數字是不可思議的數字，因為包括作者，在三個月内，沒人它的含義 。例如： if (22 == $foo) { start_thermo_nuclear_war(); } else if (19 == $foo) { refund_lotso_money(); } else { cry_cause_im_lost(); } 你應該用define()來給你想表示某樣東西的數值一個真正的名字，而不是采用赤裸裸的數字，例如： define("PRESIDENT_WENT_CRAZY", "22"); define("WE_GOOFED", "19"); define("THEY_DIDNT_PAY", "16"); if ( PRESIDENT_WENT_CRAZY == $foo) { start_thermo_nuclear_war(); } else if (WE_GOOFED == $foo) { refund_lotso_money(); } else if (THEY_DIDNT_PAY == $foo) { infinite_loop(); } else { happy_days_i_know_why_im_here(); } 4.2.9 true/false和0/1判斷遵循以下規則： a． 不能使用0/1代替true/false，在PHP中，這是不相等的； b． 不要使用非零的表達式、變量或者方法直接進行true/false判斷，而必須使用嚴格的完整 true/false判斷；如：不使用if ($a) 或者if (checka()) 而使用if (FALSE != $a)或者 if (FALSE != check()) 4.2.10 避免嵌入式指派在程式中避免下面例子中的嵌入式指派：不使用這樣的方式： while ($a != ($c = getchar())) { process the character } 4.2.11 錯誤傳回檢測規則檢查所有的系統調用的錯誤資訊，除非你要忽略錯誤。為每條系統錯誤消息定義好系統錯誤文本，并記錄錯誤LOG。 4.3 程式注釋每個程式均必須提供必要的注釋，書寫注釋要求規範，參照PEAR提供的注釋要求，為今後利用phpdoc生 成php文檔做準備。程式注釋的原則如下： a． 注釋中除了檔案頭的注釋塊外，其他地方都不使用//注釋，而使用的注釋； b． 注釋内容必須寫在被注釋對象的前面，不寫在一行或者後面； 4.3.1 程式頭注釋塊每個程式頭部必須有統一的注釋塊，規則如下： a． 必須包含本程式的描述； b． 必須包含作者； c． 必須包含書寫日期； d． 必須包含版本資訊； e． 必須包含項目名稱； f． 必須包含檔案的名稱； g． 重要的使用說明，如類的調用方法、注意事項等；參考例子如下： // // +---------------------------------------------------------+ // | PHP version 4.0 | // +---------------------------------------------------------+ // | Copyright (c) 1997-2001 The PHP Group | // +---------------------------------------------------------+ // | This source file is subject to of the PHP license, | // | that is bundled with this packafile LICENSE, and is | // | available at through the world-web at | // | http://www.php.net/license/2_02.txt. | // | If you did not receive a copy of the and are unable to | // | obtain it through the world-wide-web,end a note to | // | [email protected] so we can mail you a immediately. | // +---------------------------------------------------------+ // | Authors: Stig Bakken | // | Tomas V.V.Cox | // | | // +---------------------------------------------------------+ // // $Id: Common.php,v 1.8.2.3 2001/11/13 01:26:48 ssb Exp $ 4.3.2 類的注釋類的注釋采用裡面的參考例子方式： class Database { …… } 4.3.3 函數和方法的注釋函數和方法的注釋寫在函數和方法的前面，采用類似下面例子的規則： function（$queryStr,$username） {……} 4.3.4 變量或者語句注釋程式中變量或者語句的注釋遵循以下原則： a． 寫在變量或者語句的前面一行，而不寫在同行或者後面； b． 注釋采用的方式； c． 每個函數前面要包含一個注釋塊。内容包括函數功能簡述，輸入/輸出參數，預期的傳回值，出錯代 碼定義。 d． 注釋完整規範。 e． 把已經注釋掉的代碼删除，或者注明這些已經注釋掉的代碼仍然保留在源碼中的特殊原因。 f．例子： var db_user_name; 4.4 其他規範（建議） 4.4.1 php代碼标記所有的php程式代碼塊标記均使用 4.4.2 程式檔案名、目錄名程式檔案名和目錄名命名均采用有意義的英文方式命名，不使用拼音或無意義的字母，同時均必須使用 小寫字母，多個詞間使用_間隔。 4.4.3 PHP項目通常的檔案目錄結建構議在開發規範的獨立的PHP項目時，使用規範的檔案目錄結構，這有助于提高項目的邏輯結構合理性， 對應擴充和合作，以及團隊開發均有好處。一個完整獨立的PHP項目通常的檔案和目錄結構如下： / 項目根目錄 /manage 背景管理檔案存放目錄 /css css檔案存放目錄 /doc 存放項目文檔 /images 所有圖檔檔案存放路徑（在裡面根據目錄結構設立子目錄） /scripts 用戶端js腳本存放目錄 /tpl 網站所有html的模版檔案存放目錄 /error.php 錯誤處理檔案（可以定義到apache的錯誤進行中） 以上目錄結構是通常的目錄結構，根據具體應用的具體情況，可以考慮不用完全遵循，但是盡量做到規 範化。 4.4.4 PHP和HTML代碼的分離問題對性能要求不是很高的項目和應用，我們建議不采用PHP和HTML代碼直接混排的方式書寫代碼，而采用 PHP和HTML代碼分離的方式，即采用模版的方式處理，這樣一方面對程式邏輯結構更加清晰有利，也有助 于開發過程中人員的分工安排，同時還對日後項目的頁面更新該版提供更多便利。對于一些特殊情況，比如對性能要求很高的應用，可以不采用模版方式。 4.4.5 PHP項目開發中的程式邏輯結構對于PHP項目開發，盡量采用OOP的思想開發，尤其在PHP5以後，對于面向對象的開發功能大大提高。在PHP項目中，我們建議将獨立的功能子產品盡量寫成函數調用，對應一整塊業務邏輯，我們建議封裝成類 ，既可以提高代碼可讀性，也可以提高代碼重用性。比如，我們通常将對資料庫的接口封裝成資料庫類 ，有利于平台的移植。重複的代碼要做成公共的庫。（除了我們在plug-in産品上遇到的情況，該産品系列有多個相類似的産品 ，為了盡可能地減少安裝包尺寸，不适合将這些産品共用的所有函數做成公共的庫） 5 特定環境下PHP編碼特殊規範 5.1 變量定義 XXX環境下的php代碼編寫要求所有的變量均需要先申明後使用，否則會有錯誤資訊，對于數組，在使用 一個不确定的key時，比如先進行isset()的判斷，然後再使用；比如下面的代碼： $array ＝ array(); $var ＝ isset($array[3]) ? $array[3] : “”； 5.2 引用的使用引用在程式中使用比較多，為了公用同一個記憶體，而不需要另外進行複制，XXX環境下的引用使用時，需 要注意下面的情況；在對函數的輸入參數中使用引用時，不能在調用的時候在輸入參數前加&來引用，而直接使用該變量即可 ，同時必須在函數定義的時候說明輸入參數來自引用，比如下面的代碼： $a ＝ 1； function ab(&$var) { $var ++； return $var； } $b ＝ ab($a) // 注意，此處不能使用 $b ＝ ab(&$a)的方式； echo $b.”/n”； echo $a.”/n”；此時 $a和$b都是2； XXX環境下對引用的特殊要求源自php.ini檔案裡面的allow_call_time_pass_reference 項設定， 對外 公開的版本是 On ，這樣就可以支援&直接加到調用函數時變量前面進行引用，但是這一方法遭到抗議， 并可能在将來版本的PHP/Zend裡不再支援。受到鼓勵的指定哪些參數按引用傳遞的方法是在函數聲明裡 。你被鼓勵嘗試關閉這一選項（使用 off，XXX的所有運作環境下都是off）并确認你的腳本仍能正常工 作，以保證在将來版本的語言裡它們仍能工作。 5.3 變量的輸入輸出在XXX環境下，對web通過GET或者POST方法傳遞來的參數均要求進行嚴格的過濾和合法性驗證，不推薦使 用直接的$_GET、$_POST或者$_REQUEST擷取，而通過XXX的XXX_yiv子產品提供的方法擷取和過濾處理 規範完