Yii 2 核心框架 PHP 代码风格规范:PSR-2 兼容的类、命名、PHPDoc 与工具链全指南

原创2026-09-23 11:47:492,225 阅读
文章标签:后端Web框架

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 工程化习惯。

登录后查看全文
yii2