Yii 2 核心框架代码风格指南:PSR-2 兼容的工程化 PHP 编码规范全解
Yii 2 核心框架代码风格指南:PSR-2 兼容的工程化 PHP 编码规范全解
本指南以 Yii 2 官方核心开发规范 core-code-style.md(及对应的日文版 core-code-style.md)为骨架,系统梳理 Yii 2.x 核心框架与官方扩展的代码风格要求。无论你是想为 Yii 2 提交 Pull Request 的贡献者,还是希望在自有 PHP 项目中落地高质量工程规范的开发者,读完本文你将掌握:文件与编码的基础约束、类/属性/方法的命名与组织规则、PHPDoc 文档块的完整写法、PHP 语法层面的风格细节,以及如何借助仓库中的 phpcs.xml.dist 与 PHP_CodeSniffer 将这些规范自动化落地。
Yii 2 的代码风格以 PSR-2 为基底,在其之上叠加了 Yii 特有的约定(如私有属性以下划线开头、@property 虚拟属性文档、static 优先于 self 等),并经过十余年的沉淀形成了一套高度自洽、可机器校验的规范。官方并不强制你在自己的应用中使用这套风格——规范原文明确写道:"我们不强求你为自己的应用使用这套代码风格,请自由选择更适合你的风格",但它对想要向核心仓库提交代码的贡献者是硬性要求。本文结合 framework 目录下的真实源码逐一印证每条规则的实际落地形态。
1. 总体概览:PSR-2 兼容 + Yii 特有约定
Yii 2 核心团队在开发 Yii 2.x 核心与官方扩展时使用统一的代码风格,整体与 PHP-FIG 的 PSR-2 兼容——凡是 PSR-2 适用的规则,同样适用于 Yii 的代码风格。在此基础上,规范开篇用一条清单概括了所有硬性要求(MUST):
- 文件必须使用
<?php或<?=标签; - 文件末尾必须有换行符;
- PHP 代码文件必须使用无 BOM 的 UTF-8 编码;
- 缩进必须使用 4 个空格,禁止使用 Tab;
- 类名必须使用
StudlyCaps(大驼峰); - 类常量必须使用大写字母 + 下划线分隔;
- 方法名必须使用
camelCase(小驼峰); - 属性名必须使用
camelCase; - 私有属性必须以单个下划线开头;
- 始终使用
elseif,不要使用else if。
这条清单是整篇规范的"速查表",后面所有章节都是对它的展开解释。值得强调的是"私有属性下划线前缀"与 PSR-2 的差异点——PSR 系列规范刻意回避了成员命名中的前缀约定,而 Yii 出于与父类属性区分、以及 IDE 提示可读性的考虑,明确要求 private $_varName 这种写法。
2. 文件级规范
2.1 PHP 标签与文件收尾
- PHP 代码只能使用
<?php ?>或<?=短输出标签,禁止使用<?等其他变体; - 如果文件只包含 PHP 代码,则不应包含末尾的
?>(避免意外输出空白字符污染响应流); - 行尾不得添加多余空白;
- 任何包含 PHP 代码的文件应以
.php扩展名结尾。
从仓库实测看,framework/ 目录下所有 49 个 base/ 类文件均以 <?php 开头、以单个换行结尾且无 ?> 收尾,正是该规则的直接体现。
2.2 字符编码
PHP 代码必须使用无 BOM 的 UTF-8。BOM(Byte Order Mark)会导致 PHP 在输出前注入不可见字符,破坏 HTTP 响应头或产生 "headers already sent" 错误,因此被严格禁止。
3. 类名规范
类名必须使用 StudlyCaps(大驼峰),例如 Controller、Model。同时类名应与文件名一致、类所属命名空间应与目录结构一致。在 Yii 2 中,yii\base\Controller 位于 framework/base/,yii\db\ActiveRecord 位于 framework/db/,类名、文件名、目录、命名空间四者一一对应,这正是 PSR-4 自动加载得以高效工作的前提。
4. 类内部组织规范
这里的"类"泛指所有类与接口。核心规则如下:
- 类名使用
StudlyCase; - 左大括号永远写在类名所在行的下一行(与 PSR-2 一致);
- 每个类必须有符合 PHPDoc 规范的文档块;
- 类内所有代码缩进 4 个空格;
- 一个 PHP 文件只能有一个类;
- 所有类都必须属于某个命名空间;
- 类名匹配文件名,命名空间匹配目录结构。
<?php
/**
* Documentation
*/
class MyClass extends \yii\base\BaseObject implements MyInterface
{
// code
}
注意示例中 extends \yii\base\BaseObject 使用了带前导反斜杠的完全限定类名(FQCN),这是 Yii 代码中常见写法,用于避免 use 语句歧义并明确类的绝对位置。
4.1 常量
类常量必须全部大写并用下划线分隔单词:
<?php
class Foo
{
const VERSION = '1.0';
const DATE_APPROVED = '2012-06-01';
}
仓库实测:在 framework/base/Model.php 中可见 public const SCENARIO_DEFAULT = 'default'; 以及 EVENT_BEFORE_VALIDATE、EVENT_AFTER_VALIDATE 等常量,全部遵循大写 + 下划线命名;同时该文件也展示了"常量声明附带事件说明注释"的进阶写法,用 @event 标签描述事件在何时触发。
4.2 属性
属性声明规则是 Yii 风格中最具辨识度的部分:
- 声明 public 成员时必须显式写出
public关键字; - public 和 protected 变量应声明在类的开头、所有方法之前;private 变量通常也在开头,但如果它只与一小部分方法相关,可以紧贴相关方法群之前声明;
- 属性声明顺序按可见性从 public 到 protected 再到 private 排列;同一可见性内部无严格顺序要求;
- 可读性要求:属性声明之间不空行;属性声明块与方法声明块之间空两行;不同可见性分组之间空一行;
- 私有变量命名为
$_varName;public 成员和独立变量用首字母小写的$camelCase; - 使用描述性名称,尽量不用
$i、$j这类无意义变量。
<?php
class Foo
{
public $publicProp1;
public $publicProp2;
protected $protectedProp;
private $_privateProp;
public function someMethod()
{
// ...
}
}
上述布局在仓库中有大量真实样例。例如 framework/base/Component.php 中,$_events、$_eventWildcards、$_behaviors 三个私有属性集中在类头部声明,全部采用 $_ 前缀 + camelCase 命名,且每个属性上方都配有 @var 类型注解:
class Component extends BaseObject
{
/**
* @var array the attached event handlers (event name => handlers)
*/
private $_events = [];
/**
* @var array the event handlers attached for wildcard patterns (event name wildcard => handlers)
* @since 2.0.14
*/
private $_eventWildcards = [];
/**
* @var Behavior<static>[]|null the attached behaviors (behavior name => behavior). ...
*/
private $_behaviors;
4.3 方法
- 函数与方法使用首字母小写的
camelCase命名; - 方法名应自描述其用途;
- 类方法必须显式声明
private、protected或public可见性,不允许使用var; - 函数左大括号位于函数声明行的下一行(与 PSR-2 的函数规则一致,注意与 if/for 等控制语句"大括号同行"形成对比)。
<?php
/**
* Documentation
*/
class Foo
{
/**
* Documentation
*/
public function bar()
{
// code
return $value;
}
}
4.4 PHPDoc 文档块
Yii 对 PHPDoc 有非常具体的要求,这直接决定了官方 API 文档(yiiframework.com 上的类参考)的质量:
@param、@var、@property、@return的类型必须使用bool、int、string、array、null等小写标量类型,也可以使用Model、ActiveRecord等类名;- 类型化数组使用
ClassName[]语法; - 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. PHPDoc 的进阶文档约定
5.1 @property 与虚拟属性文档
Yii 2 大量使用 __get()/__set() 魔术方法实现"虚拟属性"(例如 Component 的属性特性、ActiveRecord 的关系属性)。规范要求:
- 所有继承自
yii\base\BaseObject的类的虚拟属性,必须在类级文档块中用@property标签登记; - 这些注解可以通过在 build 目录执行
./build php-doc命令,从对应 getter 的@return或 setter 的@param自动生成; - 当希望给出与
@return描述不同的说明时,可在 getter/setter 上显式添加@property标签覆盖。
规范给出的完整示例(这正是 framework/base/Model.php 中 getErrors() 方法的真实文档形态):
<?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)
对照源码可见,getErrors() 实际返回的是"属性名 => 错误数组"的二维结构($this->_errors 为 null 时返回空数组),文档中的 @property 与 @return 分别从"属性视角"与"方法视角"描述同一数据,这正是规范要表达的"两条描述路径"。
5.2 文件级、类级、方法级文档块
文件级 docblock(每个类文件顶部):
<?php
/**
* @link https://www.yiiframework.com/
* @copyright Copyright (c) 2008 Yii Software LLC
* @license https://www.yiiframework.com/license/
*/
类级 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
注意 @include 标签用于在文档生成时嵌入独立的 Markdown 说明文件,这是 Yii 文档构建系统(./build php-doc)支持的自定义标签;@author 与 @since 则记录作者与引入版本。在 framework/base/Component.php 中还能看到 @phpstan-property-read、@psalm-property-read 等静态分析注解,说明 Yii 2 在核心规范之外,还结合 PHPStan/Psalm 生态进一步丰富了属性文档。
方法级 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];
}
在 framework/base/Component.php 的实际实现中,事件处理器被存放在 private $_events = [] 中,2.0.14 起又增加了 $_eventWildcards 用于通配符事件,私有属性前缀规则再次得到印证。
5.3 文档中的 Markdown 与交叉链接
PHPDoc 注释内的排版使用 Markdown(如上例中的行内代码与代码块)。Yii 文档系统还支持专有的交叉引用语法:
| 语法 | 生成的链接目标 |
|---|---|
[[canSetProperty]] |
同类的 canSetProperty 方法或属性 |
[[Component::canSetProperty]] |
同命名空间内 Component 类的 canSetProperty 方法 |
[[yii\base\Component::canSetProperty]] |
yii\base 命名空间 Component 类的 canSetProperty 方法 |
[[Component]] |
同命名空间内的 Component 类 |
若想为链接自定义显示文本,使用 [[引用|显示文本]] 语法,| 前是类/方法/属性引用,| 后是链接标签:
... as displayed in the [[header|header cell]].
还可以用 guide: 前缀链接到用户指南:
link to guide
link to guide
5.4 文档中的代码示例与行内注释
- 代码示例应使用 Markdown 语法,但不应指定语言标识(如
```php),因为指定语言可能在某些 IDE 中导致渲染异常; - 单行注释必须使用
//而非#; - 单行注释应独占一行。
6. PHP 语法使用规范
6.1 类型
- 所有 PHP 类型与值使用小写:
true、false、null、array; - 改变已有变量的类型被认为是坏实践:
public function save(Transaction $transaction, $argument2 = 100)
{
$transaction = new Connection; // bad
$argument2 = 200; // good
}
6.2 字符串
- 若字符串不含变量或单引号,使用单引号:
$str = 'Like this.'; - 若字符串内含单引号,可改用双引号避免多余转义;
- 变量插值允许
"Hello $username!"与"Hello {$username}!",禁止"Hello ${username}!"; - 字符串拼接时点号两侧加空格:
$name = 'Yii' . ' Framework'; - 长字符串拼接的格式(后续行以 4 空格 +
.开头,且点号在行首便于对齐):
$sql = "SELECT *"
. "FROM `post` "
. "WHERE `id` = 121 ";
6.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],
];
6.4 控制语句
- 条件两侧(括号前与括号后)各有一个空格;
- 括号内运算符两侧用空格分隔;
- 左大括号与语句同行(区别于类/函数的换行式大括号);
- 右大括号独占一行;
- 单行语句也必须使用大括号:
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)提前返回。规范原文的示例——if (empty($result)) { return true; } else { ... }应重构为先返回、再处理剩余逻辑——正是降低嵌套深度、提升可读性的经典手法。
switch 语句的标准格式:case 与 default 与 switch 左括号对齐,break 缩进一层:
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;
}
6.5 函数调用
函数调用时参数列表的括号紧贴函数名,无空格:
doIt(2, 3);
doIt(['a' => 'b']);
doIt('a', [
'a' => 'b',
'c' => 'd',
]);
6.6 匿名函数(lambda)
function、use 关键字与左括号之间必须有一个空格:
// 好
$n = 100;
$sum = array_reduce($numbers, function ($r, $x) use ($n) {
$this->doMagic();
$r += $x * $n;
return $r;
});
// 坏:function( 与 use( 都缺少空格
$n = 100;
$mul = array_reduce($numbers, function($r, $x) use($n) {
$this->doMagic();
$r *= $x * $n;
return $r;
});
7. 附加规则:Yii 特有的工程决策
7.1 === [] 与 empty()
能使用 empty() 的地方尽量使用 empty(),它同时覆盖 null、''、[]、0、false 等"空"情形,语义更简洁。
7.2 多个返回点
当条件嵌套开始变得杂乱时,尽早 return;方法很短时则无所谓。这与 6.4 节的卫语句精神一脉相承。
7.3 self 与 static 的选择
默认始终使用 static(延迟静态绑定),仅以下三种例外必须使用 self:
- 访问常量:
self::MY_CONSTANT; - 访问 private 静态属性:
self::$_events; - 递归调用中需要调用"当前类的实现"而非扩展类实现时。
从源码印证:在 framework/base/Model.php 中,private $_scenario = self::SCENARIO_DEFAULT; 正是"用 self 访问类常量"的标准写法——即便访问的是自身常量,也统一用 self 而非 static。
7.4 "不做某事"的开关值约定
允许配置组件"不执行某功能"的属性,应接受 false 作为关闭值;不得假定 null、'' 或 [] 表示关闭。这是一条重要的 API 设计约定:关闭开关的"唯一假值"就是 false,避免调用方与实现方对"空值即关闭"产生歧义。
7.5 目录与命名空间命名
- 使用小写;
- 表示对象集合的名词用复数(如
validators); - 表示功能/特性的名称用单数(如
web); - 尽量使用单词命名空间;
- 单个单词不合适时,退而使用 camelCase。
对照 framework/ 目录:validators/(对象集合,复数)、web/、db/、i18n/、mail/、rest/(功能域,单数),完全吻合上述规则。
8. 规范的自动化落地:PHP_CodeSniffer 与 phpcs.xml.dist
规范并非停留在纸面,仓库根目录的 phpcs.xml.dist 是 PHP_CodeSniffer 的可直接使用的规则集配置文件,它引用了社区维护的 vendor/yiisoft/yii2-coding-standards/Yii2 规则集(PHP_CodeSniffer 的 CodeSniffer 配置可在 yiisoft/yii2-coding-standards 仓库获取),并在此基础上做了细粒度定制:
- 类间距控制:通过
SlevomatCodingStandard系列规则约束 trait 使用、常量、属性、方法之间的空行数(方法间 1~2 空行等); - 测试目录豁免:
PSR1.Classes.ClassDeclaration.MultipleClasses(单文件多类)与Squiz.NamingConventions.ValidVariableName.PrivateNoUnderscore(私有属性下划线)等规则对tests/*排除,因为测试数据文件需要更宽松的形态; - 副作用豁免:
PSR1.Files.SideEffects.FoundWithSymbols对tests/bootstrap.php与tests/framework/web/UserTest.php放行; - 扫描范围:默认检查
build、framework、tests三个目录,并排除各模块的migrations/*、framework/views/*、tests/data/views/*、tests/runtime/*、tests/js/*等不宜强审的位置; - 输出体验:启用进度显示(
-p)、错误码显示(-s)、彩色输出(colors)与相对路径基准(basepath)。
这意味着核心开发者可以在克隆仓库并安装依赖后,直接运行类似 vendor/bin/phpcs 的命令对 framework/ 目录做全量风格校验;CI 环境同样依赖该配置保证每次合并前代码风格达标。
9. 结语:把 Yii 的工程纪律迁移到你的项目
Yii 2 核心代码风格的价值远超"贡献者须知"本身:它是一份经过大规模生产代码验证的 PHP 工程化清单。你可以直接采用其中的可迁移部分——4 空格缩进、无 BOM UTF-8、私有属性下划线、static 优先、卫语句式提前返回、empty() 优先、复数/单数目录命名、false 作为唯一关闭值——并结合 phpcs.xml.dist 的思路为自有项目搭建 CodeSniffer 检查。文档中反复强调的一个立场值得铭记:风格是手段而非目的,"请自由选择更适合你的风格",但一旦选定,就要像 Yii 核心那样用工具与 CI 把它固化下来,让团队协作建立在可机器校验的共识之上。更多 Yii 内部工程实践(自动化、版本分支、发布流程等)可继续阅读 docs/internals 目录下的相关文档。