PHP规范PSR2

本指罗列了通用的PHP代码格式规则和建议,意在减少不同作者的编码风格差异带来的认知障碍。

  为了尽可能的提升阅读其他人代码时的效率,下面例举了一系列的通用规则,特别是有关于PHP代码风格的。各个成员项目间的共性组成了这组代码规范。当开发者们在多个项目中合作时,本指南将会成为所有这些项目中共用的一组代码规范。
因此,本指南的益处不在于这些规则本身,而在于在所有项目中共用这些规则。

这里的风格约定衍生自若干成员项目。指南作者们在多个项目中协作,推动了这些指导条款落地。
指南的关键在于共享,而不是规则本身。

1. 概述

  • 代码必须遵守 PSR-1。

  • 代码必须使用4个空格来进行缩进,而不是用制表符。

  • 一行代码的长度不建议有硬限制;软限制必须为120个字符,建议每行代码80个字符或者更少。

  • 命名空间(namespace)的声明下面必须有一行空行,并且在导入(use)的声明下面也必须有一行空行。

  • 类(class)的左花括号必须放到其声明下面自成一行,右花括号则必须放到类主体下面自成一行。

  • 方法(method)的左花括号必须放到其声明下面自成一行,右花括号则必须放到方法主体的下一行。

  • 所有的属性(property)方法(method) 必须有可见性声明;抽象(abstract)终结(final)声明必须在可见性声明之前;而静态(static)声明必须在可见性声明之后。

  • 在控制结构关键字的后面必须有一个空格;而方法(method)函数(function)的关键字的后面不可有空格。

  • 控制结构的左花括号必须跟其放在同一行,右花括号必须放在该控制结构代码主体的下一行。

  • 控制结构的左括号之后不可有空格,右括号之前也不可有空格。

文中涉及的关键词 “MUST 必须”, “MUST NOT 必须不”, “REQUIRED 必需”, “SHALL
会”, “SHALL NOT 不会”, “SHOULD 应该”, “SHOULD NOT 不应该”, “RECOMMENDED
推荐的”, “MAY 可能”, 和 “OPTIONAL 可选的” 在RFC 2119 中有具体描述.

1.1. 示例

这个示例中简单展示了上文中提到的一些规则:

namespace VendorPackage;

use FooInterface;
use BarClass as Bar;
use OtherVendorOtherPackageBazClass;

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()
{
// 方法主体
}
}

概览

  1. 代码必需遵循 “基础编码标准” PSR [PSR-1]。
  2. 代码缩进必须使用 4 空格,而不是tab。
  3. 行长度必须无硬性限制; 软性限制必须为120字符;应该少于等于80字。
  4. namespace声明后必须有一个空行,use声明后也必须有一个空行。
  5. 类的{ 必须在类名的下一行, }必须在body的下一行。
  6. 方法的 { 必须在方法签名的下一行,} 必须在body的下一行。
  7. 所有的属性和方法都要设置可见性; abstract和
    final必须在可见性之前声明;static 必须在可见性后声明。
  8. 结构控制关键词后必须有一个空格; 方法和函数必须没有空格。
  9. 结构控制的 { 必须在同一行,} 必须在body的下一行。
  10. 结构控制的 ( 后必须有空格, 结构控制的 ) 前必须没有空格。

2. 通则

例子

下面是一个综合的例子,可以帮助你对规则有一个概略的认识。

<?php
namespace VendorPackage;

use FooInterface;
use BarClass as Bar;
use OtherVendorOtherPackageBazClass;

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

2.1 基础代码规范

代码必须遵守 PSR-1 中的所有规则。

基本规则

2.2 源文件

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

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

纯PHP代码源文件的关闭标签?> 必须省略。

基本编码标准

代码必须遵循PSR-1的条款。

2.3. 行

行长度不可有硬限制。

行长度的软限制必须是120个字符;对于软限制,代码风格检查器必须警告但不可报错。

一行代码的长度不建议超过80个字符;较长的行建议拆分成多个不超过80个字符的子行。

在非空行后面不可有空格。

空行可以用来增强可读性和区分相关代码块。

一行不可多于一个语句。

文件

  1. 所有文件必须使用 Unix LF (linefeed) 换行。
  2. 所有PHP文件必须使用单个空行结束。
  3. 只包含PHP的代码必须忽略php结束标记 ? >。

2.4. 缩进

代码必须使用4个空格,且不可使用制表符来作为缩进。

注意:代码中只使用空格,且不和制表符混合使用,将会对避免代码差异,补丁,历史和注解中的一些问题有帮助。空格的使用还可以使通过调整细微的缩进来改进行间对齐变得更加的简单。

  1. 行长度必须没有硬性限制。
  2. 长度的软性限制必须为120字符;自动代码风格检查必须将120字设置为警告,必须不能设置为错误。
  3. 行不应该超过80字符;超过这个长度的行应该切分为多个不超过80字符的行。
  4. 非空行的结束必须没有尾随空格。
  5. 为增强可读性,可增加空行来标志代码的关联性。
  6. 每行包含的语句必须不能超过1条。

2.5. 关键字和 True/False/Null

PHP关键字(keywords)必须使用小写字母。

PHP常量truefalsenull 必须使用小写字母。

缩进

  1. 代码必须使用 4 空格的缩进, 必须不用tab作为缩进。

注意:只使用空格,不用tab,有助于避免diffs,patches,
history和annotations的问题。使用空格也有助于对齐。

3. 命名空间(Namespace)导入(Use)声明

命名空间(namespace)的声明后面必须澳门新葡亰娱乐在线,有一行空行。

所有的导入(use)声明必须放在命名空间(namespace)声明的下面。

一句声明中,必须只有一个导入(use)关键字。

