基本代碼規範
本篇規範制定了代碼基本元素的相關標準, 以確保共享的PHP代碼間具有較高程度的技術互通性。
關鍵詞 “必須”("MUST")、“一定不可/一定不能”("MUST NOT")、“需要”("REQUIRED")、 “將會”("SHALL")、“不會”("SHALL NOT")、“應該”("SHOULD")、“不該”("SHOULD NOT")、 “推薦”("RECOMMENDED")、“可以”("MAY")和”可選“("OPTIONAL")的詳細描述可參見 RFC 2119 。
1. 概覽
PHP代碼文件必須以
<?php
或<?=
標籤開始;PHP代碼文件必須以
不帶BOM的 UTF-8
編碼;PHP代碼中應該只定義類、函數、常量等聲明,或其他會產生
從屬效應
的操作(如:生成文件輸出以及修改.ini配置文件等),二者只能選其一;命名空間以及類必須符合 PSR 的自動加載規範:PSR-4;
類的命名必須遵循
StudlyCaps
大寫開頭的駝峯命名規範;類中的常量所有字母都必須大寫,單詞間用下劃線分隔;
方法名稱必須符合
camelCase
式的小寫開頭駝峯命名規範。
2. 文件
2.1. PHP標籤
PHP代碼必須使用 <?php ?>
長標籤 或 <?= ?>
短輸出標籤; 一定不可使用其它自定義標籤。
2.2. 字符編碼
PHP代碼必須且只可使用不帶BOM的UTF-8
編碼。
2.3. 從屬效應(副作用)
一份PHP文件中應該要不就只定義新的聲明,如類、函數或常量等不產生從屬效應的操作,要不就只有會產生從屬效應的邏輯操作,但不該同時具有兩者。
“從屬效應”(side effects)一詞的意思是,僅僅通過包含文件,不直接聲明類、 函數和常量等,而執行的邏輯操作。
“從屬效應”包含卻不僅限於:生成輸出、直接的 require
或 include
、連接外部服務、修改 ini 配置、拋出錯誤或異常、修改全局或靜態變量、讀或寫文件等。
以下是一個錯誤的例子,一份包含聲明以及產生從屬效應的代碼:
<?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()
{
// 函數主體部分
}
}
3. 命名空間和類
命名空間以及類的命名必須遵循 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
{
}
4. 類的常量、屬性和方法
此處的“類”指代所有的類、接口以及可複用代碼塊(traits)
4.1. 常量
類的常量中所有字母都必須大寫,詞間以下劃線分隔。 參照以下代碼:
<?php
namespace Vendor\Model;
class Foo
{
const VERSION = '1.0';
const DATE_APPROVED = '2012-06-01';
}
4.2. 屬性
類的屬性命名可以遵循 大寫開頭的駝峯式 ($StudlyCaps
)、小寫開頭的駝峯式 ($camelCase
) 又或者是 下劃線分隔式 ($under_score
),本規範不做強制要求,但無論遵循哪種命名方式,都應該在一定的範圍內保持一致。這個範圍可以是整個團隊、整個包、整個類或整個方法。
4.3. 方法
方法名稱必須符合 camelCase()
式的小寫開頭駝峯命名規範。