PSR-1: 基本代码规范

原文: https://www.php-fig.org/psr/psr-1/

本节我们将会讨论一些基本的代码规范问题,以此作为将来讨论更高级别的代码分享和技术互用的基础。

RFC 2119中的必须(MUST)、不能(MUST NOT)、应当(SHOULD)、不应(SHOULD NOT)、可以(MAY)等术语将在本节用来做一些解释性的描述。

1. 概述

  • 源文件必须只使用 <?php<?= 这两种标签。
  • 源文件中PHP代码的编码格式必须只使用不带字节顺序标记(BOM)的UTF-8。
  • 一个源文件应当只用来做声明(类、函数、常量等)或者只用来做一些引起副作用的操作(如输出信息、修改.ini配置等),但不应同时做这两件事。
  • 命名空间和类必须遵守关于自动加载的PSR标准:[PSR-0, PSR-4]。
  • 类名必须使用StulyCaps写法。
  • 类中的常量必须只由大写字母和下划线组成。
  • 方法名必须使用camelCase写法。

2. 文件

2.1. PHP标签

PHP代码必须只使用长标签<?php ?>或者短输出式标签<?= ?>,而不能使用其他标签。

2.2. 字符编码

PHP代码的编码格式必须只使用不带字节顺序标记(BOM)的UTF-8。

2.3. 副作用

一个源文件应当只用来做声明(类、函数、常量等)或者只用来做一些引起副作用的操作(如输出信息、修改.ini配置等),但不应同时做这两件事。

短语“副作用”的意思是在包含文件时所执行的逻辑与所声明的类、函数、常量等没有直接的关系。

“副作用”包括但不限于:产生输出,显式地使用requireinclude,连接外部服务,修改ini配置,触发错误或异常,修改全局或者静态变量,读取或修改文件等等。

下面是一个既包含声明又有副作用的示例文件;即应避免的例子:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<?php
// 副作用:修改了ini配置
ini_set('error_reporting', E_ALL);

// 副作用:载入了文件
include "file.php";

// 副作用:产生了输出
echo "<html>\n";

// 声明
function foo()
{
// 函数体
}

下面是一个仅包含声明的示例文件;即应提倡的例子:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<?php
// 声明
function foo()
{
// 函数体
}

// 条件式声明*不*算做是副作用
if (! function_exists('bar')) {
function bar()
{
// 函数体
}
}

3. 命名空间和类名

命名空间和类必须遵守关于自动加载的PSR标准:[PSR-0, PSR-4]。

这意味着一个源文件中只能有一个类,并且每个类至少要有一级空间名,即一个顶级的组织名。

类名必须使用StulyCaps写法。

PHP5.3之后的代码必须使用正式的命名空间。

例如:

1
2
3
4
5
6
7
<?php
// PHP 5.3 及之后:
namespace Vendor\Model;

class Foo
{
}

PHP5.2.x和之前的代码应当用伪命名空间Vendor_作为类名的前缀:

1
2
3
4
5
<?php
// PHP 5.2.x 及之前:
class Vendor_Model_Foo
{
}

4. 类的常量、属性和方法

术语“类”指所有的类、接口和特性。

4.1. 常量

类常量必须只由大写字母和下划线组成。

例如:

1
2
3
4
5
6
7
8
<?php
namespace Vendor\Model;

class Foo
{
const VERSION = '1.0';
const DATE_APPROVED = '2012-06-01';
}

4.2. 属性

本指南中故意不对$StulyCaps$camelCase$unser_score中的某一种风格作特别推荐,完全由读者依据个人喜好决定属性名的命名风格。

但是不管你如何定义属性名,应当在一个合理的范围内保持一致。这个范围可能是组织级别的、包级别的、类级别的或者方法级别的。

4.3. 方法

方法名则必须使用camelCase()风格来声明。