PHP 的一些开发规范
長篇慎入
分以下幾點說明
- 一些編碼的經驗
- PSR-1
- PSR-2
- PSR-3
- PSR-4
一些編碼的經驗
變量命名
代碼注釋
代碼備份
使用 github, 本地留一份
編碼統一
PHP編碼 == HTML編碼 == 數據庫編碼 == UTF-8
header("Content-type: text/html; charset=utf-8");路徑常量
所有路徑和URL盡量使用常量進行存放
不寫結束標記 ?>
<?php//code錯誤記錄
- 開發環境開啟錯誤調試
E_ERROR
E_WARNING
E_NOTICE
生產環境寫入日志中
千萬別用 @ 符號屏蔽錯誤
變量使用
不規范
array_push($arr, 'test');規范
$arr = []; array_push($arr, 'test');不規范
echo $_GET[name];規范
echo $_GET['name'];不規范
for ($i=0; $i<strlen($data); $i++){// code }規范
$len = strlen($data); for ($i=0; $i<$len $i++){// code }函數使用
strtr 比 str_replace 快四倍
使用 microtime 檢測執行時間
返回值: 操作類函數返回ture/false, 數據類函數返回data/null
盡量使用內置函數,少用正則
對所有外部輸入變量進行校驗
用戶輸入,函數傳值時, 應該考慮到:
為空的情況
畸形數據如SQL注入
溢出或變量類型不一致
不要相信數據的可靠性
對于SQL注入,可以使用 PDO
對于XSS攻擊,htmlspecialchars 只能防御一小部分
語法糖
對于某個功能,在添加新的語法形式時,對功能本身不造成影響,且新的語法方便程序員使用
下面這些均不時函數,算是內置的指令
echo() print() die() exit() unset() isset() include() include_once() require() require_once() array() list() empty() eval()其他的一些語法糖, 均下一行寫法比上一行寫法好點
echo $a . $b; echo $a , $b; echo strlen($str) === 5; echo isset($str[4]) $arr = array(); $arr = []; function sum($a, $b, $c, $d, $e){return $a + $b + $c + $d + $e; }function sum(...$n){return array_sum($n); }eval 的防御
php.ini 的 disbale_function 只能禁用函數,但eval不屬于函數
使用 suhosin 來防御
php.ini
suhosin.executor.disable_eval = on代碼簡化
if else 簡化
if (1 == $orderState)$status = 'success'; else$status = 'error';return $status; $status = 'error';if ( 1== $orderState)$status = 'success';return $status;空值賦予默認簡化
if (!empty($_POST['action']))$action = $_POST['action']; else$action = 'default'; $action = $_POST['action'] ?? 'default';中間值提高可讀性
return implode('', array_map('ucfirst', explode('_', 'this_is_test'))); $str = 'this_is_test'; $words = explode('_', $str); $uWords = array_map('ucfirst', $words); $res = implode('', $uWords);代碼長度
函數長度保持 50-150行內
函數參數長度 不超過7個
函數只做一件事情,易于復用
標準規范
PSR
關鍵詞:
- 必須 (must)
- 不能 (must not)
- 需要 (required)
- 將會 (shall)
- 不會 (shall not)
- 應該 (should)
- 不該 (should not)
- 推薦 (recommended)
- 可以 (may)
- 可選 (optional)
詳情參見 RFC2119
PSR-0(廢棄)
PSR-1
- PHP標簽
PHP代碼必須使用 <?php ?> 長標簽 或 <?= ?> 短輸出標簽; 一定不可使用其它自定義標簽。
- 字符編碼
PHP代碼必須且只可使用不帶BOM的UTF-8編碼。
- 從屬效應
一份PHP文件中應該要不就只定義新的聲明,如類、函數或常量等不產生從屬效應的操作,要不就只有會產生從屬效應的邏輯操作,但不該同時具有兩者。
從屬效應(side effects)意思是: 僅僅通過包含文件,不直接聲明類、 函數和常量等,而執行的邏輯操作。
從屬效應包含卻不僅限于:
...
以下是一個錯誤的例子,一份包含聲明以及產生從屬效應的代碼:
<?php // 從屬效應:修改 ini 配置 ini_set('error_reporting', E_ALL);// 從屬效應:引入文件 include "file.php";// 從屬效應:生成輸出 echo "<html>\n";// 聲明函數 function foo() {// 函數主體部分 }下面是一個范例,一份只包含聲明不產生從屬效應的代碼:
<?php // 聲明函數 function foo() {// 函數主體部分 }// 條件聲明**不**屬于從屬效應 if (! function_exists('bar')) {function bar(){// 函數主體部分} }- 命名空間和類
命名空間以及類的命名必須遵循 PSR-4
根據規范,每個類都獨立為一個文件,且命名空間至少有一個層次:頂級的組織名稱(vendor name)。
類的命名必須 遵循 StudlyCaps 大寫開頭的駝峰命名規范。
PHP 5.3及以后版本的代碼必須使用正式的命名空間。
例如:
<?php // PHP 5.3及以后版本的寫法 namespace Vendor\Model;class Foo { }5.2.x及之前的版本應該使用偽命名空間的寫法,約定俗成使用頂級的組織名稱(vendor name)如 Vendor_ 為類前綴。
<?php // 5.2.x及之前版本的寫法 class Vendor_Model_Foo { }類的常量、屬性和方法
此處的“類”指代所有的類、接口以及可復用代碼塊(traits)
- 常量
類的常量中所有字母都必須大寫,詞間以下劃線分隔。 參照以下代碼:
<?php namespace Vendor\Model;class Foo {const VERSION = '1.0';const DATE_APPROVED = '2012-06-01'; }- 方法
方法名稱必須符合 camelCase() 式的小寫開頭駝峰命名規范。
- 屬性
類的屬性命名可以遵循:
本規范不做強制要求,但無論遵循哪種命名方式,都應該在一定的范圍內保持一致。
這個范圍可以是整個團隊、整個包、整個類或整個方法。
PSR-2
本篇規范是 PSR-1 基本代碼規范的繼承與擴展。
本規范希望通過制定一系列規范化PHP代碼的規則,以減少在瀏覽不同作者的代碼時,因代碼風格的不同而造成不便。
當多名程序員在多個項目中合作時,就需要一個共同的編碼規范, 而本文中的風格規范源自于多個不同項目代碼風格的共同特性, 因此,本規范的價值在于我們都遵循這個編碼風格,而不是在于它本身。
符合規范的小例子
<?php namespace Vendor\Package;use FooInterface; use BarClass as Bar; use OtherVendor\OtherPackage\BazClass;class Foo extends Bar implements FooInterface {public function sampleFunction($a, $b = null){if ($a === $b) {bar();} elseif ($a > $b) {$foo->bar($arg1);} else {BazClass::bar($arg2, $arg3);}}final public static function bar(){// method body} }- 編碼基準
必須遵守 PSR-1
- 文件
所有PHP文件必須使用Unix LF (linefeed)作為行的結束符。
所有PHP文件必須以一個空白行作為結束。
純PHP代碼文件必須省略最后的 ?> 結束標簽。
- 行
行的長度一定不能有硬性的約束。
軟性的長度約束一定要限制在120個字符以內,若超過此長度,帶代碼規范檢查的編輯器一定要發出警告,不過一定不可發出錯誤提示。
每行不應該多于80個字符,大于80字符的行應該折成多行。
非空行后一定不能有多余的空格符。
空行可以使得閱讀代碼更加方便以及有助于代碼的分塊。
每行一定不能存在多于一條語句。
- 縮進
代碼必須使用4個空格符的縮進,一定不能用 tab鍵 。
備注: 使用空格而不是tab鍵縮進的好處在于, 避免在比較代碼差異、打補丁、重閱代碼以及注釋時產生混淆。 并且,使用空格縮進,讓對齊變得更方便。- 關鍵字
PHP所有 關鍵字必須全部小寫。
常量 true false null 也必須全部小寫。
- namespace 以及 use 聲明
namespace 聲明后必須插入一個空白行。
所有 use 必須在 namespace 后。
每條 use 聲明語句必須只有一個 use 關鍵詞。
use 聲明語句塊后必須要有一個空白行。
如
<?php namespace Vendor\Package;use FooClass; use BarClass as Bar; use OtherVendor\OtherPackage\BazClass;// ... additional PHP code ...- 擴展與繼承
關鍵詞 extends 和 implements 必須寫在類名稱的同一行
<?php namespace Vendor\Package;use FooClass; use BarClass as Bar; use OtherVendor\OtherPackage\BazClass;class ClassName extends ParentClass implements \ArrayAccess, \Countable {// constants, properties, methods }implements 的繼承列表也可以分成多行,這樣的話,每個繼承接口名稱都必須分開獨立成行,包括第一個。
<?php namespace Vendor\Package;use FooClass; use BarClass as Bar; use OtherVendor\OtherPackage\BazClass;class ClassName extends ParentClass implements\ArrayAccess,\Countable,\Serializable {// constants, properties, methods }- 屬性
每個屬性都必須添加訪問修飾符。
一定不可使用關鍵字 var 聲明一個屬性。
每條語句一定不可定義超過一個屬性。
不要使用下劃線作為前綴,來區分屬性是 protected 或 private。
以下是屬性聲明的一個范例:
<?php namespace Vendor\Package;class ClassName {public $foo = null; }- 方法
所有方法都必須添加訪問修飾符。
不要使用下劃線作為前綴,來區分方法是 protected 或 private。
方法名稱后一定不能有空格符,其開始花括號必須獨占一行,結束花括號也必須在方法主體后單獨成一行。參數左括號后和右括號前一定不能有空格。
一個標準的方法聲明可參照以下范例,留意其括號、逗號、空格以及花括號的位置。
<?php namespace Vendor\Package;class ClassName {public function fooBarBaz($arg1, &$arg2, $arg3 = []){// method body} }- 方法的參數
參數列表中,每個逗號后面必須要有一個空格,而逗號前面一定不能有空格。
有默認值的參數,必須放到參數列表的末尾。
<?php namespace Vendor\Package;class ClassName {public function foo($arg1, &$arg2, $arg3 = []){// method body} }參數列表可以分列成多行,這樣,包括第一個參數在內的每個參數都必須單獨成行。
拆分成多行的參數列表后,結束括號以及方法開始花括號 必須 寫在同一行,中間用一個空格分隔。
<?php namespace Vendor\Package;class ClassName {public function aVeryLongMethodName(ClassTypeHint $arg1,&$arg2,array $arg3 = []) {// method body} }- abstract 、 final 、 以及 static
需要添加 abstract 或 final 聲明時, 必須寫在訪問修飾符前,而 static 則必須寫在其后。
<?php namespace Vendor\Package;abstract class ClassName {protected static $foo;abstract protected function zim();final public static function bar(){// method body} }4.6. 方法及函數調用
方法及函數調用時,方法名或函數名與參數左括號之間一定不能有空格,參數右括號前也 一定不能有空格。每個逗號前一定不能有空格,但其后必須有一個空格。
參數可以分列成多行,此時包括第一個參數在內的每個參數都必須單獨成行。
<?php $foo->bar($longArgument,$longerArgument,$muchLongerArgument );- 控制結構
控制結構的基本規范如下:
控制結構關鍵詞后必須有一個空格。
左括號 ( 后一定不能有空格。
右括號 ) 前也一定不能有空格。
右括號 ) 與開始花括號 { 間一定有一個空格。
結構體主體一定要有一次縮進。
結束花括號 } 一定在結構體主體后單獨成行。
每個結構體的主體都必須被包含在成對的花括號之中, 這能讓結構體更加結構化,以及減少加入新行時,出錯的可能性。
- if 、 elseif 和 else
標準的 if 結構如下代碼所示,留意 括號、空格以及花括號的位置, 注意 else 和 elseif 都與前面的結束花括號在同一行。
<?php if ($expr1) {// if body } elseif ($expr2) {// elseif body } else {// else body; }應該使用關鍵詞 elseif 代替所有 else if ,以使得所有的控制關鍵字都像是單獨的一個詞。
- switch 和 case
標準的 switch 結構如下代碼所示,留意括號、空格以及花括號的位置。
case 語句必須相對 switch 進行一次縮進,
而 break 語句以及 case 內的其它語句都 必須 相對 case 進行一次縮進。
如果存在非空的 case 直穿語句,主體里必須有類似 // no break 的注釋。
<?php switch ($expr) {case 0:echo 'First case, with a break';break;case 1:echo 'Second case, which falls through';// no breakcase 2:case 3:case 4:echo 'Third case, return instead of break';return;default:echo 'Default case';break; }- while 和 do while
一個規范的 while 語句應該如下所示,注意其 括號、空格以及花括號的位置。
標準的 do while 語句如下所示,同樣的,注意其 括號、空格以及花括號的位置。
<?php do {// structure body; } while ($expr);- for
標準的 for 語句如下所示,注意其 括號、空格以及花括號的位置。
- foreach
標準的 foreach 語句如下所示,注意其 括號、空格以及花括號的位置。
- try, catch
標準的 try catch 語句如下所示,注意其 括號、空格以及花括號的位置。
- 閉包
閉包聲明時,關鍵詞 function 后以及關鍵詞 use 的前后都必須要有一個空格。
開始花括號必須寫在聲明的同一行,結束花括號必須緊跟主體結束的下一行。
參數列表和變量列表的左括號后以及右括號前,必須不能有空格。
參數和變量列表中,逗號前必須不能有空格,而逗號后必須要有空格。
閉包中有默認值的參數必須放到列表的后面。
標準的閉包聲明語句如下所示,注意其 括號、逗號、空格以及花括號的位置。
<?php $closureWithArgs = function ($arg1, $arg2) {// body };$closureWithArgsAndVars = function ($arg1, $arg2) use ($var1, $var2) {// body };參數列表以及變量列表可以分成多行,這樣,包括第一個在內的每個參數或變量都必須單獨成行,而列表的右括號與閉包的開始花括號必須放在同一行。
以下幾個例子,包含了參數和變量列表被分成多行的多情況。
<?php $longArgs_noVars = function ($longArgument,$longerArgument,$muchLongerArgument ) {// body };$noArgs_longVars = function () use ($longVar1,$longerVar2,$muchLongerVar3 ) {// body };$longArgs_longVars = function ($longArgument,$longerArgument,$muchLongerArgument ) use ($longVar1,$longerVar2,$muchLongerVar3 ) {// body };$longArgs_shortVars = function ($longArgument,$longerArgument,$muchLongerArgument ) use ($var1) {// body };$shortArgs_longVars = function ($arg) use ($longVar1,$longerVar2,$muchLongerVar3 ) {// body };注意,閉包被直接用作函數或方法調用的參數時,以上規則仍然適用。
<?php $foo->bar($arg1,function ($arg2) use ($var1) {// body},$arg3 );- 多行參數 (09/08/2013)
使用一個或多個跨行的參數(如數組和匿名函數)并不需要觸發 4.6 節中關于參數列表的單行規定, 因此,在參數表中的數組和匿名函數是可以單獨分列成多行的。
以下的例子是符合 PSR-2 規范的:
<?php somefunction($foo, $bar, [// ... ], $baz);$app->get('/hello/{name}', function ($name) use ($app) { return 'Hello '.$app->escape($name);- 總結
以上規范難免有疏忽,其中包括但不僅限于:
全局變量和常量的定義
函數的定義
操作符和賦值
行內對齊
注釋和文檔描述塊
類名的前綴及后綴
最佳實踐
本規范之后的修訂與擴展將彌補以上不足。
PSR-3
日志接口規范
本文制定了日志類庫的通用接口規范。
本規范的主要目的,是為了讓日志類庫以簡單通用的方式,
通過接收一個 Psr\Log\LoggerInterface 對象,來記錄日志信息。
框架以及CMS內容管理系統如有需要,可以對此接口進行擴展,
但需遵循本規范,這才能保證在使用第三方的類庫文件時,日志接口仍能正常對接。
- LoggerInterface 接口對外定義了八個方法,分別用來記錄 RFC 5424 中定義的八個等級的日志:
- 第九個方法 —— log,其第一個參數為記錄的等級。可使用一個預先定義的等級常量作為參數來調用此方法,必須與直接調用以上八個方法具有相同的效果。
如果傳入的等級常量參數沒有預先定義,則必須拋出 Psr\Log\InvalidArgumentException 類型的異常。
在不確定的情況下,使用者不該使用未支持的等級常量來調用此方法。
1.2 記錄信息
以上每個方法都接受一個字符串類型或者是有 __toString() 方法的對象作為記錄信息參數,這樣,實現者就能把它當成字符串來處理,否則實現者必須自己把它轉換成字符串。
記錄信息參數可以攜帶占位符,實現者可以根據上下文將其它替換成相應的值。
其中占位符必須與上下文數組中的鍵名保持一致。
占位符的名稱必須由一個左花括號 { 以及一個右括號 } 包含。但花括號與名稱之間一定不能有空格符。
占位符的名稱應該只由 A-Z、 a-z,0-9、下劃線 _、以及英文的句號 .組成,其它字符作為將來占位符規范的保留。
實現者可以通過對占位符采用不同的轉義和轉換策略,來生成最終的日志。
而使用者在不知道上下文的前提下,不該提前轉義占位符。以下是一個占位符使用的例子:
/*** 用上下文信息替換記錄信息中的占位符*/ function interpolate($message, array $context = array()) {// 構建一個花括號包含的鍵名的替換數組$replace = array();foreach ($context as $key => $val) {$replace['{' . $key . '}'] = $val;}// 替換記錄信息中的占位符,最后返回修改后的記錄信息。return strtr($message, $replace); }// 含有帶花括號占位符的記錄信息。 $message = "User {username} created";// 帶有替換信息的上下文數組,鍵名為占位符名稱,鍵值為替換值。 $context = array('username' => 'bolivar');// 輸出 "Username bolivar created" echo interpolate($message, $context);
1.3 上下文
每個記錄函數都接受一個上下文數組參數,用來裝載字符串類型無法表示的信息。它可以裝載任何信息,所以實現者必須確保能正確處理其裝載的信息,對于其裝載的數據,一定不能 拋出異常,或產生PHP出錯、警告或提醒信息(error、warning、notice)。
如需通過上下文參數傳入了一個 Exception 對象, 必須以 'exception' 作為鍵名。
記錄異常信息是很普遍的,所以如果它能夠在記錄類庫的底層實現,就能夠讓實現者從異常信息中抽絲剝繭。
當然,實現者在使用它時,必須確保鍵名為 'exception' 的鍵值是否真的是一個 Exception,畢竟它可以裝載任何信息。
1.4 助手類和接口
Psr\Log\AbstractLogger 類使得只需繼承它和實現其中的 log 方法,就能夠很輕易地實現 LoggerInterface 接口,而另外八個方法就能夠把記錄信息和上下文信息傳給它。
同樣地,使用 Psr\Log\LoggerTrait 也只需實現其中的 log 方法。不過,需要特別注意的是,在traits可復用代碼塊還不能實現接口前,還需要 implement LoggerInterface。
在沒有可用的日志記錄器時, Psr\Log\NullLogger 接口可以為使用者提供一個備用的日志“黑洞”。不過,當上下文的構建非常消耗資源時,帶條件檢查的日志記錄或許是更好的辦法。
Psr\Log\LoggerAwareInterface 接口僅包括一個
setLogger(LoggerInterface $logger) 方法,框架可以使用它實現自動連接任意的日志記錄實例。Psr\Log\LoggerAwareTrait trait可復用代碼塊可以在任何的類里面使用,只需通過它提供的 $this->logger,就可以輕松地實現等同的接口。
Psr\Log\LogLevel 類裝載了八個記錄等級常量。
2. 包
上述的接口、類和相關的異常類,以及一系列的實現檢測文件,都包含在 psr/log 文件包中。
3. Psr\Log\LoggerInterface
<?phpnamespace Psr\Log;/*** 日志記錄實例** 日志信息變量 —— message, **必須**是一個字符串或是實現了 __toString() 方法的對象。** 日志信息變量中**可以**包含格式如 “{foo}” (代表foo) 的占位符,* 它將會由上下文數組中鍵名為 "foo" 的鍵值替代。** 上下文數組可以攜帶任意的數據,唯一的限制是,當它攜帶的是一個 exception 對象時,它的鍵名 必須 是 "exception"。** 詳情可參閱: https://github.com/PizzaLiu/PHP-FIG/blob/master/PSR-3-logger-interface-cn.md*/ interface LoggerInterface {/*** 系統不可用** @param string $message* @param array $context* @return null*/public function emergency($message, array $context = array());/*** **必須**立刻采取行動** 例如:在整個網站都垮掉了、數據庫不可用了或者其他的情況下,**應該**發送一條警報短信把你叫醒。** @param string $message* @param array $context* @return null*/public function alert($message, array $context = array());/*** 緊急情況** 例如:程序組件不可用或者出現非預期的異常。** @param string $message* @param array $context* @return null*/public function critical($message, array $context = array());/*** 運行時出現的錯誤,不需要立刻采取行動,但必須記錄下來以備檢測。** @param string $message* @param array $context* @return null*/public function error($message, array $context = array());/*** 出現非錯誤性的異常。** 例如:使用了被棄用的API、錯誤地使用了API或者非預想的不必要錯誤。** @param string $message* @param array $context* @return null*/public function warning($message, array $context = array());/*** 一般性重要的事件。** @param string $message* @param array $context* @return null*/public function notice($message, array $context = array());/*** 重要事件** 例如:用戶登錄和SQL記錄。** @param string $message* @param array $context* @return null*/public function info($message, array $context = array());/*** debug 詳情** @param string $message* @param array $context* @return null*/public function debug($message, array $context = array());/*** 任意等級的日志記錄** @param mixed $level* @param string $message* @param array $context* @return null*/public function log($level, $message, array $context = array()); }4. Psr\Log\LoggerAwareInterface
<?phpnamespace Psr\Log;/*** logger-aware 定義實例*/ interface LoggerAwareInterface {/*** 設置一個日志記錄實例** @param LoggerInterface $logger* @return null*/public function setLogger(LoggerInterface $logger); }5. Psr\Log\LogLevel
<?phpnamespace Psr\Log;/*** 日志等級常量定義*/ class LogLevel {const EMERGENCY = 'emergency';const ALERT = 'alert';const CRITICAL = 'critical';const ERROR = 'error';const WARNING = 'warning';const NOTICE = 'notice';const INFO = 'info';const DEBUG = 'debug'; }PSR-4
自動加載(Autoloader)
本 PSR 是關于由文件路徑 自動載入 對應類的相關規范,
本規范是可互操作的,可以作為任一自動載入規范的補充,
其中包括 PSR-0,此外, 本 PSR 還包括自動載入的類對應的文件存放路徑規范。
- 詳細說明
此處的“類”泛指所有的class類、接口、traits可復用代碼塊以及其它類似結構。
一個完整的類名需具有以下結構:
\<命名空間>(\<子命名空間>)*\<類名>完整的類名必須要有一個頂級命名空間,被稱為 "vendor namespace";
完整的類名可以有一個或多個子命名空間;
完整的類名必須有一個最終的類名;
完整的類名中任意一部分中的下劃線都是沒有特殊含義的;
完整的類名可以由任意大小寫字母組成;
所有類名都必須是大小寫敏感的。
當根據完整的類名載入相應的文件……
完整的類名中,去掉最前面的命名空間分隔符,前面連續的一個或多個命名空間和子命名空間,作為“命名空間前綴”,其必須與至少一個“文件基目錄”相對應;
緊接命名空間前綴后的子命名空間必須與相應的”文件基目錄“相匹配,其中的命名空間分隔符將作為目錄分隔符。
末尾的類名必須與對應的以 .php 為后綴的文件同名。
自動加載器(autoloader)的實現一定不能拋出異常、一定不能觸發任一級別的錯誤信息以及不應該有返回值。
- 例子
下表展示了符合規范完整類名、命名空間前綴和文件基目錄所對應的文件路徑。
| \Acme\Log\Writer\File_Writer | Acme\Log\Writer | ./acme-log-writer/lib/ | ./acme-log-writer/lib/File_Writer.php |
| \Aura\Web\Response\Status | Aura\Web | /path/to/aura-web/src/ | /path/to/aura-web/src/Response/Status.php |
| \Symfony\Core\Request | Symfony\Core | ./vendor/Symfony/Core/ | ./vendor/Symfony/Core/Request.php |
| \Zend\Acl | Zend | /usr/includes/Zend/ | /usr/includes/Zend/Acl.php |
關于本規范的實現,可參閱 相關實例
注意:實例并不屬于規范的一部分,且隨時會有所變動。
轉載于:https://www.cnblogs.com/demonxian3/p/11334005.html
總結
以上是生活随笔為你收集整理的PHP 的一些开发规范的全部內容,希望文章能夠幫你解決所遇到的問題。
- 上一篇: PHP 的一些底层知识
- 下一篇: 星空[好题][题意转化]