本篇(PSR-1)將標準化包含了標準編碼元素的部份，以確保高階技術間之 PHP 程式碼的互通性。

在文件中所使用到的關鍵字 “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, 以及 “OPTIONAL” 皆引用自 RFC 2199 中說明。

譯註：
為了讓語句順暢，這邊就不先針對每個字翻譯；而為了維持原文件中之強調性，所以都會將這幾個關鍵字加粗並在其後接上原字，例如一定 (MUST)。

1.總覽

檔案中一定 (MUST) 只能使用 <?php 以及 <?= 標籤。
PHP 程式的檔案編碼，一定 (MUST) 要用 “無 BOM 之 UTF-8” 格式。
檔案需要 (SHOULD) 在宣告 symbols (classes, functions, constants, 等) 或是採用從屬效應(side-effects) (像是產生輸出，變動 .ini 的設定等) 中擇一處理，不需要 (SHOULD NOT) 二者都做。
命名空間以及類別一定 (MUST) 依循著 PSR-0 建議文件。
類別名稱一定 (MUST) 是採用大寫開始的駝峰大小寫命名法(StudlyCaps) 來宣告。
類別中的宣告常數變數的名稱一定 (MUST) 是由全大寫字母以及底線符號組成。
函式名稱一定 (MUST) 是以小寫開始的駝峰大小寫命名法(camelCase) 宣告。

2.檔案

2.1 PHP 標籤

PHP 程式碼一定要 (MUST) 使用長標籤 <?php ?> 或是短標籤 <?= ?> ；一定不能使用其它標籤。

2.2 字符編碼

PHP程式碼一定要 (MUST) 只使用無 BOM 的 UTF-8 編碼。

2.3 從屬效應

一個檔案中所需要 (SHOULD) 的，要嘛就是只宣告新的 symbols (類別、函式以及常數變數等)；不然就是只採用從屬效應(side effects)，就是不需要(SHOULD NOT)二者都在同一個檔案中。
“從屬效應 (Side effects)” 一詞係指在撰寫程式邏輯時，完全只用到引入檔案中的類別、函式或是常數等，而不再自行宣告。
“從屬效應 (Side effects)” 包含 (但還不僅止於此)：產生輸出、明確地使用 require 或 include 、連接外部的服務、修改 ini 的設定、發出錯誤或例外、更動全域或靜態變數、從檔案讀取或寫入以及諸如此類的動作。

下面這個範例是應該要去避免的情形，一個檔案中包含著宣告以及從屬效應：

<?php
// 從屬效應：改變 ini 的設定
ini_set('error_reporting', E_ALL);

// 從屬效應：載入檔案
include "file.php";

// 從屬效應：產生輸出
echo "<html>\n";

// 宣告
function foo()
{
    // function body
}

<?php

// 從屬效應：改變 ini 的設定

ini_set('error_reporting', E_ALL);

// 從屬效應：載入檔案

include "file.php";

// 從屬效應：產生輸出

echo "<html>\n";

// 宣告

function foo()

{

// function body

}

再來這個例子是示範一個檔案中沒有從屬效應的宣告方式

<?php
// 宣告
function foo()
{
    // function body
}

// 判斷 "非" 從屬效應時才宣告
if (! function_exists('bar')) {
    function bar()
    {
        // function body
    }
}

<?php

// 宣告

function foo()

{

// function body

}

// 判斷 "非" 從屬效應時才宣告

if (! function_exists('bar')) {

function bar()

{

// function body

}

3.命名空間與類別名稱

命名空間以及類別一定要 (MUST) 依循 PSR-0。

這表示每一個類別在該檔案裡，它的命名空間至少要有一層：最上層的提供者名稱(vendor name)。

類別名稱一定要 (MUST) 用大寫開始的駝峰大小寫命名法(StudlyCaps) 。

PHP 5.3 以後的程式碼必需使用正式的命名空間。

舉例來說：

<?php
// PHP 5.3 以後要這麼寫：
namespace Vendor\Model;

class Foo
{
}

<?php

// PHP 5.3 以後要這麼寫：

namespace Vendor\Model;

class Foo

{

}

5.2.x 以前的程式碼，命名類別時需要 (SHOULD) 採用的提供者名稱底線 (Vender_) 方式為開頭的類別名稱之偽命名空間公約。

<?php
// PHP 5.2.x 以前的版本：
class Vendor_Model_Foo
{
}

<?php

// PHP 5.2.x 以前的版本：

class Vendor_Model_Foo

{

}

4.類別裡的常數變數、屬性以及函式

“Class” 一詞包含了所有的類別 (class)、介面 (interfaces)以及特性 (trait)。

譯註：trait 在 PHP 5.4 中泛指所有能被重覆使用的函式。 http://php.net/manual/en/language.oop5.traits.php

4.1 常數變數

類別中所宣告的常數變數名稱一定 (MUST) 要由大寫字母以及底線符號所組成。舉例來說：

<?php
namespace Vendor\Model;

class Foo
{
    const VERSION = '1.0';
    const DATE_APPROVED = '2012-06-01';
}

<?php

namespace Vendor\Model;

class Foo

{

const VERSION = '1.0';

const DATE_APPROVED = '2012-06-01';

}

4.2 屬性

像這類的命名公約應該 (SHOULD) 是要用在一個合理的範圍裡，而這個範圍應該是在：提供者層級 (vendor-level)、封包層級 (package-level)、類別層級 (class-level) 或 method-level (函式層)。

因此，本文件故意不對屬性名稱做像是駝峰式命名 ($StudlyCaps、$camelCase) 或是底線分隔 ($under_score) 這樣的命名建議。

4.3 函式

函式名稱一定 (MUST) 是採用小寫開始的駝峰大小寫命名法(camelCase()) 宣告。

莫希爾(Mosil)手札

PSR-1 Basic Coding Standard

1.總覽

2.檔案

2.1 PHP 標籤

2.2 字符編碼

2.3 從屬效應

3.命名空間與類別名稱

4.類別裡的常數變數、屬性以及函式

4.1 常數變數

4.2 屬性

4.3 函式

6 關於 “PSR-1 Basic Coding Standard” 的評論

發表迴響取消回覆

努力當一個稱職的 NPC

1.總覽

2.檔案

2.1 PHP 標籤

2.2 字符編碼

2.3 從屬效應

3.命名空間與類別名稱

4.類別裡的常數變數、屬性以及函式

4.1 常數變數

4.2 屬性

4.3 函式

分享此文：

6 關於 “PSR-1 Basic Coding Standard” 的評論

發表迴響 取消回覆

努力當一個稱職的 NPC

發表迴響取消回覆