PHP PSR-1 基本程式碼規範(中文版)

weixin_33901926發表於2017-01-18
PHP

基本程式碼規範

本篇規範制定了程式碼基本元素的相關標準，
以確保共享的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() 式的小寫開頭駝峰命名規範。

相關文章