导入(use)声明代码块后面必须有一行空行。

示例:

namespace VendorPackage;

use FooClass;
use BarClass as Bar;
use OtherVendorOtherPackageBazClass;

// … 其它PHP代码 …

关键词(保留字) 和 true/false/null

  1. PHP保留字必须小写.
  2. PHP常量 true, false和 null 必须小写.

4. 类(class)属性(property)方法(method)

术语“类”指所有的类(class)接口(interface)特性(trait)

Namespace 和 Use 声明

  1. namespace 声明之后必须有空行。
  2. 所有use 声明,必须在namespace声明之后。
  3. 每个声明必须单独使用一个use。
  4. use声明区之后必须有一个空行。

例如:

<?php
namespace VendorPackage;

use FooClass;
use BarClass as Bar;
use OtherVendorOtherPackageBazClass;

// ... additional PHP code ...

4.1. 扩展(extend)实现(implement)

一个类的扩展(extend)实现(implement)关键词必须类名(class name)在同一行。

类(class)的左花括号必须放在下面自成一行;右花括号必须放在类(class)主体的后面自成一行。

namespace VendorPackage;

use FooClass;
use BarClass as Bar;
use OtherVendorOtherPackageBazClass;

class ClassName extends ParentClass implements ArrayAccess,
Countable
{
// 常量、属性、方法
}

实现(implement)列表可以被拆分为多个缩进了一次的子行。如果要拆成多个子行,列表的第一项必须要放在下一行,并且每行必须只有一个接口(interface)

namespace VendorPackage;

use FooClass;
use BarClass as Bar;
use OtherVendorOtherPackageBazClass;

class ClassName extends ParentClass implements
ArrayAccess,
Countable,
Serializable
{
// 常量、属性、方法
}

类, 属性 和 方法

这里的“类”包括 class、interface 和 trait。

4.2. 属性(property)

所有的属性(property)必须声明其可见性。

变量(var)关键字不可用来声明一个属性(property)

一条语句不可声明多个属性(property)

属性名(property name) 不推荐用单个下划线作为前缀来表明其保护(protected)私有(private)的可见性。

一个属性(property)声明看起来应该像下面这样。

namespace VendorPackage;

class ClassName
{
public $foo = null;
}

继承 和 实现

extends 和 implements 关键字必须和类名在同一行声明。

类的 { 必须独占一行; } 必须在body的下一行。

<?php
namespace VendorPackage;

use FooClass;
use BarClass as Bar;
use OtherVendorOtherPackageBazClass;

class ClassName extends ParentClass implements ArrayAccess, Countable
{
    // constants, properties, methods
}

implements
多个接口时,接口列表可以被分到多行,每个子行有一个缩进。如果这么做,第一个接口必须在implements
下一行,每行只能有一个接口。

<?php
namespace VendorPackage;

use FooClass;
use BarClass as Bar;
use OtherVendorOtherPackageBazClass;

class ClassName extends ParentClass implements
    ArrayAccess,
    Countable,
    Serializable
{
    // constants, properties, methods
}

4.3. 方法(method)

所有的方法(method)必须声明其可见性。

方法名(method name) 不推荐用单个下划线作为前缀来表明其保护(protected)私有(private)的可见性。

方法名(method name)在其声明后面不可有空格跟随。其左花括号必须放在下面自成一行,且右花括号必须放在方法主体的下面自成一行。左括号后面不可有空格,且右括号前面也不可有空格。

一个方法(method)声明看来应该像下面这样。
注意括号,逗号,空格和花括号的位置:

namespace VendorPackage;

class ClassName
{
public function fooBarBaz($arg1, &$arg2, $arg3 = [])
{
// 方法主体部分
}
}

属性

所有属性都必须声明 visibility(可见性)。

Var 关键字必须不能用于声明属性。

每行必须只声明一个属性。

不应该通过前缀下划线来标示protected和private的属性。

例:

<?php
namespace VendorPackage;

class ClassName
{
    public $foo = null;
}

4.4. 方法(method)的参数

在参数列表中,逗号之前不可有空格,而逗号之后则必须要有一个空格。

方法(method)中有默认值的参数必须放在参数列表的最后面。

namespace VendorPackage;

class ClassName
{
public function foo($arg1, &$arg2, $arg3 = [])
{
// 方法主体部分
}
}

参数列表可以被拆分为多个缩进了一次的子行。如果要拆分成多个子行,参数列表的第一项必须放在下一行,并且每行必须只有一个参数。

当参数列表被拆分成多个子行,右括号和左花括号之间必须又一个空格并且自成一行。

namespace VendorPackage;

class ClassName
{
public function aVeryLongMethodName(
ClassTypeHint $arg1,
&$arg2,
array $arg3 = []
) {
// 方法主体部分
}
}

方法

所有方法都必须声明可见性。

不应该通过前缀下划线来标示protected和private的方法。

声明方法时,方法名的后必须没有空格。 { 必须在同一行, }
必须在body的下一行。 (后必须没有空格,) 前必须没有空格。

一个方法声明的例子如下,注意 小括号,逗号,空格 和 花括号 的位置:

<?php
namespace VendorPackage;

class ClassName
{
    public function fooBarBaz($arg1, &$arg2, $arg3 = [])
    {
        // method body
    }
}

4.5. 抽象(abstract)终结(final)和 静态(static)

当用到抽象(abstract)终结(final)来做类声明时,它们必须放在可见性声明的前面。

而当用到静态(static)来做类声明时,则必须放在可见性声明的后面。

namespace VendorPackage;

abstract class ClassName
{
protected static $foo;

abstract protected function zim();

final public static function bar()
{
// 方法主体部分
}
}

发表评论

电子邮件地址不会被公开。 必填项已用*标注

相关文章

网站地图xml地图