1.编码规范
- PHP 代码文件 必须 以
<?php
或<?=
标签开始; - PHP 代码文件 必须 以
不带 BOM 的 UTF-8
编码; - PHP 代码中 应该 只定义类、函数、常量等声明, 或其他会产生
副作用
的操作(如:生成文件输出以及修改 .ini 配置文件等),二者只能选其一; - 命名空间以及类 必须 符合 PSR 的自动加载规范: [PSR-0(已废弃)或 PSR-4] 中的一个。
- 类的命名 必须 遵循
StudlyCaps
大写开头的驼峰命名规范; - 类中的常量所有字母都 必须 大写,单词间用下划线分隔;
- 方法名称 必须 符合
camelCase
式的小写开头驼峰命名规范。 - 单一文件只能申明单个类
1.类的常量、属性和方法
此处的「类」指代所有的类、接口以及可复用代码块(traits)。
1.1常量
类的常量中所有字母都 必须 大写,词间以下划线分隔。例如:
<?php
namespace Vendor\Model;
class Foo
{
const VERSION = '1.0';
const DATE_APPROVED = '2012-06-01';
}
1.2.属性
- 类的属性命名 可以 遵循:
- 大写开头的驼峰式 (
$StudlyCaps
) - 小写开头的驼峰式 (
$camelCase
) - 下划线分隔式 (
$under_score
)
- 大写开头的驼峰式 (
- 本规范不做强制要求,但无论遵循哪种命名方式,都 应该 在一定的范围内保持一致。这个范围可以是整个团队、整个包、整个类或整个方法。
1.3.方法
- 方法名称 必须 符合
camelCase()
式的小写开头驼峰命名规范。
1.4.注释
所有的类都 必须 添加大概说明、创建者、创建日期 切放在
namespace
申明前 并空一行。例:<?php /** * 类说明 * * User: pota * DateTime: 2018/11/15 5:37 PM */ namespace Example;
方法注释 必须 采用
doc
风格注释。例:/** * 方法说明 * * @param int $param 参数说明 * @throw \Exception 若有异常抛出 需申明抛出异常类型 * @return bool true 成功 false 失败 //强制必须申明所返回参数类型 若有必要需说明返回参数说明(非强制) */ public function action(int $param): bool { //类主体 }
类属性和参数需说明参数类型以及参数说明。例:
/** * 参数说明 * * @var array */ public $param = array();
方法内部单行注释,在被注释语句上方另起一行,使用
//<...>
注释。方法内部多行注释 使用/* <...> */
注释,注意与代码对齐。代码修改的同时,注释也要进行相应的修改,尤其是参数、返回值、异常、核心逻 辑等的修改。
注释类型申明可以使用以下类型
bool
:此类型适用的元素仅具有状态TRUE
或FALSE
。int
:此类型适用的元素是整数或整数。float
:此类型适用的元素是连续或实数。string
:此类型适用的元素是二进制字符串。object
:此类型适用的元素是未确定类的实例。array
:此类型适用的元素是值数组。iterable
:此类型适用的元素是每个PHP定义的数组或Traversable对象。resource
:此类型适用的元素是每个PHP定义的资源。mixed
:此类型适用的元素可以是此处指定的任何类型。在编译时不知道将使用哪种类型。void
:此类型通常仅在定义方法或函数的返回类型时使用,指示“未返回任何内容”,因此用户不应依赖任何返回的值。
2.文件
2.1. PHP 标签
- PHP 代码 必须 使用
<?php ?>
长标签 或<?= ?>
短输出标签;一定不可 使用其它自定义标签。
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() { // function body }
下面是一个范例,一份只包含声明不产生「副作用」的代码:
<?php // 声明函数 function foo() { // 函数主体部分 } // 条件声明 **不** 属于「副作用」 if (! function_exists('bar')) { function bar() { // 函数主体部分 } }
2.编码风格
1.概览
- 代码 必须 遵循 [PSR-1] 中的编码规范 。
- 代码 必须 使用 4 个空格符而不是「Tab 键」进行缩进。
- 每行的字符数 应该 软性保持在 80 个之内,理论上 一定不可 多于 120 个,但 一定不可 有硬性限制。
- 每个
namespace
命名空间声明语句和use
声明语句块后面,必须 插入一个空白行。 - 类的开始花括号(
{
) 必须 写在函数声明后自成一行,结束花括号(}
)也 必须 写在函数主体后自成一行。 - 方法的开始花括号(
{
) 必须 写在函数声明后自成一行,结束花括号(}
)也 必须 写在函数主体后自成一行。 - 类的属性和方法 必须 添加访问修饰符(
private
、protected
以及public
),abstract
以及final
必须 声明在访问修饰符之前,而static
必须 声明在访问修饰符之后。 - 控制结构的关键字后 必须 要有一个空格符,而调用方法或函数时则 一定不可 有。
- 控制结构的开始花括号(
{
) 必须 写在声明的同一行,而结束花括号(}
) 必须 写在主体后自成一行。 - 控制结构的开始左括号后和结束右括号前,都 一定不可 有空格符。
- 控制结构必须使用花括号(
{}
)
1.1.示例
本示例将作为下文规则的快速概览:
<?php
namespace Vendor\Package;
use FooInterface;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;
class Foo extends Bar implements FooInterface
{
public function sampleMethod($a, $b = null)
{
if ($a === $b) {
bar();
} elseif ($a > $b) {
$foo->bar($arg1);
} else {
BazClass::bar($arg2, $arg3);
}
}
final public static function bar()
{
// 方法体
}
}
2. 通则
2.1. 基本编码准则
- 代码 必须 符合 PSR-1 中的所有规范。
2.2. 文件
所有 PHP 文件 必须 使用
Unix LF (linefeed)
作为行的结束符。所有 PHP 文件 必须 以一个空白行作为结束。
纯 PHP 代码文件 必须 省略最后的
?>
结束标签。
2.3. 行
行的长度 一定不可 有硬性的约束。
每行 不该 多于 80 个字符,大于 80 字符的行 应该 折成多行。
非空行后 一定不可 有多余的空格符。
空行 可以 使得阅读代码更加方便以及有助于代码的分块。
每行 一定不可 存在多于一条语句。
2.4. 缩进
- 代码 必须 使用 4 个空格来进行缩进, 并且 一定不能 使用
tab
键来缩进。
注:仅使用空格,而不是使用空格和
tab
键混在一起, 能帮助避免在查看代码差异,打补丁,查看提交历史,以及进行注解时产生问题。使用空格也使得代码对齐更轻松。
2.5. 关键字与 True/False/Null
PHP 的 关键字 必须 使用小写形式。
PHP 的常量
true
,false
, 还有null
必须 使用小写形式。
3. 命名空间和使用声明
namespace
声明之后 必须 存在一个空行。所有的
use
声明 必须 位于namespace
声明之后。每条
use
声明 必须 只有一个use
关键字。use
语句块之后 必须 存在一个空行。例如:
<?php
namespace Vendor\Package;
use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;
// ... 其他 PHP 代码 ...
4. 类、属性和方法
此处的「类」泛指所有的「class 类」、「接口」以及「traits 可复用代码块」。
4.1. 扩展与继承
- 关键词
extends
和implements
必须 写在类名称的同一行。 - 类的开始花括号 必须 独占一行,结束花括号也 必须 在类主体后独占一行。
<?php
namespace Vendor\Package;
use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;
class ClassName extends ParentClass implements \ArrayAccess, \Countable
{
// 这里面是常量、属性、类方法
}
implements
的继承列表也 可以 分成多行,这样的话,每个继承接口名称都 必须 分开独立成行,包括第一个。
<?php
namespace Vendor\Package;
use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;
class ClassName extends ParentClass implements
\ArrayAccess,
\Countable,
\Serializable
{
// 这里面是常量、属性、类方法
}
4.2. 属性
每个属性都 必须 添加访问修饰符。
一定不可 使用关键字
var
声明一个属性。每条语句 一定不可 定义超过一个属性。
不该 使用下划线作为前缀,来区分属性是 protected 或 private。
以下是属性声明的一个范例:
<?php
namespace Vendor\Package;
class ClassName
{
public $foo = null;
}
4.3. 方法
所有方法都 必须 添加访问修饰符。
不该 使用下划线作为前缀,来区分方法是 protected 或 private 访问修饰符。
方法名称后 一定不可 有空格符,其开始花括号 必须 独占一行,结束花括号也 必须 在方法主体后单独成一行。参数左括号后和右括号前 一定不可 有空格。
一个标准的方法声明可参照以下范例,留意其括号、逗号、空格以及花括号的位置。
<?php
namespace Vendor\Package;
class ClassName
{
public function fooBarBaz($arg1, &$arg2, $arg3 = [])
{
// 方法主体
}
}
4.4. 方法的参数
参数列表中,每个逗号后面 必须 要有一个空格,而逗号前面 一定不可 有空格。
php7
及以上版本参数必须申明类型function getSoft(int $softId, array $params) {/* todo */}
有默认值的参数,必须 放到参数列表的末尾。
<?php
namespace Vendor\Package;
class ClassName
{
public function foo($arg1, &$arg2, $arg3 = [])
{
// 方法主体
}
}
参数列表 可以 分列成多行,这样,包括第一个参数在内的每个参数都 必须 单独成行。
拆分成多行的参数列表后,结束括号以及方法开始花括号 必须 写在同一行,中间用一个空格分隔。
<?php
namespace Vendor\Package;
class ClassName
{
public function aVeryLongMethodName(
ClassTypeHint $arg1,
&$arg2,
array $arg3 = []
) {
// 方法主体
}
}
4.5. abstract
, final
, 和 static
关键字
- 需要添加
abstract
或final
声明时,必须 写在访问修饰符前,而static
则 必须 写在其后。
<?php
namespace Vendor\Package;
abstract class ClassName
{
protected static $foo;
abstract protected function zim();
final public static function bar()
{
// 方法主体
}
}
4.6. 方法及函数调用
- 方法及函数调用时,方法名或函数名与参数左括号之间 一定不可 有空格,参数右括号前也 一定不可 有空格。每个逗号前 一定不可 有空格,但其后 必须 有一个空格。
<?php
bar();
$foo->bar($arg1);
Foo::bar($arg2, $arg3);
- 参数 可以 分列成多行,此时包括第一个参数在内的每个参数都 必须 单独成行。
<?php
$foo->bar(
$longArgument,
$longerArgument,
$muchLongerArgument
);
4.7局部变量和成员变量
所有申明的变量 必须 被使用
所有被使用的变量 必须 确保已申明
所有变量 必须 初始化
5. 控制结构
控制结构的基本规范如下:
- 控制结构关键词后 必须 有一个空格。
- 控制结构关键词必须使用
boolean
类型 - 左括号
(
后 一定不可 有空格。 - 右括号
)
前也 一定不可 有空格。 - 右括号
)
与开始花括号{
间 必须 有一个空格。 - 结构体主体 必须 要有一次缩进。
- 结束花括号
}
必须 在结构体主体后单独成行。
每个结构体的主体都 必须 被包含在成对的花括号之中, 这能让结构体更加标准化,以及减少加入新行时,出错的可能性。
5.1. if
, elseif
, else
- 标准的
if
结构如下代码所示,请留意「括号」、「空格」以及「花括号」的位置, 注意else
和elseif
都与前面的结束花括号在同一行。
<?php
if ($expr1) {
// if body
} elseif ($expr2) {
// elseif body
} else {
// else body;
}
- 应该 使用关键词
elseif
代替所有else if
,以使得所有的控制关键字都像是单独的一个词。
5.2. switch
, case
标准的 switch
结构如下代码所示,留意括号、空格以及花括号的位置。
case
语句 必须 相对 switch
进行一次缩进,而 break
语句以及 case
内的其它语句都 必须 相对 case
进行一次缩进。
如果存在非空的 case
直穿语句,主体里 必须 有类似 // no break
的注释。
<?php
switch ($expr) {
case 0:
echo 'First case, with a break';
break;
case 1:
echo 'Second case, which falls through';
// no break
case 2:
case 3:
case 4:
echo 'Third case, return instead of break';
return;
default:
echo 'Default case';
break;
}
5.3. while
, do while
一个规范的 while
语句应该如下所示,注意其「括号」、「空格」以及「花括号」的位置。
<?php
while ($expr) {
// 结构体
}
标准的 do while
语句如下所示,同样的,注意其「括号」、「空格」以及「花括号」的位置。
<?php
do {
// 结构体
} while ($expr);
5.4. for
标准的 for
语句如下所示,注意其「括号」、「空格」以及「花括号」的位置。
<?php
for ($i = 0; $i < 10; $i++) {
// for 循环主体
}
5.5. foreach
标准的 foreach
语句如下所示,注意其「括号」、「空格」以及「花括号」的位置。
<?php
foreach ($iterable as $key => $value) {
// foreach 主体
}
5.6. try
, catch
标准的 try catch
语句如下所示,注意其「括号」、「空格」以及「花括号」的位置。
<?php
try {
// try 主体
} catch (FirstExceptionType $e) {
// catch 主体
} catch (OtherExceptionType $e) {
// catch 主体
}
6. 闭包
闭包声明时,关键词
function
后以及关键词use
的前后都 必须 要有一个空格。开始花括号 必须 写在声明的同一行,结束花括号 必须 紧跟主体结束的下一行。
参数列表和变量列表的左括号后以及右括号前,一定不可 有空格。
参数和变量列表中,逗号前 一定不可 有空格,而逗号后 必须 要有空格。
闭包中有默认值的参数 必须 放到列表的后面。
标准的闭包声明语句如下所示,注意其「括号」、「空格」以及「花括号」的位置。
<?php
$closureWithArgs = function ($arg1, $arg2) {
// 主体
};
$closureWithArgsAndVars = function ($arg1, $arg2) use ($var1, $var2) {
// 主体
};
- 参数列表以及变量列表 可以 分成多行,这样,包括第一个在内的每个参数或变量都 必须 单独成行,而列表的右括号与闭包的开始花括号 必须 放在同一行。
以下几个例子,包含了参数和变量列表被分成多行的多情况。
<?php
$longArgs_noVars = function (
$longArgument,
$longerArgument,
$muchLongerArgument
) {
// 主体
};
$noArgs_longVars = function () use (
$longVar1,
$longerVar2,
$muchLongerVar3
) {
// 主体
};
$longArgs_longVars = function (
$longArgument,
$longerArgument,
$muchLongerArgument
) use (
$longVar1,
$longerVar2,
$muchLongerVar3
) {
// 主体
};
$longArgs_shortVars = function (
$longArgument,
$longerArgument,
$muchLongerArgument
) use ($var1) {
// 主体
};
$shortArgs_longVars = function ($arg) use (
$longVar1,
$longerVar2,
$muchLongerVar3
) {
// 主体
};
注意,闭包被直接用作函数或方法调用的参数时,以上规则仍然适用。
<?php
$foo->bar(
$arg1,
function ($arg2) use ($var1) {
// 主体
},
$arg3
);