Yii 2 核心框架代码风格指南:PSR-2 兼容的工程化 PHP 编码规范全解

原创2026-09-23 17:43:551,831 阅读
文章标签:后端Web框架

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 目录下的相关文档。

登录后查看全文
yii2