Yii 2 核心框架 PHP 代码风格规范:PSR-2 兼容的类、命名、PHPDoc 与工具链全指南
Yii 2 核心框架 PHP 代码风格规范:PSR-2 兼容的类、命名、PHPDoc 与工具链全指南
本篇指南基于 Yii 2 官方文档 docs/internals/core-code-style.md(及其俄文版 docs/internals-ru/core-code-style.md),系统讲解 Yii 2.x 核心代码与官方扩展开发所遵循的编码风格。文中每一条规则都可在本仓库 framework/ 目录的真实源码、phpcs.xml.dist 静态检查配置与 composer.json 工具链依赖中得到印证。读完本文,你将掌握一套可复制的 PHP 代码风格基线,既能用于向 Yii 2 核心提交 Pull Request 前的自查,也能作为自有 PHP 项目(特别是基于 Yii 2 的应用与扩展)的工程规范参考。
适用范围:核心与官方扩展,而非强制
需要首先明确这套规范的定位:它服务于 Yii 2.x 核心框架及其官方扩展的日常开发。如果你计划向 Yii 2 核心提交代码(Pull Request),应当尽量遵循此风格;但 Yii 团队并不强制应用开发者在自己基于 Yii 2 的项目中采用它——"Feel free to choose what suits you better"(可以自由选择更适合自己的风格)。因此本文既是一份"贡献者入场须知",也是一份"可选的工程最佳实践参考"。
配套的视图(模板)文件另有独立规范,见 docs/internals/view-code-style.md,本文聚焦 PHP 代码本身。
1. 总览:以 PSR-2 为基线的核心规则
Yii 2 整体采用与 PSR-2(PHP-FIG 编码风格建议)兼容的风格,PSR-2 适用的条款在此同样适用。在 PSR-2 之上,Yii 2 明确了以下 10 条必须遵守(MUST)的基线规则:
| 规则 | 要求 |
|---|---|
| PHP 标签 | 只允许 <?php 或 <?=,禁止 <? 等变体 |
| 文件结尾 | 文件末尾必须有换行符(空行) |
| 字符编码 | PHP 代码必须为 UTF-8 且不含 BOM |
| 缩进 | 使用 4 个空格,禁止制表符 |
| 类名 | 使用 StudlyCaps(大驼峰) |
| 类常量 | 全部大写,用下划线分隔(如 DATE_APPROVED) |
| 方法名 | 使用 camelCase(小驼峰,首字母小写) |
| 属性名 | 使用 camelCase |
| 私有属性 | 以单个下划线开头($_varName) |
| 条件分支 | 始终用 elseif,不用 else if |
从源码结构看,这套基线在仓库中通过 phpcs.xml.dist 落地:它引用了
vendor/yiisoft/yii2-coding-standards/Yii2规则集,并叠加了 SlevomatCodingStandard 的间距规则(如MethodSpacing要求方法间空 1~2 行、PropertySpacing要求注释前空行数为 0),同时对tests/*目录豁免了"单文件单类"与"私有属性下划线"两条检查(见其中exclude-pattern>tests/*的 TODO 注释)。
2. 文件级规范
2.1 PHP 标签
- PHP 代码必须使用
<?php ?>或<?=标签,禁止<?、<%等其他短标签变体; - 若文件只包含 PHP 代码(无 HTML 输出),则文件末尾不应出现闭合标签
?>,以避免意外输出空白字符破坏 HTTP 头或响应体; - 行尾不得残留多余空格(trailing whitespace);
- 任何包含 PHP 代码的文件都应使用
.php扩展名。
上述规则在仓库源码中体现得非常直观,例如 framework/yii 入口文件以 #!/usr/bin/env php 开头并使用 <?php 标签且无闭合 ?>,framework/base/Component.php 同样在文件头声明标签后直接进入命名空间与类定义。
2.2 字符编码
PHP 代码必须使用 UTF-8 且无 BOM 编码。BOM 会导致输出内容在页面头部出现不可见字符,在 HTTP 场景下可能引发"headers already sent"类错误,在纯 PHP 文件中则可能破坏类加载。
3. 类名命名
类名必须使用 StudlyCaps(大驼峰),例如 Controller、Model、ActiveRecord。这与 composer.json 中的 PSR-4 自动加载映射("yii\\": "framework/")配合,保证 yii\base\Component 对应 framework/base/Component.php,类名与文件名、命名空间与目录结构一一对应。
4. 类与接口的组织
本节"类"泛指类与接口。
- 类名使用
StudlyCase; - 左花括号
{必须独占一行,位于类名声明的下一行(Allman 风格),这一点与 PSR-2 的"同行括号"不同,是 Yii 2 的明确特色; - 每个类必须有符合 PHPDoc 规范的文档块;
- 类内代码一律缩进 4 空格;
- 一个 PHP 文件只允许一个类;
- 所有类必须使用命名空间;
- 类名必须与文件名一致,命名空间必须与目录结构一致。
/**
* Documentation
*/
class MyClass extends \yii\base\BaseObject implements MyInterface
{
// code
}
4.1 常量
类常量必须全部大写并使用下划线分隔:
<?php
class Foo
{
const VERSION = '1.0';
const DATE_APPROVED = '2012-06-01';
}
4.2 属性
属性的声明与排布是 Yii 2 风格中细节最多、也最能体现工程洁癖的部分:
- 声明公有成员时必须显式写出
public关键字; public与protected属性应声明在类顶部、所有方法之前;private属性同样建议在类顶部声明,但当某个私有属性仅被少数方法使用、与这些方法强相关时,可紧随其对应方法之前声明;- 属性按可见性升序排列:先
public,再protected,最后private;同一可见性内部无强制排序要求; - 排版要求:属性声明之间不留空行;属性区与方法区之间空两行;不同可见性分组之间空一行;
- 私有属性命名形如
$_varName(下划线前缀); - 公有成员与局部变量使用首字母小写的
$camelCase; - 使用描述性命名,尽量避免
$i、$j这类无意义变量。
标准范例:
<?php
class Foo
{
public $publicProp1;
public $publicProp2;
protected $protectedProp;
private $_privateProp;
public function someMethod()
{
// ...
}
}
这一规范在核心源码中有着大量真实样本,例如 framework/base/Component.php 中事件与行为的私有属性即采用 private $_events = [];、private $_eventWildcards = [];、private $_behaviors; 的写法(约 110~119 行),且统一声明在类顶部、方法之前,与本文规范完全吻合。
4.3 方法
- 方法名与函数名使用首字母小写的
camelCase,且名称应能自解释用途; - 类方法必须显式声明
private、protected或public之一,禁止使用var(var仅等价于public却更含糊,PSR-2 也禁止); - 方法的左花括号位于函数声明下一行(同样为 Allman 风格)。
/**
* Documentation
*/
class Foo
{
/**
* Documentation
*/
public function bar()
{
// code
return $value;
}
}
4.4 PHPDoc 类型声明
@param、@var、@property、@return 中的类型应使用小写标量类型 bool、int、string、array、null,也可以使用类名(如 Model、ActiveRecord);类型化数组写作 ClassName[](如 Post[])。此外,英文原版 docs/internals/core-code-style.md 还补充了三条写作要求:PHPDoc 第一行必须描述方法用途;判断类方法(如 isActive、hasClass)的第一行应以 "Checks whether" 开头;@return 必须明确描述返回值内容。例如:
/**
* Checks whether the IP is in subnet range
*
* @param string $ip an IPv4 or IPv6 address
* @param int $cidr the CIDR length
* @param string $range subnet in CIDR format e.g. `10.0.0.0/8` or `2001:af::/64`
* @return bool whether the IP is in subnet range
*/
private function inRange($ip, $cidr, $range)
{
// ...
}
4.5 构造函数
必须使用 __construct,禁止 PHP 4 时代的"类名同名构造函数"旧写法。
5. PHP 语言使用规范
5.1 类型与值
- 所有 PHP 类型与关键字一律小写,包括
true、false、null、array(禁止TRUE、False、NULL等写法); - 改变已有变量的类型属于不良实践,应尽量避免:
public function save(Transaction $transaction, $argument2 = 100)
{
$transaction = new Connection; // 不好:改变了参数类型
$argument2 = 200; // 好:仅重新赋值
}
5.2 字符串
- 字符串不含变量与单引号时,使用单引号;
- 字符串内含单引号时,改用双引号以避免多余转义;
- 变量插值:允许
"Hello $username!"与"Hello {$username}!"两种形式,禁止"Hello ${username}!"(${}语法已被 PHP 8.2 废弃,项目规范更是明确禁止); - 拼接:
.连接符两侧必须留空格,如$name = 'Yii' . ' Framework';;长字符串拼接采用"每行一个片段、运算符开头"的格式:
$sql = "SELECT *"
. "FROM `post` "
. "WHERE `id` = 121 ";
5.3 数组
统一使用 PHP 5.4 引入的短数组语法 [](禁止 array() 长语法):
- 索引数组:禁止使用负数索引;单行放得下就单行,元素过多则每行一组、结尾保留逗号:
$arr = [3, 14, 15, 'Yii', 'Framework'];
$arr = [
3, 14, 15,
92, 6, $test,
'Yii', 'Framework',
];
- 关联数组:
=>两侧空格、键值对齐,最后一个元素后保留逗号:
$config = [
'name' => 'Yii',
'options' => ['usePHP' => true],
];
5.4 控制结构
控制结构(if、for、foreach、while 等)遵循 PSR-2 风格:
- 左括号前一个空格,右括号后一个空格(即
if (与) {); - 括号内运算符两侧留空格;
- 左花括号与条件同行,右花括号独占一行(与类/方法的 Allman 风格形成对照);
- 单行语句也必须使用花括号,禁止无括号的单语句分支:
if ($event === null) {
return new Event();
}
if ($event instanceof CoolEvent) {
return $event->instance();
}
return null;
// 以下写法不允许:
if (!$model && null === $event)
throw new Exception('test');
- 避免
return后的else:优先使用卫语句(guard clauses)提前返回,减少嵌套层级:
// 不推荐
$result = $this->getResult();
if (empty($result)) {
return true;
} else {
// 后续计算
}
// 推荐
$result = $this->getResult();
if (empty($result)) {
return true;
}
// 后续计算
switch的标准格式:case缩进 4 空格、case内部语句再缩进、case之间空一行、default收尾:
switch ($this->phpType) {
case 'string':
$a = (string) $value;
break;
case 'integer':
case 'int':
$a = (int) $value;
break;
case 'boolean':
$a = (bool) $value;
break;
default:
$a = null;
}
5.5 函数调用
函数名与左括号之间不留空格;多参数用逗号加空格分隔;数组实参可整体内联或换行展开:
doIt(2, 3);
doIt(['a' => 'b']);
doIt('a', [
'a' => 'b',
'c' => 'd',
]);
5.6 匿名函数(lambda)
function / use 关键字与左括号之间必须留空格(这一点常被忽略):
// 正确
$n = 100;
$sum = array_reduce($numbers, function ($r, $x) use ($n) {
$this->doMagic();
$r += $x * $n;
return $r;
});
// 错误
$mul = array_reduce($numbers, function($r, $x) use($n) {
...
});
6. 文档与 PHPDoc 规范
"无文档的代码不允许提交"(Code without documentation is not allowed)——文档规范在 Yii 2 中与代码风格同等重要。
- PHPDoc 语法以 phpDoc 官方规范为准;
- 每个类文件必须包含文件级 docblock(文件头部)与类级 docblock(类声明正上方);
- 方法无返回值时不必写
@return; - 所有继承自
yii\base\BaseObject的类的虚拟属性(由 getter/setter 定义的属性)必须在类级 docblock 中用@property标注。
6.1 文件级 docblock
标准模板如下(仓库中每个框架源文件都以此开头,例如 framework/base/BaseObject.php 头部):
<?php
/**
* @link https://www.yiiframework.com/
* @copyright Copyright (c) 2008 Yii Software LLC
* @license https://www.yiiframework.com/license/
*/
6.2 类级 docblock
/**
* Component is the base class that provides the *property*, *event* and *behavior* features.
*
* @include @yii/docs/base-Component.md
*
* @author Qiang Xue <qiang.xue@gmail.com>
* @since 2.0
*/
class Component extends \yii\base\BaseObject
6.3 方法级 docblock 与 @property 的配合
对于 BaseObject 派生类中的虚拟属性,其 @property 注解可通过在构建目录执行 ./build php-doc 自动从对应 getter 的 @return 或 setter 的 @param 生成;当 getter/setter 引入的属性说明与 @return 不一致时,可手动添加额外 @property 标签补充说明:
<?php
/**
* Returns the errors for all attribute or a single attribute.
* @param string $attribute attribute name. Use null to retrieve errors for all attributes.
* @property array An array of errors for all attributes. Empty array is returned if no error.
* The result is a two-dimensional array. See [[getErrors()]] for detailed description.
* @return array errors for all attributes or the specified attribute. Empty array is returned if no error.
* Note that when returning errors for all attributes, the result is a two-dimensional array, like the following:
* ...
*/
public function getErrors($attribute = null)
这正是 Yii 2 文档系统(docs/guide 目录的官方指南即由此生态生成)保持 API 文档与源码同步的机制:虚拟属性在 IDE 与生成文档中都能以真实属性的形态出现。以 framework/base/BaseObject.php 的 getLabel()/setLabel() 为例,private $_label 配合公开 getter/setter 即构成 label 虚拟属性。
6.4 方法级 docblock 完整示例
/**
* Returns the list of attached event handlers for an event.
* You may manipulate the returned [[Vector]] object by adding or removing handlers.
* For example,
*
* ```
* $component->getEventHandlers($eventName)->insertAt(0, $eventHandler);
* ```
*
* @param string $name the event name
* @return Vector list of attached event handlers for the event
* @throws Exception if the event is not defined
*/
public function getEventHandlers($name)
{
if (!isset($this->_e[$name])) {
$this->_e[$name] = new Vector;
}
$this->ensureBehaviors();
return $this->_e[$name];
}
注意上例同时演示了 4.3 节"方法括号独占下一行"与 4.2 节"私有属性 $_e 下划线前缀"在真实核心代码中的落地。
6.5 PHPDoc 专用 Markdown 标记语法
Yii 2 在 PHPDoc 中使用了一套 [[...]] 交叉引用标记,用于在 API 文档中自动生成类、方法、属性之间的链接:
| 写法 | 含义 |
|---|---|
[[canSetProperty]] |
链接到本类的 canSetProperty 方法或属性 |
[[Component::canSetProperty]] |
链接到同命名空间下 Component 类的 canSetProperty 方法 |
[[yii\base\Component::canSetProperty]] |
链接到 yii\base 命名空间下 Component 类的该方法 |
[[Component]] |
链接到同命名空间的 Component 类,也可显式加命名空间 |
自定义链接文字使用管道符:[[header|header cell]]——| 前为类/方法/属性引用,| 后为显示文本。
同时支持链接到官方指南(Guide)文件:
link to guide
link to guide
6.6 代码示例与注释
- docblock 中的代码示例使用 Markdown 代码围栏,但不要指定语言(
```而非```php),因为指定语言可能破坏部分 IDE 的渲染:
/**
* Correct code example:
*
* ```
* $object->doMagic();
* ```
*/
function doMagic()
{
}
/**
* Incorrect code example:
*
* ```php
* $object->doMagic();
* ```
*/
function doMagic()
{
}
- 单行注释必须使用
//(禁止#),且应独占一行。
7. 附加规则:经验沉淀
7.1 === [] 与 empty()
能用 empty() 就用 empty()(它同时处理未定义变量与空值,语义更安全)。
7.2 多个返回点
当条件嵌套开始变得混乱时,尽早 return(卫语句风格)。短方法则不受此限制。
7.3 self 与 static
默认始终使用 static(支持后期静态绑定,便于继承覆写),仅以下例外:
- 访问常量必须用
self:self::MY_CONSTANT; - 访问私有静态属性必须用
self:self::$_events; - 递归调用当前类自身实现(而非子类实现)时,允许用
self。
7.4 "不做某事"的取值约定
用于配置组件"关闭某功能"的属性,其禁用值必须是 false;不要把 null、'' 或 [] 当作"关闭"语义来依赖。这一约定从规范层面杜绝了"空值即禁用"的隐式耦合。
7.5 目录与命名空间命名
- 一律小写;
- 表示"对象集合"的名词用复数(如
validators); - 表示"功能/特性"的名称用单数(如
web); - 优先使用单词语命名空间;
- 实在无法单词表达时,才使用 camelCase。
这套命名习惯直接映射到本仓库的目录结构:framework/validators/(复数)、framework/web/、framework/db/(单数功能域)等 framework 目录即为其真实样板。
8. 规范在仓库中的工程化落地
这套编码风格并非停留在文档层面,而是被工具链强制执行:
- phpcs.xml.dist:仓库根目录的 PHP_CodeSniffer 配置,引用
vendor/yiisoft/yii2-coding-standards/Yii2规则集,叠加 SlevomatCodingStandard 的TraitUseSpacing、ConstantSpacing、PropertySpacing、MethodSpacing等间距规则;检查范围覆盖build、framework、tests目录,并对迁移脚本(framework/*/migrations)、视图文件(framework/views/*)等做了排除;测试目录豁免了"单文件单类"与"私有属性下划线"两条检查(文件中以<!-- TODO: fix errors -->标注,说明是待修复的历史债务而非推荐写法); - composer.json:
require-dev中声明了yiisoft/yii2-coding-standards: ^3.0、slevomat/coding-standard: ^8.31、friendsofphp/php-cs-fixer: ^3.95等代码质量工具,并预置了可直接运行的脚本命令:composer cs(运行./vendor/bin/phpcs && ./vendor/bin/php-cs-fixer check做静态检查)、composer cs-fix(运行./vendor/bin/phpcbf && ./vendor/bin/php-cs-fixer fix自动修复)、composer static(PHPStan 静态分析)、composer rector(Rector 重构); - 真实源码样板:framework/base/Component.php、framework/base/BaseObject.php、framework/yii 分别是"类级 docblock + Allman 花括号 + 私有属性下划线 + 4 空格缩进"与"文件级 docblock + 无闭合标签 + 变量插值"等规则的最佳示范文件。
结语
Yii 2 的核心代码风格是一份"PSR-2 兼容 + 团队取舍"的完整方案:它在 PSR-2 基础上强化了 Allman 风格花括号、属性可见性排序、私有属性下划线、self/static 边界、PHPDoc 交叉引用标记等细节,并通过 phpcs、php-cs-fixer、PHPStan 与 yiisoft/yii2-coding-standards 工具链在 phpcs.xml.dist 与 composer.json 中强制落地。无论你是准备向 Yii 2 核心提交首个 Pull Request,还是希望在自有 PHP 团队中建立一套"有文档、有工具、有源码样板"的编码基线,都可以直接从本仓库的规范文档与配置出发——复制这份风格,就是复制一个久经考验的 PHP 工程化习惯。