PSR-2 代码风格指南

代码风格指南

---

翻译自：

https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md

PSR-2 在 PSR-1 的基础上进行了继承和扩展

---

1. 概述

• 代码 必须 遵循 PSR-1 规范
• 代码 必须 使用 4个空格 的缩进，而不是制表符 tab
• 一行代码长度 不可 有硬性限制，软限制必须为120个字符，也应当是80个字符或者更少
• 在 namespace 声明如下 必须 有一个空行。并且 use 声明代码块如下也必须有一个空行
• 类的開始花括号 必须 放到下一行，结束花括号 必须 放在类主体的下一行
• 方法的開始花括号 必须 放在下一行，结束花括号 必须 放在方法主体如下
• 所有的属性和方法的可见性 必须 显式(译者注：Public, Protect, Private)声明，abstract 和 final 声明必须在显式声明可见性以前。static 声明必须在显式声明可见性以后
• 控制结构（译者注：for，while 等）的关键词 必须 在后面有一个空格； 方法和函数 必须 没有
• 控制结构（译者注：for，while 等）的開始花括号 必须 放在同一行，结束花括号 必须 放在控制主体的下一行
• 控制结构的左括号后面不可有空格。右括号以前不可有空格

1.1. 演示样例

对于上述规则的一些演示样例：

<?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() {
        // method body
    }
}

---

2. 常规

2.1 基础编码规范

代码 必须 遵照 PSR-1 的所有规范

2.2 文件

所有的 PHP 文件 必须 使用 Unix LF (换行)做为行结束符

所有PHP文件 必须 以一个空行结束

仅仅有 PHP 代码的文件关闭标签 ?> 必须 省略

2.3 行

每行的长度 不可 有硬性限制

每行长度的软限制必须是 120 个字符。对于软限制。本身主动样式检查器 必须 警告但 不可 报错

每行实际长度 不该该 超过 80 个字符，较长的行 应该 被拆分红多个不超过 80 个字符的兴许行

在非空行后面 不可 有空格

空行 可以 用来改善可读性和区分相关的代码块

每行 不可 多于一个语句

2.4 缩进

代码 必须 使用 4个空格 的缩进。并且 不可 使用制表符 tab 做为缩进

注意：仅仅用空格。不与制表符 tab 混合使用，将会对避免代码差别。补丁，历史和注解中的一些问题有帮助。

使用空格还可以使调整细微的缩进来改进行间对齐变得简单

2.5 关键词 keywords 和 True/False/Null

PHP 的关键词 keywords 必须 用小写

PHP 中的常量 true。false，null 必须 所有小写

---

3. Namespace 和 Use 声明

假设存在。namespace 声明后面 必须 有一个空行

假设存在，所有的 use 声明 必须 放在 namespace 声明如下

一个 use 关键字 必须 仅仅用于一个声明

use 声明代码块后面 必须 有一个空行

例：

<?php
namespace Vendor\Package;

use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

// ... additional PHP code ...

---

4. 类 class，属性 property，方法 method

类 class 指所有的类 class。接口 interface 和特性 trait

4.1. 继承 extends 和接口实现 implements

一个类的 extends 和 implements 关键词 必须 和类名 class name 在同一行

类的開始花括号 必须 放在如下自成一行，结束花括号 必须 放在类主体的后面自成一行

<?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 的列表 可以 被拆分为多个有一次缩进的兴许行。

假设这么作，接口列表的第一个接口名 必须 要放在下一行，并且每行 必须 仅仅有一个接口。

<?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
}

4.2. 属性 property

所有的属性 必须 显式声明可见性

var 关键词 不可 用来声明属性

一个语句 不可 声明多个属性

属性名称 不该该 使用单个下划线做为前缀来代表保护或私有的可见性

一个属性声明应该像这样：

<?php
namespace Vendor\Package;

class ClassName {
    public $foo = null;
}

4.3. 方法 method

所有的方法 必须 显式声明可见性

方法名 不该该 使用单个下划线做为前缀来代表保护或私有的可见性

方法名在声明以后 不可 尾随一个空格。

開始花括号 必须 放在如下自成一行，并且结束花括号 必须 放在方法主体的如下自成一行

左括号后面 不可 有空格。右括号前面 不可 有空格

一个方法定义应该像如下这样， 注意括号，逗号。空格和花括号：

<?
php namespace Vendor\Package; class ClassName { public function fooBarBaz($arg1, &$arg2, $arg3 = []) { // method body } }

4.4. 方法參数 Method Arguments

參数列表中。逗号以前 不可 有空格。逗号以后 必须 要有一个空格

方法中有默认值的參数 必须 放在參数列表的最后面

<?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 } }

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() {
        // method body
    }
}

4.6. 方法 method 和函数 function 调用

当进行函数或方法调用的时候。在方法或者函数名与左括号之间 不可 有空格。左括号以后 不可 有空格。右括号以前 不可 有空格

參数列表中，逗号以前 不可 有空格，逗号以后 必须 有一个空格

<?php
bar();
$foo->bar($arg1);
Foo::bar($arg2, $arg3);

參数列表 可以 被拆分红多个有一个缩进的兴许行。假设这么作，列表中的第一项 必须 放在下一行，并且每一行 必须 仅仅有一个參数

<?php
$foo->bar(
    $longArgument,
    $longerArgument,
    $muchLongerArgument
);

---

5. 控制结构 Control Structures

对于控制结构一般的样式规则例如如下：

• 控制结构关键词以后 必须 有一个空格
• 左括号以后 不可 有空格
• 右括号以前 不可 有空格
• 在右括号和開始花括号之间 必须 有一个空格
• 代码主体 必须 有一次缩进
• 结束花括号 必须 在主体的下一行

结构的主体部分 必须 被括在花括号中，这使结构体看起来更加标准。下降了在主体部分中增长新行时出现错误的可能

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 不适用 break 结束）则必须有一个类似 // 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) {
    // structure body
}

一样的。一个 do while 语句看起来应该像如下这样。注意括号，空格和花括号的位置

<?php
do {
    // structure body;
} while ($expr);

5.4. for

一个 for 语句看起来应该像如下这样。注意括号，空格和花括号的位置

<?php
for ($i = 0; $i < 10; $i++) {
    // for body
}

5.5. foreach

一个 foreach 语句看起来应该像如下这样。注意括号，空格和花括号的位置

<?
php foreach ($iterable as $key => $value) { // foreach body }

5.6. try，catch

一个 try catch 语句看起来应该像如下这样。注意括号，空格和花括号的位置

<?php
try {
    // try body
} catch (FirstExceptionType $e) {
    // catch body
} catch (OtherExceptionType $e) {
    // catch body
}

---

6. 闭包 Closures

闭包在声明时 function 关键词以后 必须 有一个空格，并且 use 以前也需要一个空格

開始花括号 必须 与 function 在同一行，结束花括号 必须 在主体的下一行

參数列表和变量列表的左括号以后 不可 有空格，其右括号以前也 不可 有空格

在參数列表和变量列表中，逗号以前 不可 有空格，逗号以后 必须 有空格

闭包带默认值的參数 必须 放在參数列表后面

一个闭包声明看起来应该像如下这样。注意括号，空格和花括号的位置

<?
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
);

---

7. 结论

该指南中有很是多风格的元素和作法被有益忽略掉。这些包含如下的等等：

• 全局变量和全局常量的声明
• 方法声明
• 操做符和赋值
• 行间对齐
• 凝视和文档块
• 类名给你前缀和后缀
• 最佳实践

---

敲了快两个小时。

。要疯了（生无可恋）。。