PSR-1: 基础编码规范 - 快车库

这份文档是《PSR-1: Basic Coding Standard》的非官方译文。

这份标准文档阐述了那些需要考虑的标准的编写代码的原则，用于确保在共享 PHP 代码时技术上具备较高层次的互操作性。

英文原文使用的关键词 "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 以及 "OPTIONAL" 遵循 RFC 2119 的描述。译文中根据上下文可能会使用不同的词汇来对应这些关键词，并加粗显示。

1. 概述

文件必须只用 <?php 或 <?= 标记。
PHP 源代码文件必须只用不带 BOM 的 UTF-8 编码。
一个文件应该或者用于声明各种符号（类、函数、常量等），或者发生作用（例如产生输出、修改 .ini 设置等）但不应该同时做上述两件事情。
命名空间和类必须遵循一条关于自动加载的 PSR，即 PSR-0 或 PSR-4。
类名必须声明为 StudlyCaps 样式。
类常量必须全部使用大写字母和下划线进行声明。
方法名必须声明为 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() 风格的命名。