本文介绍如何通过自定义 PHPCS Sniff 实现对指定目录下 PHP 类的继承关系校验，确保所有 src/Controller/CP/ 目录中的控制器类必须继承 AbstractCPController，否则触发静态分析错误。
本文介绍如何通过自定义 phpcs sniff 实现对指定目录下 php 类的继承关系校验，确保所有 `src/controller/cp/` 目录中的控制器类必须继承 `abstractcpcontroller`，否则触发静态分析错误。
PHP_CodeSniffer（PHPCS）本身不提供开箱即用的“强制继承某类”规则，但其高度可扩展的 Sniff 机制允许我们精准解析类定义结构，并在语法层面验证 extends 关键字后的父类名。以下是一个生产可用的自定义 Sniff 示例，专用于约束控制器类的继承链。
核心实现逻辑
该 Sniff 在扫描到 T_CLASS 令牌时，执行以下步骤：
- 定位类名：提取当前类的名称，跳过 AbstractCPController 自身（避免误报）；
- 查找 extends 位置：在类声明的 { 前范围内搜索 T_EXTENDS 令牌；
- 解析父类全名：遍历 extends 后的连续 T_STRING 和 T_NS_SEPARATOR 令牌，拼接出完整的父类名（支持命名空间，如 App\Controller\CP\AbstractCPController）；
- 匹配校验：检查是否以 AbstractCPController 结尾（str_ends_with()），兼容带命名空间的继承；
- 报错提示：若未匹配，则调用 $file->addError() 报告违规。
✅ 注意：本 Sniff 不依赖文件路径过滤（如仅检查 src/Controller/CP/），实际使用中建议配合 PHPCS 的 <rule> 配置或 ruleset.xml 中的 <exclude-pattern> / <include-pattern> 进行目录级作用域控制，例如：
<rule ref="MyCodingStandard.Classes.ClassInheritance"> <include-pattern>*/src/Controller/CP/*</include-pattern> </rule>
完整 Sniff 代码（已优化可读性与健壮性）
<?php
declare(strict_types=1);
namespace MyCodingStandard\Sniffs\Classes;
use PHP_CodeSniffer\Fixer;
use PHP_CodeSniffer\Files\File;
use PHP_CodeSniffer\Sniffs\Sniff;
use PHP_CodeSniffer\Util\Tokens;
final class ClassInheritanceSniff implements Sniff
{
public function register(): array
{
return [T_CLASS];
}
public function process(File $file, $position): void
{
$tokens = $file->getTokens();
// 提取类名
$classNamePos = $file->findNext(T_STRING, $position + 1);
if ($classNamePos === false) {
return;
}
$className = $tokens[$classNamePos]['content'];
// 跳过基类自身
if ($className === 'AbstractCPController') {
return;
}
// 查找 { 位置（类体开始）
$curlyOpen = $file->findNext(T_OPEN_CURLY_BRACKET, $position + 1);
if ($curlyOpen === false) {
return;
}
// 查找 extends / implements
$extendsPos = $file->findNext(T_EXTENDS, $position + 1, $curlyOpen);
if ($extendsPos === false) {
$file->addError(
'All CP Controller classes must extend AbstractCPController',
$position,
'MissingExtends'
);
return;
}
// 解析 extends 后的完整类名（支持 \Namespace\Class）
$parentClass = '';
$i = $extendsPos + 1;
while ($i < $curlyOpen && !in_array($tokens[$i]['code'], [T_COMMA, T_CLOSE_PARENTHESIS, T_OPEN_CURLY_BRACKET], true)) {
if (in_array($tokens[$i]['code'], Tokens::$nameTokens, true)) {
$parentClass .= $tokens[$i]['content'];
}
$i++;
}
$parentClass = trim($parentClass);
if (!str_ends_with($parentClass, 'AbstractCPController')) {
$file->addError(
sprintf(
'CP Controller "%s" must extend AbstractCPController, but extends "%s"',
$className,
$parentClass ?: '(unknown)'
),
$extendsPos,
'InvalidParentClass'
);
}
}
}集成与启用步骤
- 将 Sniff 类保存至项目标准目录（如 phpcs/MyCodingStandard/Sniffs/Classes/ClassInheritanceSniff.php）；
- 在 ruleset.xml 中注册标准和规则：
<?xml version="1.0"?> <ruleset name="MyProject"> <description>Custom rules for My Project</description> <autoload>./phpcs/autoload.php</autoload> <rule ref="MyCodingStandard.Classes.ClassInheritance"> <include-pattern>*/src/Controller/CP/*</include-pattern> </rule> </ruleset> - 运行检测：
vendor/bin/phpcs --standard=ruleset.xml src/Controller/CP/
总结
虽然 PHPCS 默认不支持继承约束，但通过自定义 Sniff 可以在词法分析层精确捕获 extends 行为。本方案具备命名空间感知、错误定位精准、易于集成等优点，是保障框架约定（如控制器统一基类）的有效工程实践。如需进一步增强，可扩展支持接口实现检查、抽象类豁免、或结合 PHPStan 进行语义级校验。
立即学习“PHP免费学习笔记（深入）”；
