PSR-1 基礎編碼規範

時間 2019-11-20

原文原文鏈接

本篇規範制定了代碼基本元素的相關標準，以確保共享的PHP代碼間具備較高程度的技術互通性。php

關鍵詞「必須」("MUST")、「必定不可/必定不能」("MUST NOT")、「須要」("REQUIRED")、「將會」("SHALL")、「不會」("SHALL NOT")、「應該」("SHOULD")、「不應」("SHOULD NOT")、「推薦」("RECOMMENDED")、「能夠」("MAY")和」可選「("OPTIONAL")的詳細描述可參見 RFC 2119 。html

概覽

PHP代碼文件必須以 <?php 或 <?= 標籤開始；git
PHP代碼文件必須以 不帶BOM的 UTF-8 編碼；github
PHP代碼中應該只定義類、函數、常量等聲明，或其餘會產生 從屬效應 的操做（如：生成文件輸出以及修改.ini配置文件等），兩者只能選其一；ide
命名空間以及類必須符合 PSR 的自動加載規範：PSR-4；函數
類的命名必須遵循 StudlyCaps 大寫開頭的駝峯命名規範；ui
類中的常量全部字母都必須大寫，單詞間用下劃線分隔；編碼
方法名稱必須符合 camelCase 式的小寫開頭駝峯命名規範。spa

文件

2.1. PHP標籤

PHP代碼必須使用 <?php ?> 長標籤或 <?= ?> 短輸出標籤；必定不可以使用其它自定義標籤。code

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() { // 函數主體部分
 } } 
 

命名空間和類

命名空間以及類的命名必須遵循 PSR-4。

根據規範，每一個類都獨立爲一個文件，且命名空間至少有一個層次：頂級的組織名稱（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 { }

類的常量、屬性和方法

此處的「類」指代全部的類、接口以及可複用代碼塊（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)，本規範不作強制要求，但不管遵循哪一種命名方式，都應該在必定的範圍內保持一致。這個範圍能夠是整個團隊、整個包、整個類或整個方法。