PHP 基本代碼規範 PSR-1
本節我們將會討論一些基本的代碼規範問題,以此作爲將來討論更高級別的代碼分享和技術互用的基礎。
RFC 2119中的必須(MUST)
,不可(MUST NOT)
,建議(SHOULD)
,不建議(SHOULD NOT)
,可以/可能(MAY)
等關鍵詞將在本節用來做一些解釋性的描述。
1. 概述
源文件
必須
只使用<?php
和<?=
這兩種標籤。源文件中php代碼的編碼格式
必須
只使用不帶字節順序標記(BOM)
的UTF-8
。一個源文件
建議
只用來做聲明(類(class)
,函數(function)
,常量(constant)
等)或者只用來做一些引起副作用的操作(例如:輸出信息,修改.ini
配置等),但不建議
同時做這兩件事。命名空間(namespace)
和類(class)
必須
遵守PSR-0標準。類名(class name)
必須
使用駱駝式(StudlyCaps)
寫法 (譯者注:駝峯式(cameCase)
的一種變種,後文將直接用StudlyCaps
表示)。類(class)
中的常量必須
只由大寫字母和下劃線(_)
組成。方法名(method name)
必須
使用駝峯式(cameCase)
寫法(譯者注:後文將直接用camelCase
表示)。
2. 文件
2.1. PHP標籤
PHP代碼必須
只使用長標籤(<?php ?>)
或者短輸出式標籤(<?= ?>)
;而不可
使用其他標籤。
2.2. 字符編碼
PHP代碼的編碼格式必須
只使用不帶字節順序標記(BOM)
的UTF-8
。
2.3. 副作用
一個源文件建議
只用來做聲明(類(class)
,函數(function)
,常量(constant)
等)或者只用來做一些引起副作用的操作(例如:輸出信息,修改.ini
配置等),但不建議
同時做這兩件事。
短語副作用(side effects)
的意思是 在包含文件時 所執行的邏輯與所聲明的類(class)
,函數(function)
,常量(constant)
等沒有直接的關係。
副作用(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. 空間名(namespace)
和類名(class name)
命名空間(namespace)
和類(class)
必須遵守 PSR-0.
這意味着一個源文件中只能有一個類(class)
,並且每個類(class)
至少要有一級空間名(namespace)
:即一個頂級的組織名(vendor name)
。
類名(class name)
必須
使用StudlyCaps
寫法。
PHP5.3
之後的代碼必須
使用正式的命名空間(namespace)
例子:
<?php
// PHP 5.3 及之後:
namespace Vendor\Model;
class Foo
{
}
PHP5.2.x
之前的代碼建議
用僞命名空間Vendor_
作爲類名(class name)
的前綴
<?php
// PHP 5.2.x 及之前:
class Vendor_Model_Foo
{
}
4. 類的常量、屬性和方法
術語類(class)
指所有的類(class)
,接口(interface)
和特性(trait)
4.1. 常量
類常量必須
只由大寫字母和下劃線(_)
組成。
例子:
<?php
namespace Vendor\Model;
class Foo
{
const VERSION = '1.0';
const DATE_APPROVED = '2012-06-01';
}
4.2. 屬性
本指南中故意不對$StulyCaps
,$camelCase
或者$unser_score
中的某一種風格作特別推薦,完全由讀者依據個人喜好決定屬性名的命名風格。
但是不管你如何定義屬性名,建議
在一個合理的範圍內保持一致。這個範圍可能是組織(vendor)
級別的,包(package)
級別的,類(class)
級別的,或者方法(method)
級別的。
4.3. 方法
方法名則必須
使用camelCase()
風格來聲明。