PSR-1: 基礎編碼規範

時間 2019-12-07

原文原文鏈接

翻譯：薛粲
受權許可：CC BY-NC 4.0php

這份文檔是《PSR-1: Basic Coding Standard》的非官方譯文。html

這份標準文檔闡述了那些須要考慮的標準的編寫代碼的原則，用於確保在共享 PHP 代碼時技術上具有較高層次的互操做性。函數

英文原文使用的關鍵詞 "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 以及 "OPTIONAL" 遵循 RFC 2119 的描述。譯文中根據上下文可能會使用不一樣的詞彙來對應這些關鍵詞，並加粗顯示。ui

1. 概述

文件必須只用 <?php 或 <?= 標記。編碼
PHP 源代碼文件必須只用不帶 BOM 的 UTF-8 編碼。spa
一個文件應該或者用於聲明各類符號（類、函數、常量等），或者發生做用（例如產生輸出、修改 .ini 設置等）但不該該同時作上述兩件事情。翻譯
命名空間和類必須遵循一條關於自動加載的 PSR，即 PSR-0 或 PSR-4。code
類名必須聲明爲 StudlyCaps 樣式。htm
類常量必須所有使用大寫字母和下劃線進行聲明。接口
方法名必須聲明爲 camelCase 樣式。.

2. 文件

2.1 PHP 標記

PHP 代碼必須使用長的 <?php ?> 標記或者短的用於輸出的 <?= ?> 標記；不得使用其它種類的標記。

2.2 字符編碼

PHP 源代碼必須使用不帶 BOM 的 UTF-8 編碼。

2.3 反作用

一個文件應該是：或者用於聲明新的符號（類、函數、常量等）的，同時並不致使其它反作用；或者用於執行一些會產生反作用的邏輯。可是，一個文件不該該既聲明新的符號，又執行產生反作用的邏輯。

短語「反作用」在這裏指的是執行那些不直接與聲明類、函數、常量等相關的邏輯，merely from including the file.

「反作用」包括但不限於：產生輸出、明確的使用 require 或 include，鏈接外部服務、修改 ini 設置、拋出錯誤或異常、修改全局或靜態變量以及讀寫文件等。

下面的示例既包含了聲明又執行了產生反作用的邏輯，換句話說，這裏例子是應該避免的：

<?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
    }
}

3. 命名空間和類名

命名空間和類必須遵循一份自動加載 PSR 規範：PSR-0 或 PSR-4。

這意味着每一個類在一個只屬於它本身的文件中，而且至少在一層命名空間——即最頂層的提供商名——之中。

類名必須聲明爲 StudlyCaps 的形式。

面向 PHP 5.3 或更高版本的代碼必須使用正式的命名空間。

例如：

<?php
// PHP 5.3 或更高版本：
namespace Vendor\Model;

class Foo
{
}

面向 PHP 5.2 或更早版本的代碼應該使用以 Vendor_ 開始的僞命名空間的慣例：

<?php
// PHP 5.2.x 或更早的版本：
class Vendor_Model_Foo
{
}

4. 類常量、屬性和方法

術語「類」在這裏涵蓋了類、接口和 trait。

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() 風格的命名。

相關標籤/搜索

每日一句

每一个你不满意的现在，都有一个你没有努力的曾经。