PHP FIG - PSR-1 基本代码规范（Basic Coding Standard）

译自 http://www.php-fig.org/psr/psr-1/

这个章节讨论的是必须确保共享 PHP 代码之间的最高共通性，以及技术互操作的高水平的标准编码要素。

1. 概况 #

源文件中必须而且只能使用 <?php 和 <?= 标签；
源文件必须而且只能使用 UTF-8 without BOM 字符编码来编写 PHP 代码；
源文件中的代码应当只能有下述操作中的一种，但不应同时并存：
1. 声明符号（classes, functions, constants, etc.），
2. 引起副作用（ side-effects）（例如，产生输出，或者改变 .ini 设置，etc）;
命名空间（NameSpaces）和类（Classes）必须遵循 PSR-0 ；
类（Class）名必须使用 首字母大写的驼峰（StudlyCaps） 命名法则；
类常量（Class constants）必须使用 全大写以下划线隔开 的命名法则；
方法（Method）名称必须使用 驼峰（camelCase） 的命名法则；

2. 文件 #

2.1. PHP 标签（Tag） #

PHP 代码必须使用 <?php ?> 长标签或者 <?= ?> 短输出标签；但他们不应包含在对方的标签中。

2.2. 字符类型（Character Encoding） #

PHP 代码必须只能使用 UTF-8 without BOM 字符类型。

2.3. 副作用（Side Effects） #

源文件中的代码应当只能声明符号（classes, functions, constants, etc.），但不产生任何副作用；或只能进行引起副作用的逻辑操作；但不应同时并存：

”Side effects“ 的语义指的是逻辑的执行，但不直接关联声明的类，方法和常量等等，仅是包含文件而已。

“Side effects” 可以包含如下：产生输出，明确 require 和 include 的使用，连接外部的服务，改变 ini 配置，输出错误或异常，改变全局或静态变量，读写文件等等；

下面是一个同时声明和副作用的例子（是我们应该避免的）：

<?php
// side effect: 改变 ini 设置
ini_set('errror_reporting', E_ALL);

// side effect: 载入文件
include "file.php";

// side effect: 产生输出
echo "<html>\n";

// 声明
function foo()
{
    // function body
}

接下来的例子是只包含声明但没有副作用的（是我们提倡的，要遵守的）：

<?php
// 声明
function foo()
{
    // function body
}

// 条件声明不属于 side effect
if (! funciton_exists('bar')) {
    function bar()
    {
        // funciton body
    }
}

3. 命名空间（NameSpace）和类名（Class） #

命名空间和类必须遵守 PSR-0 。

这意味着一个文件只能包含一个类，而且要在一个至少一级的命名空间下：顶级的 vendor 名。

类名必须使用 首字母大写的驼峰命名形式（StudlyCaps） 。

代码必须支持 PHP 5.3 或者更高的版本，因为 5.3 之后才能支持正式的命名空间。

例如：

<?php
// PHP 5.3 and later:
namespace Vendor\Model;

class Foo
{
}

PHP 5.2.x 之前应当使用 伪命名空间原则（Vender 名加下划线在类名之前） ：

<?php
// PHP 5.2.x and earlier:
class Vendor_Model_Foo
{
}

4. 类常量（Class Constants）,属性（Properties）和方法（Methods） #

这里的类指的是类，接口和 Traits 的统称。

4.1. 常量（Constants） #

类常量（Class constants）必须使用 全大写以下划线隔开 的命名法则；例如：

<?php
namespace Vendor\Model;

class Foo
{
    const Version    ＝ '1.0';
    const DATE_APPROVED = '2013-06-01';
}

4.2. 属性（Properties） #

这个指南有意对属性的各种命名建议不做任何推荐，如 首字母大写的驼峰（$StudlyCaps） ， 驼峰（$camelCase） 和 下划线命名（$under_score） 。

无论你使用哪一个原则，你都应当在合理的代码范围内保持一致性。这个范围可以是 vender 级别的，包级别的，类级别，还可以是方法级别的。

4.3. 方法（Methods） #

方法名必须使用 驼峰的形式（camelCase()） 。