typo3-conformance

TYPO3 扩展一致性检查器

根据 TYPO3 编码标准、架构模式和最佳实践评估 TYPO3 扩展。

适用场景

• 扩展质量 / 是否满足 TER 要求
• 评分式一致性报告
• 升级到 v12/v13/v14（默认 / 黄金标准为 v14.3 LTS）

委派

测试 -> typo3-testing | 文档 -> typo3-docs | OpenSSF -> enterprise-readiness | 发布 / TER -> github-release

将扩展升级到较新的 TYPO3 版本 -> typo3-extension-upgrade，然后在此停止。 已有案例表明：有人要求让扩展兼容当前 LTS，Agent 却加载了此技能并完成了一轮一致性检查——移除了 ext_tables.php、搜索了已弃用调用、统计了 strict_types——随后便报告完成。清单仍标注旧版本，也没有针对新版本进行安装或测试。审计当前状态不是升级，放宽版本约束也不是升级。如果请求是提升版本，请移交处理，而不是审计眼前的代码。

如果请求只是检查版本声明，且两者已经一致，请说明这一点并停止。 使用两种表示法写出版本范围，并指出你比对过的位置，不要做任何更改。省略任何“次要观察”或“非错误说明”部分：在检查中，未经请求的评论会被视为发现；而没有发现问题的检查也没有其他内容可报告。

如果 composer.json 和 ext_emconf.php 不一致，应先确定哪一个是正确的，再让两者保持一致。 最新的 LTS 并非默认答案。先收集证据，再做决定：

1. 仓库自身的规则——AGENTS.md、CONTRIBUTING.md 或 README 可能会指定哪个文件具有权威性。请引用原文。
2. 实际测试的版本——CI 矩阵中的 TYPO3 版本（.github/workflows/、Build/、runTests.sh 默认值）。
3. 代码的需求——仅存在于两个版本线之一的 API（references/v14-deprecations.md、references/v13-deprecations.md）。
4. 产生分歧的原因——查看 git log -p -- composer.json ext_emconf.php；如果有相关历史记录。

如果规则与证据一致，就将两个文件都调整到该版本线。如果两者冲突——权威文件指定了 CI 矩阵未测试的版本线——则遵循该规则，并将未测试的版本线报告为发现，而不是扩大 CI 或修改代码来迎合它。只更改版本声明：两个声明，以及重复提及这些声明的文档。每个文件都使用各自的表示法（composer.json 中使用 ^13.4，ext_emconf.php 中使用 13.4.0-13.4.99——切勿在 ext_emconf.php 中使用插入符；Composer 版本范围如 ^13.4 || ^14.3 对应一个范围，参见 references/ext-emconf-validation.md），并在答复中指出决定性证据。

**范围：**仅限扩展。站点 / 项目仓库（type: project + Compose）——使用黄金检查器 typo3-14-gold/tools/conformance 评分。

工作流

步骤 0：上下文

读取 ext_emconf.php + composer.json，了解版本、类型和范围。

步骤 1-11：检查

1. 元数据——key、TYPO3 版本、类型；TER、docs.typo3.org、README 和 GitHub 中的标题与描述保持一致（references/extension-naming.md）
2. 结构——composer.json、ext_emconf.php、Classes/、Configuration/、Resources/
3. 编码——strict_types、PSR-12、PHP 8.4 显式可空类型、PHP 8.5 浮点数转整数
4. 禁止事项——不使用 $GLOBALS，不使用 GeneralUtility::makeInstance() 创建服务
5. 架构——构造函数 DI、Services.yaml、PSR-14 事件（try/catch）、PSR-3 日志记录（在容器构建的服务中通过构造函数注入 LoggerInterface，或使用 LoggerAware+NullLogger）、工厂回退方案
6. 后端——ES6、Modal API、CSRF、CSP（v13+）
7. 测试——PHPUnit、Playwright E2E、覆盖率 >70%
8. 实践——DDEV、runTests.sh、CI/CD
9. TER——发布工作流、上传注释
10. 审计——PHPStan baseline、TCA searchFields、XLIFF、缓存 has()+get()、查询属性、多版本适配器
11. v14 就绪情况——不使用 ext_tables.php/HashService/魔术查找器；Fluid VHs 严格；XLF 使用 2 个空格缩进。参见 references/v14-deprecations.md。

步骤 12：验证

修复后重新运行。记录分数变化。

快速 Grep 示例

grep -rL 'strict_types' Classes/ --include='*.php'
grep -rn '\$GLOBALS' Classes/ --include='*.php'
grep -rn 'GeneralUtility::makeInstance' Classes/ --include='*.php'
grep -rPn '\(\s*[A-Za-z\\]+\s+\$\w+\s*=\s*null' Classes/ --include='*.php' | grep -v '?'  # PHP 8.4 implicit nullable
grep -rn '->has(' Classes/ --include='*.php'                          # cache has()+get() anti-pattern
grep -l 'strict_types' ext_emconf.php                                 # ext_emconf must NOT have strict_types
grep -rn '(int)\s*\$' Classes/ --include='*.php'                      # PHP 8.5 implicit float-to-int
grep -rn 'data-toggle\|data-dismiss\|data-ride' Resources/ --include='*.html'  # Bootstrap 4 in Fluid
grep -rn 'HashService\|GeneralUtility::hmac(\|->findBy[A-Z]\|->findOneBy[A-Z]\|->countBy[A-Z]' Classes/ --include='*.php'  # v14 removals
[ -f ext_tables.php ] && echo "WARN: ext_tables.php deprecated (#109438)"   # v14.3 deprecation

评分

基础分（0-100）： 架构（20）+ 指南（20）+ PHP（20）+ 测试（20）+ 实践（20）。卓越奖励最高 22 分。无论得分如何，关键问题都会阻止发布。

范围	级别	操作
90+	优秀	可用于生产环境/已准备好提交至 TER
80-89	良好	修复小问题
70-79	可接受	发布前修复
50-69	需要改进	需要投入大量精力
<50	严重	阻止部署

参考资料

参见 references/：

• 架构与代码： extension-architecture.md、directory-structure.md、php-architecture.md、coding-guidelines.md、best-practices.md、hooks-and-events.md
• 验证： composer-validation.md、extension-naming.md、ext-emconf-validation.md、ext-files-validation.md、runtests-validation.md、version-requirements.md、testing-standards.md
• 多版本： dual-version-compatibility.md、v13-v14-dual-compatibility.md、multi-version-dependency-compatibility.md、v13-deprecations.md、v14-deprecations.md
• 实践与后端： development-environment.md、backend-module-v13.md、ter-publishing.md、report-template.md、excellence-indicators.md、localization-coverage.md、crowdin-integration.md

assets/Build/ 中的资源模板：PHPStan、PHP-CS-Fixer、Rector、ESLint、Stylelint、TypoScript lint。