PHP 编码风格规范指南
概览
代码必需遵循 基础编码标准 PSR [PSR-1]。
代码缩进必须使用 4 空格,而不是tab。
行长度必须无硬性限制; 软性限制必须为120字符;应该少于等于80字。
namespace声明后必须有一个空行,use声明后也必须有一个空行。
类的{ 必须在类名的下一行, }必须在body的下一行。
方法的 { 必须在方法签名的下一行,} 必须在body的下一行。
所有的属性和方法都要设置可见性; abstract和 final必须在可见性之前声明;static 必须在可见性后声明。
结构控制关键词后必须有一个空格; 方法和函数必须没有空格。
结构控制的 { 必须在同一行,} 必须在body的下一行。
结构控制的 ( 后必须有空格, 结构控制的 ) 前必须没有空格。
例子
下面是一个综合的例子,可以帮助你对规则有一个概略的认识。
<?php
namespace Vendor\Package;
use FooInterface;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;
class Foo extends Bar implements FooInterface
{
public function sampleFunction($$a, $$b = null)
{
if ($$a === $$b) {
bar();
} elseif ($$a > $$b) {
$$foo->bar($$arg1);
} else {
BazClass::bar($$arg2, $$arg3);
}
}
final public static function bar()
{
// 方法 body
}
}
基本规则
基本编码标准
代码必须遵循PSR-1的条款。
文件
所有文件必须使用 Unix LF (linefeed) 换行。
所有PHP文件必须使用单个空行结束。
只包含PHP的代码必须忽略php结束标记 ? >。
行
行长度必须没有硬性限制。
长度的软性限制必须为120字符;自动代码风格检查必须将120字设置为警告,必须不能设置为错误。
行不应该超过80字符;超过这个长度的行应该切分为多个不超过80字符的行。
非空行的结束必须没有尾随空格。
为增强可读性,可增加空行来标志代码的关联性。
每行包含的语句必须不能超过1条。
缩进
代码必须使用 4 空格的缩进, 必须不用tab作为缩进。
注意:只使用空格,不用tab,有助于避免diffs,patches, history和annotations的问题。使用空格也有助于对齐。
关键词(保留字) 和 true/false/null
PHP保留字必须小写.
PHP常量 true, false和 null 必须小写.
Namespace 和 Use 声明
namespace 声明之后必须有空行。
所有use 声明,必须在namespace声明之后。
每个声明必须单独使用一个use。
use声明区之后必须有一个空行。
例如:
<?php
namespace Vendor\Package;
use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;
// ... additional PHP code ...
类, 属性 和 方法
这里的 类 包括 class、interface 和 trait。
继承 和 实现
extends 和 implements 关键字必须和类名在同一行声明。
类的 { 必须独占一行; } 必须在body的下一行。
<?php
namespace Vendor\Package;
use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;
class ClassName extends ParentClass implements \ArrayAccess, \Countable
{
// constants, properties, methods
}
implements 多个接口时,接口列表可以被分到多行,每个子行有一个缩进。如果这么做,第一个接口必须在implements 下一行,每行只能有一个接口。
<?php
namespace Vendor\Package;
use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;
class ClassName extends ParentClass implements
\ArrayAccess,
\Countable,
\Serializable
{
// constants, properties, methods
}
属性
所有属性都必须声明 visibility(可见性)。
Var 关键字必须不能用于声明属性。
每行必须只声明一个属性。
不应该通过前缀下划线来标示protected和private的属性。
例:
<?php
namespace Vendor\Package;
class ClassName
{
public $$foo = null;
}
方法
所有方法都必须声明可见性。
不应该通过前缀下划线来标示protected和private的方法。
声明方法时,方法名的后必须没有空格。 { 必须在同一行, } 必须在body的下一行。 (后必须没有空格,) 前必须没有空格。
一个方法声明的例子如下,注意 小括号,逗号,空格 和 花括号 的位置:
<?php
namespace Vendor\Package;
class ClassName
{
public function fooBarBaz($$arg1, &$$arg2, $$arg3 = [])
{
// method body
}
}
方法参数
方法的形参列表中, 每个逗号前必须没有空格。有默认值的参数必须在参数列表的最后。
<?php
namespace Vendor\Package;
class ClassName
{
public function foo($$arg1, &$$arg2, $$arg3 = [])
{
// method body
}
}
参数列表可以切分为多行,每个子行要有一个缩进。如果这么做,第一个参数必须独占一行,每行只能有一个参数。
参数列表切分为多行时,右括号)和左花括号{必须在同一行,之前必须有一个空格。
<?php
namespace Vendor\Package;
class ClassName
{
public function aVeryLongMethodName(
ClassTypeHint $$arg1,
&$$arg2,
array $$arg3 = []
) {
// method body
}
}
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()
{
// method body
}
}
方法和函数调用
写方法或函数调用时,方法/函数名 和 左括号( 之间,必须没有空格, 右括号 ) 之前必须没有空格。在参数列表中,逗号间必须没有逗号,每个逗号后必须有一个空格。
<?php
$$foo->bar(
$$longArgument,
$$longerArgument,
$$muchLongerArgument
);
控制结构
控制结构通常遵循以下风格:
控制结构关键词后必须有一个空格。
左括号后必须没有空格。
右括号前必须没有空格。
又括号和左花括号之间必须有一个空格。
body必须有一层缩进。
右花括号必须在body下一行。
每个控制结构的body必须用花括号括起来。 即保证外观统一,又减少了添加新行时引入的错误。
if, elseif, else
if 结构如下所示。注意括号、空格、花括号的位置;同时留意 else 和 elseif 与前一部分的 } 在同一行。
<?php
if ($$expr1) {
// if body
} elseif ($$expr2) {
// elseif body
} else {
// else body;
}
elseif关键字不应该被 else if 代替。
switch, case
Switch结构如下所示。注意括号、空格和花括号的位置。 case 语句相对于switch必须有一个缩进, break关键字 或者其他终结性的关键字必须和case body在同一缩进层级。在非空的case body,如果没有终结性语句,必须加上注释 // 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;
}
while, do while
while结构如下所示。 注意括号、空格和花括号的位置。
<?php
while ($$expr) {
// structure body
}
do-while接口如下所示。 注意括号、空格和花括号的位置。
<?php
do {
// structure body;
} while ($$expr);
for
for 结构如下所示。 注意括号、空格和花括号的位置。
<?php
for ($$i = 0; $$i < 10; $$i++) {
// for body
}
foreach
foreach 结构如下所示。 注意括号、空格和花括号的位置。
<?php
foreach ($$iterable as $$key => $$value) {
// foreach body
}
try, catch
try-catch区块如下所示。 注意括号、空格和花括号的位置。
<?php
try {
// try body
} catch (FirstExceptionType $$e) {
// catch body
} catch (OtherExceptionType $$e) {
// catch body
}
Closure 闭包
声明闭包必须在function关键字后留一个空格,在use关键字前后各留一个空格。
左花括号必须在同一行, 右花括号必须在body的下一行。
参数或变量列表的左括号后 和 右括号前必须没有空格。
参数和变量列表的逗号前必须没有空格,每个逗号后必须有一个空格。
有默认值的参数必须排在最后。
闭包的声明如下所示。 注意括号,逗号,空格和花括号的位置:
<?php
$$closureWithArgs = function ($$arg1, $$arg2) {
// body
};
$$closureWithArgsAndVars = function ($$arg1, $$arg2) use ($$var1, $$var2) {
// body
};
参数列表和变量列表可以拆分到多行,每个子行有一层缩进。 这么做的时候,第一个列表成员必须独占一行,每行只能有一个列表成员。
参数或变量列表拆分为多行时,到了列表的末尾, 右括号 和 左花括号必须放在同一行,中间有一个空格。
例子:
<?php
$$longArgs_noVars = function (
$$longArgument,
$$longerArgument,
$$muchLongerArgument
) {
// body
};
$$noArgs_longVars = function () use (
$$longVar1,
$$longerVar2,
$$muchLongerVar3
) {
// body
};
$$longArgs_longVars = function (
$$longArgument,
$$longerArgument,
$$muchLongerArgument
) use (
$$longVar1,
$$longerVar2,
$$muchLongerVar3
) {
// body
};
$$longArgs_shortVars = function (
$$longArgument,
$$longerArgument,
$$muchLongerArgument
) use ($$var1) {
// body
};
$$shortArgs_longVars = function ($$arg) use (
$$longVar1,
$$longerVar2,
$$muchLongerVar3
) {
// body
};
注意:当闭包被直接作为函数或方法调用的参数时,以上规则同样适用。
<?php
$$foo->bar(
$$arg1,
function ($$arg2) use ($$var1) {
// body
},
$$arg3
);
结语
本指南刻意忽略了许多风格和实践。包括但不限于:
声明全局变量和全局常量。
声明函数。
操作符和赋值。
行间对齐。
注释和文档区。
类名前后缀。
最佳实践。