PHP 基本代碼規範 PSR-1

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)包含但不侷限於:產生輸出,顯式地使用requireinclude,連接外部服務,修改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()風格來聲明。

發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章