PHP PSR基本代碼規範(中文版)
PSR-1
基本代碼規範
本篇規範制定了代碼基本元素的相關標準,
以確保共享的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-0 或 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-0.
根據規範,每個類都獨立為一個文件,且命名空間至少有一個層次:頂級的組織名稱(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()
式的小寫開頭駝峰命名規範。
PSR-2
代碼風格規範
本篇規範是 PSR-1 基本代碼規範的繼承與擴展。
本規範希望通過制定一系列規範化PHP代碼的規則,以減少在瀏覽不同作者的代碼時,因代碼風格的不同而造成不便。
當多名程序員在多個項目中合作時,就需要一個共同的編碼規範,
而本文中的風格規範源自於多個不同項目代碼風格的共同特性,
因此,本規範的價值在於我們都遵循這個編碼風格,而不是在於它本身。
關鍵詞 “必須”("MUST")、“一定不可/一定不能”("MUST NOT")、“需要”("REQUIRED")、
“將會”("SHALL")、“不會”("SHALL NOT")、“應該”("SHOULD")、“不該”("SHOULD NOT")、
“推薦”("RECOMMENDED")、“可以”("MAY")和”可選“("OPTIONAL")的詳細描述可參見 [RFC 2119][] 。
1. 概覽
-
代碼必須遵循 PSR-1 中的編碼規範 。
-
代碼必須使用4個空格符而不是 tab鍵 進行縮進。
-
每行的字符數應該軟性保持在80個之內, 理論上一定不可多於120個, 但一定不能有硬性限制。
-
每個
namespace
命名空間聲明語句和use
聲明語句塊後面,必須插入一個空白行。 -
類的開始花括號(
{
)必須寫在函數聲明後自成一行,結束花括號(}
)也必須寫在函數主體後自成一行。 -
方法的開始花括號(
{
)必須寫在函數聲明後自成一行,結束花括號(}
)也必須寫在函數主體後自成一行。 -
類的屬性和方法必須添加訪問修飾符(
private
、protected
以及public
),abstract
以及final
必須聲明在訪問修飾符之前,而static
必須聲明在訪問修飾符之後。 -
控制結構的關鍵字後必須要有一個空格符,而調用方法或函數時則一定不能有。
-
控制結構的開始花括號(
{
)必須寫在聲明的同一行,而結束花括號(}
)必須寫在主體後自成一行。 -
控制結構的開始左括號後和結束右括號前,都一定不能有空格符。
1.1. 例子
以下例子程序簡單地展示了以上大部分規範:
update: 因下面程序的<?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
}
}
2. 通則
2.1 基本編碼準則
代碼必須符合 PSR-1 中的所有規範。
2.2 文件
所有PHP文件必須使用Unix LF (linefeed)
作為行的結束符。
所有PHP文件必須以一個空白行作為結束。
純PHP代碼文件必須省略最後的 ?>
結束標簽。
2.3. 行
行的長度一定不能有硬性的約束。
軟性的長度約束一定要限制在120個字符以內,若超過此長度,帶代碼規範檢查的編輯器一定要發出警告,不過一定不可發出錯誤提示。
每行不應該多於80個字符,大於80字符的行應該折成多行。
非空行後一定不能有多余的空格符。
空行可以使得閱讀代碼更加方便以及有助於代碼的分塊。
每行一定不能存在多於一條語句。
2.4. 縮進
代碼必須使用4個空格符的縮進,一定不能用 tab鍵 。
備註: 使用空格而不是tab鍵縮進的好處在於,
避免在比較代碼差異、打補丁、重閱代碼以及註釋時產生混淆。
並且,使用空格縮進,讓對齊變得更方便。
2.5. 關鍵字 以及 True/False/Null
PHP所有 關鍵字必須全部小寫。
常量 true
、false
和 null
也必須全部小寫。
3. 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 ...
4. 類、屬性和方法
此處的“類”泛指所有的class類、接口以及traits可復用代碼塊。
4.1. 擴展與繼承
關鍵詞 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
}
4.2. 屬性
每個屬性都必須添加訪問修飾符。
一定不可使用關鍵字 var
聲明一個屬性。
每條語句一定不可定義超過一個屬性。
不要使用下劃線作為前綴,來區分屬性是 protected 或 private。
以下是屬性聲明的一個範例:
<?php
namespace Vendor\Package;
class ClassName
{
public $foo = null;
}
4.3. 方法
所有方法都必須添加訪問修飾符。
不要使用下劃線作為前綴,來區分方法是 protected 或 private。
方法名稱後一定不能有空格符,其開始花括號必須獨占一行,結束花括號也必須在方法主體後單獨成一行。參數左括號後和右括號前一定不能有空格。
一個標準的方法聲明可參照以下範例,留意其括號、逗號、空格以及花括號的位置。
<?php
namespace Vendor\Package;
class ClassName
{
public function fooBarBaz($arg1, &$arg2, $arg3 = [])
{
// method body
}
}
4.4. 方法的參數
參數列表中,每個參數後面必須要有一個空格,而前面一定不能有空格。
有默認值的參數,必須放到參數列表的末尾。
<?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
}
}
4.5. 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
bar();
$foo->bar($arg1);
Foo::bar($arg2, $arg3);
參數可以分列成多行,此時包括第一個參數在內的每個參數都必須單獨成行。
<?php
$foo->bar(
$longArgument,
$longerArgument,
$muchLongerArgument
);
5. 控制結構
控制結構的基本規範如下:
- 控制結構關鍵詞後必須有一個空格。
- 左括號
(
後一定不能有空格。 - 右括號
)
前也一定不能有空格。 - 右括號
)
與開始花括號{
間一定有一個空格。 - 結構體主體一定要有一次縮進。
- 結束花括號
}
一定在結構體主體後單獨成行。
每個結構體的主體都必須被包含在成對的花括號之中,
這能讓結構體更加結構話,以及減少加入新行時,出錯的可能性。
5.1. if
、 elseif
和 else
標準的 if
結構如下代碼所示,留意 括號、空格以及花括號的位置,
註意 else
和 elseif
都與前面的結束花括號在同一行。
<?php
if ($expr1) {
// if body
} elseif ($expr2) {
// elseif body
} else {
// else body;
}
應該使用關鍵詞 elseif
代替所有 else if
,以使得所有的控制關鍵字都像是單獨的一個詞。
5.2. 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 break
case 2:
case 3:
case 4:
echo ‘Third case, return instead of break‘;
return;
default:
echo ‘Default case‘;
break;
}
5.3. while
和 do while
一個規範的 while
語句應該如下所示,註意其 括號、空格以及花括號的位置。
<?php
while ($expr) {
// structure body
}
標準的 do while
語句如下所示,同樣的,註意其 括號、空格以及花括號的位置。
<?php
do {
// structure body;
} while ($expr);
5.4. for
標準的 for
語句如下所示,註意其 括號、空格以及花括號的位置。
<?php
for ($i = 0; $i < 10; $i++) {
// for body
}
5.5. foreach
標準的 foreach
語句如下所示,註意其 括號、空格以及花括號的位置。
<?php
foreach ($iterable as $key => $value) {
// foreach body
}
5.6. try
, catch
標準的 try catch
語句如下所示,註意其 括號、空格以及花括號的位置。
<?php
try {
// try body
} catch (FirstExceptionType $e) {
// catch body
} catch (OtherExceptionType $e) {
// catch body
}
6. 閉包
閉包聲明時,關鍵詞 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
);
7. 總結
以上規範難免有疏忽,其中包括但不僅限於:
-
全局變量和常量的定義
-
函數的定義
-
操作符和賦值
-
行內對齊
-
註釋和文檔描述塊
-
類名的前綴及後綴
-
最佳實踐
PSR-3
日誌接口規範
本文制定了日誌類庫的通用接口規範。
本規範的主要目的,是為了讓日誌類庫以簡單通用的方式,通過接收一個 Psr\Log\LoggerInterface
對象,來記錄日誌信息。
框架以及CMS內容管理系統如有需要,可以對此接口進行擴展,但需遵循本規範,
這才能保證在使用第三方的類庫文件時,日誌接口仍能正常對接。
關鍵詞 “必須”("MUST")、“一定不可/一定不能”("MUST NOT")、“需要”("REQUIRED")、
“將會”("SHALL")、“不會”("SHALL NOT")、“應該”("SHOULD")、“不該”("SHOULD NOT")、
“推薦”("RECOMMENDED")、“可以”("MAY")和”可選“("OPTIONAL")的詳細描述可參見 RFC 2119 。
本文中的 實現者
指的是實現了 LoggerInterface
接口的類庫或者框架,反過來講,他們就是 LoggerInterface
的 使用者
。
1. 規範說明
1.1 基本規範
-
LoggerInterface
接口對外定義了八個方法,分別用來記錄 RFC 5424 中定義的八個等級的日誌:debug、 info、 notice、 warning、 error、 critical、 alert 以及 emergency 。 -
第九個方法 ——
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
<?php
namespace 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
<?php
namespace Psr\Log;
/**
* logger-aware 定義實例
*/
interface LoggerAwareInterface
{
/**
* 設置一個日誌記錄實例
*
* @param LoggerInterface $logger
* @return null
*/
public function setLogger(LoggerInterface $logger);
}
5. Psr\Log\LogLevel
<?php
namespace 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
關鍵詞 “必須”("MUST")、“一定不可/一定不能”("MUST NOT")、“需要”("REQUIRED")、
“將會”("SHALL")、“不會”("SHALL NOT")、“應該”("SHOULD")、“不該”("SHOULD NOT")、
“推薦”("RECOMMENDED")、“可以”("MAY")和”可選“("OPTIONAL")的詳細描述可參見 [RFC 2119][] 。
1. 概述
本 PSR 是關於由文件路徑 自動載入 對應類的相關規範,
本規範是可互操作的,可以作為任一自動載入規範的補充,其中包括 PSR-0,此外,
本 PSR 還包括自動載入的類對應的文件存放路徑規範。
2. 詳細說明
-
此處的“類”泛指所有的class類、接口、traits可復用代碼塊以及其它類似結構。
-
一個完整的類名需具有以下結構:
\<命名空間>(\<子命名空間>)*\<類名>
-
完整的類名必須要有一個頂級命名空間,被稱為 "vendor namespace";
-
完整的類名可以有一個或多個子命名空間;
-
完整的類名必須有一個最終的類名;
-
完整的類名中任意一部分中的下滑線都是沒有特殊含義的;
-
完整的類名可以由任意大小寫字母組成;
-
所有類名都必須是大小寫敏感的。
-
-
當根據完整的類名載入相應的文件……
-
完整的類名中,去掉最前面的命名空間分隔符,前面連續的一個或多個命名空間和子命名空間,作為“命名空間前綴”,其必須與至少一個“文件基目錄”相對應;
-
緊接命名空間前綴後的子命名空間必須與相應的”文件基目錄“相匹配,其中的命名空間分隔符將作為目錄分隔符。
-
末尾的類名必須與對應的以
.php
為後綴的文件同名。 -
自動加載器(autoloader)的實現一定不能拋出異常、一定不能觸發任一級別的錯誤信息以及不應該有返回值。
-
3. 例子
下表展示了符合規範完整類名、命名空間前綴和文件基目錄所對應的文件路徑。
完整類名 | 命名空間前綴 | 文件基目錄 | 文件路徑 |
---|---|---|---|
\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 |
關於本規範的實現,可參閱 相關實例
註意:實例並不屬於規範的一部分,且隨時會有所變動。
PHP PSR基本代碼規範(中文版)