PHP 编码规范

当多人协作编码时，一份共同遵守的编码规范必不可少。它有利于阅读和编写代码，既可以提高新成员熟悉代码的效率，也可以提高老成员编码的效率。

如果以下规范与框架规范冲突，则以框架规范为准。

本文档中使用了大量的“能愿动词”，说明如下：

必须：绝对，严格遵循，请照做，无条件遵守；
一定不能：禁令，严令禁止；
应该：强烈建议这样做，但不强求；
不该：强烈不建议这样做，但不强求;
可以：更多的选择。

1. 命名

变量名、类的属性名必须使用小驼峰形式（如 $varName）。

常量名中所有字母必须大写，单词间应该以下划线分隔。

文件夹名所有字母应该使用小写字母，单词间应该以下划线分隔。

类名必须使用大驼峰形式（如 ClassName）。

定义类的文件名应该与类名相同，或者包含类名，同样应该使用大驼峰形式。

方法名必须使用小驼峰形式。

PHP 的关键字必须全部小写。

系统常量（true, false, null）必须小写。

2. 基础规范

代码必须使用 4 个空格符而不是 Tab 键进行缩进。

每行代码的字符数应该控制在 120 个以内。

类和方法的起始花括号（{）必须在声明后自成一行，结束花括号（}）必须在代码主体后自成一行。

类的属性和方法必须添加访问修饰符（private, protected, public），abstract 和 final 必须写在访问修饰符之前，而 static 必须写在访问修饰符之后。

<?php

abstract class ClassName
{
    protected static $fooVar;

    abstract protected function baz();

    final public static function barShow($a, $b = null)
    {
        // 方法主体
    }
}

赋值符号（=）的左右必须有且只有一个空格。

取反符号（!）后必须有一个空格。

纯 PHP 代码文件应该省略末尾的结束标签（?>）。

非空行后不该有多余的空格。

每行 一定不能 存在多条语句。

文件应该以一个空白行作为结束。

字符串应该使用单引号。

3. 编码风格

3.1 类、属性和方法

关键词 extends 和 implements 必须写在类名称的同一行。

<?php

class ClassName extends ParentClass implements ImplementName
{
    // 这里面是常量、属性、类方法
}

implements 的继承列表也可以分成多行，但每个继承接口名称都必须分开独立成行，包括第一个。

<?php

class ClassName extends ParentClass implements
    ImplementName1,
    ImplementName2,
    ImplementName3
{
    // 这里面是常量、属性、类方法
}

每个属性都必须添加访问修饰符。
一定不能 使用关键字 var 声明一个属性。
每条语句 一定不能 定义超过一个属性。
不该使用下划线作为前缀，来区分属性是 protected 或 private。

所有方法都必须添加访问修饰符。
不该使用下划线作为前缀，来区分方法是 protected 或 private。
方法名称后 一定不能 有空格符，参数左括号后和右括号前 一定不能 有空格。
参数列表中，每个逗号后面必须要有一个空格，而逗号前面 一定不能 有空格。
有默认值的参数，必须放到参数列表的末尾。

<?php

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

訪問修飾符必須按最小訪問原則。例如只在本類中使用的方法，必須使用 private；當該方法需要被外部訪問時，再改為 public。

3.2 控制结构

控制结构的关键字（如 if）后必须有一个空格，而调用方法、函数的左括号前 一定不能 有空格。
控制结构的起始花括号应该写在声明的同一行，而最后一个结束花括号必须在主体后自成一行。
控制结构的左括号后，右括号前 一定不能 有空格。
结构体主体必须要有一次缩进。
注意，控制结构的花括号并不总是单独成行。

if 条件语句

<?php

if ($expr1) {
    // if 代码块
} elseif ($expr2) {
    // elseif 代码块
} else {
    // else 代码块
}

应该使用关键词 elseif 代替所有 else if 。
主体部分，必须使用花括号括起来，即使只有一句。

switch 语句

<?php

switch ($expr) {
    case 0:
        echo '第一种情况, 带有 break';
        break;
    case 1:
        echo '第二种情况';
        // no break
    case 2:
    case 3:
    case 4:
        echo '第三种情况, 直接 return';
        return;
    default:
        echo '默认情况';
        break;
}

case 语句必须相对 switch 进行一次缩进，而 break 语句以及 case 内的其它语句都必须相对 case 进行一次缩进。
如果存在非空的 case 直穿语句，主体中必须有类似 // no break 的注释。

while 和 do...while 语句

<?php

while ($expr) {
    // 循环主体
}

do {
    // 循环主体
} while ($expr);

for 语句

<?php

for ($i = 0; $i < 10; $i++) {
    // 循环主体
}

foreach 语句

<?php

foreach ($iterable as $key => $value) {
    // 循环主体
}

try...catch 语句

<?php

try {
    // 主体代码
} catch (FirstExceptionType $e) {
    // 异常处理代码
} catch (OtherExceptionType $e) {
    // 异常处理代码
}

3.3 闭包

关键词 function 后以及关键词 use 的前后都必须要有一个空格。
开始花括号必须写在声明的同一行，结束花括号必须紧跟主体结束的下一行。

<?php

$closureWithArgs = function ($arg1, $arg2) {
    // 主体
};

$closureWithArgsAndVars = function ($arg1, $arg2) use ($var1, $var2) {
    // 主体
};

参数列表以及变量列表可以分成多行，这样，包括第一个在内的每个参数或变量都必须单独成行，而列表的右括号与闭包的开始花括号必须放在同一行。

<?php

$longArgs_longVars = function (
    $longArgument,
    $longerArgument,
    $muchLongerArgument
) use (
    $longVar1,
    $longerVar2,
    $muchLongerVar3
) {
   // 代码主体
};

3.4 命名空间

namespace 声明后必须插入一个空白行。
所有 use 必须在 namespace 后声明。
每条 use 声明语句必须只有一个 use 关键词。
use 声明语句块后必须要有一个空白行。

<?php
namespace Vendor\Package;

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

// 更多的代码...

3.5 注释与空行

单行注释应该放在行末，与代码之间应该保留 2 个空格，而较长的注释，应该放在相应代码的上一行；注释符号（//）与注释之间应该保留 1 个空格。

较复杂的代码，应该详细说明。

<?php

/**
 * 算法标题
 *
 * 首先，调用...取得...数据
 * 其次，对...数据进行循环处理，得到...
 * 最后，按...格式输出数据
 */

清楚明了的代码不该增加注释：

<?php

$criteria = new CDbCriteria;
// 仅获取id,parentid字段
$criteria->select = 'id,parentid';
// 排除已删除节点
$criteria->addCondition('is_delete=0');

$list = $modelClassName::model()->findAll($criteria);

代码块之间应该用一个空行分隔，如类的方法之间使用一个空行分隔。

附0 开发工具推荐

PhpStorm
PHPDesigner
PhpED

附1 Git 使用

提交时简明扼要地描述所变更代码的主要内容
至少形成一个基本逻辑再提交
不相关的修改应该分开提交
不必要的修改不要提交（如调试时多加了个空行，提交时查看变更内容可避免）
开发周期较长（超过一周）的需求应该新建一个分支

提交信息格式：
修改Bug：BF(###): xxxxxxx
完成需求：PR(###): xxxxxxx

参考文档

PSR - PHP标准规范

2017年2月