缩进
项目编码规范
概览
这个例子包含规范中将要描述的一些规则:
1<?php 2 3namespaceVendor\Package;
4 5useFooInterface;
6useBarClassasBar;
7useOtherVendor\OtherPackage\BazClass;
8 9classFooextendsBarimplementsFooInterface10{
11publicfunctionsampleFunction($a, $b = null)
12 {
13if ($a === $b) {
14 bar();
15 } elseif ($a > $b) {
16$foo->bar($arg1);
17 } else {
18BazClass::bar($arg2, $arg3);
19 }
20 }
2122finalpublicstaticfunctionbar()
23 {
24// method body25 }
26}
27
基础编码标准
文件
所有 PHP 文件都必须使用 UTF-8 编码,文件头不允许出现 BOM 标记。
所有 PHP 文件都必须使用 Unix LF 格式作为行的结尾。
所有 PHP 文件都必须以一个空行结束。
在只包含有 PHP 代码的文件中不允许使用 ?> 作为结束标签。
不允许使用short tag"<?"开头,必须使用"<?php"开头.
缩进
代码缩进统一为 4 个空格,不允许使用 tab。
行
在非空行的结尾不允许出现尾随空白。
使用空行来提高代码的可读性,并分离功能相关的代码块。
每一行代码只允许一条语句。
方法与方法之间,都至少有一个空行。
PHP 关键字 和 true/false/null
PHP 关键字 必须使用小写。
关键字 true, false 和 null 必须使用小写。
=、=> 等操作符的前后都必须有一个空格
字符串
不带任何变量转换的字符串必须使用单引号。
不允许对两个不带变量的字符串使用连接符,应该用一个字符串表示.
注释
行尾注释和结束代码的分号之间至少有一个空格。
注释标记 // 和 /* 之后必须有一个空格。
不允许使用#做为注释标记.
命名空间(namespace)和 use 关键字的使用
在 namespace 声明之后必须有一个空行。
所有 use 声明必须出现在 namespace 声明的后面。
每一行只允许出现一个 use 关键字。
在 use 定义块之后必须有一个空行。
例子:
1namespaceVendor\Package;
23useFooClass;
4useBarClassasBar;
5useOtherVendor\OtherPackage\BazClass;
67// ... additional PHP code ...
类、类属性和类方法
类在这里泛指所有类(class)、接口(interface)、特征(trait)
类、接口和特征的名称必须以大写开头,如:PartnerInfo、Partner_Info
一个文件中只能包含类、接口和特征中的一个,不允许出现多个.
类方法的名称和变量的名称定义必须由小写开头,如:getBrandName, queryAll, $lastSql、$sqlQueries
类常量
类的常量定义必须全部为大写,并用下划线分割每个单词,如:BRAND_DRAFT、BRAND_DELETED
1classPartnerInfo2{
3constBRAND_DRAFT = 0;
4constBRAND_SUBMIT = 1;
5constBRAND_APPROVE = 2;
6constBRAND_REJECT = 3;
7constBRAND_DELETED = 4;
8}
扩展(extends)和实现(implements)
关键字 public,function,extends,implements以及类名只用一个空格隔开,不能用两个或两个以上的空格.
关键字 extends 和 implements 必须和类名在同一行。
开始大括号必须在一个独立的行,结束大括号必须在下一行或代码块结束后的下一行。
1namespaceVendor\Package;
2 3useFooClass;
4useBarClassasBar;
5useOtherVendor\OtherPackage\BazClass;
6 7classClassNameextendsParentClassimplements \ArrayAccess, \Countable 8{
9// constants, properties, methods10}
要实现的接口队列可以被写到多行,每一行都要有相同的缩进,第一个接口必须被写到新的一行,并且每一行只能有一个接口。
1namespaceVendor\Package;
2 3useFooClass;
4useBarClassasBar;
5useOtherVendor\OtherPackage\BazClass;
6 7classClassNameextendsParentClassimplements 8 \ArrayAccess,
9 \Countable,
10 \Serializable11{
12// constants, properties, methods13}
类属性
所有类属性的前面必须定义其可见性。
不允许使用 var 关键字来定义一个类属性。
每一行只允许定义一个类属性。
类属性名称不允许使用单一下划线开头来表示其 protected 和 private 的可见性。
一个类属性的定义看上去像下面这样:
1namespaceVendor\Package;
23classClassName4{
5public$foo = null;
6}
类方法
所有类方法都必须定义其可见性(public/protected/private)。
方法名不允许使用单一下划线开头来表示其 protected 和 private 的可见性。
类方法定义的名称后面不允许出现空格。开始大括号和方法名称必须在同一行,结束大括号必须在下一行或代码块结束后的下一行。在开始括号的后面和结束括号的前面都不允许出现空格。
一个类方法的声明看上去像下面这样,注意括号、逗号、空格和大括号的位置:
1namespaceVendor\Package;
2 3classClassName 4{
5publicfunctionfooBarBaz($arg1, &$arg2, $arg3 = [])
6 {
7// method body 8 }
9}
类方法的参数
在参数队列中,逗号之前不允许出现空格,逗号之后必须有一个空格。
在方法的参数队列中定义带默认值的参数时,必须放到队列的末尾。
1namespaceVendor\Package;
2 3classClassName 4{
5publicfunctionfoo($arg1, &$arg2, $arg3 = [])
6 {
7// method body 8 }
9}
参数队列可以被写到多行,每一行都需要用一个同样的缩进,第一个参数必须被写到新的一行,并且每一行只能有一个参数。
当参数队列被写到多行时,结束括号和开始大括号必须被写到一行,两者之间必须有一个空格。
1namespaceVendor\Package;
2 3classClassName 4{
5publicfunctionaVeryLongMethodName(
6ClassTypeHint$arg1,
7 &$arg2,
8array$arg3 = []
9 ) {
10// method body11 }
12}
abstract, final 和 static
当定义 abstract 和 final 声明时,必须出现在可见性声明之前。
当定义 static 声明时,必须出现在可见性声明之后。
1namespaceVendor\Package;
2 3abstractclassClassName 4{
5protectedstatic$foo;
6 7abstractprotectedfunctionzim();
8 9finalpublicstaticfunctionbar()
10 {
11// method body12 }
13}
类方法和一般函数(function)的调用
当调用一个类方法或者一般函数时,方法或函数名称和开始括号之间不允许出现空格,在开始括号之后和结束括号之前都不允许出现空格。
在参数队列里,逗号之前不允许出现空格,逗号之后必须有一个空格。
1bar();
2$foo->bar($arg1);
3Foo::bar($arg2, $arg3);
参数队列可以被写到多行,每一行都需要用一个同样的缩进,第一个参数必须被写到新的一行,并且每一行只能有一个参数。
1$foo->bar(
2$longArgument,
3$longerArgument,
4$muchLongerArgument5);
控制结构
控制结构的一般样式规则如下:
- 在控制结构的关键字后面必须有一个空格
- 开始括号之后不能出现空格
- 结束括号之前不能出现空格
- 在结束括号和开始大括号之间必须有一个空格
- 代码块(结构体)必须有一个缩进
- 结束大括号必须在代码块结束后的下一行
每个代码块必须被封装到一个大括号内,以标准化代码结构,同时减少在添加代码时间引入错误的可能性。
if, elseif 和 else
一个 if 结构看上去像下面这样,注意括号、空格和大括号的位置。关键字 else 和 elseif 和前一个代码块的结束大括号必须在同一行
1if ($expr1) {
2// if body3} elseif ($expr2) {
4// elseif body5} else {
6// else body;7}
必须用 elseif 代替 else if,让控制关键字看上去是一个单词,同时避免出现代码块逻辑错误。
switch 和 case
一个 case 声明相对于 switch 必须有一个缩进,关键字 break 必须和 case 代码块有相同的缩进。
当一个 case 代码块不需要 break 的时候必须加上注释描述,比如 // no break
一个 switch 结构看上去像下面这样,注意括号、空格和大括号的位置。
1switch ($expr) {
2case0:
3echo'First case, with a break';
4break;
5case1:
6echo'Second case, which falls through';
7// no break 8case2:
9case3:
10case4:
11echo'Third case, return instead of break';
12return;
13default:
14echo'Default case';
15break;
16}
while 和 do while
一个 while 声明看上去像下面这样,注意括号、空格和大括号的位置。
1while ($expr) {
2// structure body3}
同样,一个 do while 声明看上去像下面这样,注意括号、空格和大括号的位置。
1do {
2// structure body;3} while ($expr);
for
一个 for 声明看上去像下面这样,注意括号、空格和大括号的位置。
1for ($i = 0; $i < 10; $i++) {
2// for body3}
foreach
一个 foreach 声明看上去像下面这样,注意括号、空格和大括号的位置。
1foreach ($iterableas$key => $value) {
2// foreach body3}
try 和 catch
一个 try catch 代码块看上去像下面这样,注意括号、空格和大括号的位置。
1try {
2// try body3} catch (FirstExceptionType$e) {
4// catch body5} catch (OtherExceptionType$e) {
6// catch body7}
闭合(Closure)
在 function 和 use 关键字的前后必须加上空格。
开始大括号必须和 function 关键字在同一行的尾部,结束大括号必须在下一行,或代码块结束后的下一行。
在定义参数队列和变量队列时,开始括号之后和结束符号之前,都不允许出现空格。
在定义参数队列和变量队列时,逗号的前面不允许出现空格,在逗号之后必须加上一个空格。
需要给闭合定义有默认值的参数时,必须放到参数队列的最后。
一个闭合定义看上去像下面这样,注意括号、逗号、空格和大括号的位置:
1$closureWithArgs = function ($arg1, $arg2) {
2// body3};
45$closureWithArgsAndVars = function ($arg1, $arg2) use ($var1, $var2) {
6// body7};
参数队列和变量队列可以被写到多行,每一行都需要用一个同样的缩进,第一个参数或者变量必须被写到新的一行,并且每一行只能有一个参数或者变量。
当参数队列和变量队列被写到多行时,结束括号和开始大括号必须被写到一行,两者之间必须有一个空格。
以下例子示范了把参数队列和变量队列写到多行的情况:
1$longArgs_noVars = function (
2$longArgument,
3$longerArgument,
4$muchLongerArgument 5) {
6// body 7};
8 9$noArgs_longVars = function () use (
10$longVar1,
11$longerVar2,
12$muchLongerVar313) {
14// body15};
1617$longArgs_longVars = function (
18$longArgument,
19$longerArgument,
20$muchLongerArgument21) use (
22$longVar1,
23$longerVar2,
24$muchLongerVar325) {
26// body27};
2829$longArgs_shortVars = function (
30$longArgument,
31$longerArgument,
32$muchLongerArgument33) use ($var1) {
34// body35};
3637$shortArgs_longVars = function ($arg) use (
38$longVar1,
39$longerVar2,
40$muchLongerVar341) {
42// body43};
以上闭合的格式规范同样适用于闭合在作为其它方法调用的参数时:
1$foo->bar(
2$arg1,
3function ($arg2) use ($var1) {
4// body5 },
6$arg37);