PHP 编码规范

2017年11月2日 PHP 编程发表评论

本规范包含 PHP 开发时程序编码中命名规范、代码缩进规则、控制结构、函数调用、函数定义、注释、包含代码、PHP标记、常量命名等方面的规则。

依据”约定大于规范”原则，本规范不强制指定和推荐某种格式，并就实际开发中个人习惯做了一些调整。

1. 文件格式

1.1 文件标记

所有 PHP 文件，其代码标记均使用 <?php ?> 完整 PHP 标签，不建议使用 <?= ?> 短标签。

对于只含有 PHP 代码的文件，必须省略最后的 ?> 结束标签。这是为了防止多余空格或者其他字符影响到代码。

1.2 文件和目录命名

程序文件名和目录名均采用有意义的英文命名，不使用拼音或无意义的字母，多个词间使用驼峰法命名。

// 类统一采用
DemoTest.class.php
// 接口统一采用
DemoTest.interface.php

// 其他按照各自的方式

2. 命名规范

2.1 命名空间和类命名

根据规范，每个类都独立为一个文件，且命名空间至少有一个层次：顶级的组织名称（vendor name）.

类的命名必须遵循 class MyClass 大写开头的驼峰命名规范。

<?php
// PHP 5.3及以后版本的写法
namespace Vendor\Model;

class Foo
{

}

2.2 类的常量、属性和方法命名

类的常量名所有字母都必须大写，多个词间使用下划线分隔。

<?php
namespace Vendor\Model;

class Foo
{
    const VERSION = '1.0';
    const DATE_APPROVED = '2017-11-01';
}

类的属性命名可以遵循小写开头的驼峰式 $userAvatar 或下划线分割式 $user_avatar。此条规范不做强制要求，但无论遵循那种命名方式，都应该在一定范围内保持一致。这个范围可以是整个团队、整个包、整个类或整个方法。

方法名称必须符合 showMsg() 式的小写开头的驼峰命名规范，建议采用动词或动词加名词的命名方式。不建议下面的函数名：

getPublishedAdvertisementByCategoryAndCategoryIdAndPosition()
// 上面的函数名可以提炼为
getAd($category, $categoryId, $position, $published)

2.3 关键字以及 True/False/Null

PHP 所有的 关键字 必须全部小写。常量 true、false 和 null 也必须全部小写。

2.4 数据库命名

在数据库相关的命名中，一律不出现大写。详细规则如下所示。

数据表命名遵循以下规范：
- 表名均使用小写字母；
- 表名字使用统一的前缀，且前缀不能为空（模块化，且可有效规避 MYSQL 保留字）；
- 对于多个单词组成的表名，使用 “_” 间隔。
表字段命名遵循如下规则：
- 全部使用小写字母命名；
- 多个单词不用下划线进行分割，如 “opentime”、“addtime”；
- 如果有必要，给常用字段加上表名首字母作为前缀；
- 避免使用关键字和保留字，但约定俗成的除外。
存储过程、触发器、event 以及视图的命名在表的命名规则基础上，遵循以下规则：
- 存储过程以 proc_ 开头，如 “proc_syn_nick_name_friend”;
- 触发器以 tri_ 开头，如 “tri_blog_user_u”;
- Event 调度以 event_ 开头，如 “event_rank”;
- 视图以 view_ 开头，如 “view_blog_user”。

3. 代码风格

3.1 缩进和空格

使用 4 个空格作为缩进，而不使用 tab 缩进。

变量赋值时，等号左右留出空格。

3.2 namespace 以及 use 声明

namespace 声明后必须插入一个空白行。所有 use 必须在 namespace 后声明。use 声明语句后必须要有一个空白行。

<?php
namespace Vendor\Package;

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

// ... 更多的 PHP 代码在这里 ...

3.3 类、属性和方法

类的开始花括号必须独占一行，结束花括号也必须在类主体后独占一行。
方法的开始花括号必须独占一行，结束花括号也必须在方法主体后独占一行。参数左括号和右括号钱 一定不可 有空格。
方法参数列表中，每个逗号后面必须要有一个空格，而逗号前面 一定不可 有空格。有默认值的参数必须放到参数列表的末尾。
所有属性和方法都必须添加访问修饰符。
需要添加 abstract 或 final 声明时，必须写在访问修饰符前，而 static 则必须写在其后。

以下例子程序简单地展示了以上大部分规范：

<?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()
    {
        // 方法的内容
    }
}

3.4 控制结构

控制结构关键词后必须有一个空格。
左括号 ( 后 一定不可 有空格，右括号 ) 前也 一定不可 有空格。
右括号 ) 与开始花括号 { 间必须有一个空格。
结束花括号 } 必须在结构体主体后单独成行。

3.5 `switch` 和 `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';
        break;
    default:
        echo 'Default case';
        break;
}

4.注释规范

代码注释应该描述为什么，而不是做什么，给代码阅读者提供最主要的信息，不能为了注释而注释。