当前主流 PHP 静态分析工具（PHPStan 和 Psalm）均不支持真正意义上的递归类型定义，因此无法精确建模深度嵌套、结构动态的条件数组（如 CakePHP 风格的 ['OR' => [...]]），需通过类型注解策略与运行时防护协同保障安全。
当前主流 php 静态分析工具（phpstan 和 psalm）均不支持真正意义上的递归类型定义，因此无法精确建模深度嵌套、结构动态的条件数组（如 cakephp 风格的 `['or' => [...]]`），需通过类型注解策略与运行时防护协同保障安全。
在构建 ORM 查询条件系统时，安全性与类型严谨性高度耦合：键名（如 'OR'、'category_id'）必须为字面量字符串（literal-string），以杜绝 SQL 注入；而值则需区分——纯 SQL 片段（如 'category_id IS NULL'）应为 literal-string，用户输入值（如 $id）必须经参数化处理，不可拼接进 SQL。
然而，静态分析工具在此场景面临根本性限制：
- ✅ PHPStan 明确表示：“Recursive types aren't supported now and I don't know if they ever will”（2021）；“very hard to do”（2022）。其类型系统不支持自引用泛型（如 array
的无限展开）。 - ✅ Psalm 同样关闭了该能力：“Recursive types aren’t supported (and probably won’t ever be)”（2019），并在多个 issue 中强调设计上主动拒绝递归类型，因会导致类型推导不可判定、性能急剧下降。
这意味着，以下理想化的递归类型注解无法被任何主流工具识别或验证：
/** * ❌ 不被支持：Psalm/PHPStan 会忽略或报错 * @param array<literal-string, int|string|literal-string|array<literal-string, mixed>> $conditions */
可行的工程化应对策略
1. 分层类型约束（推荐）
将“顶层结构”与“递归子结构”解耦，用非递归但语义明确的联合类型覆盖常见合法形态：
立即学习“PHP免费学习笔记（深入）”；
/**
* ✅ 兼容 Psalm & PHPStan 的务实注解
* 支持：扁平条件、单层 OR/AND/XOR、以及一层嵌套（实践中 95%+ 场景）
* @param array<int, literal-string|array{0: literal-string, 1?: mixed}>|
* array<literal-string, int|string|literal-string|array{literal-string, mixed}> $conditions
*/
public function find(string $finder, array $conditions): void { ... }配合严格运行时校验（见下文），既保留类型提示价值，又避免工具报错。
2. 强制使用构造器 API（更安全的替代方案）
彻底规避数组 DSL 的类型表达困境，改用流式接口或专用条件对象：
$articles->find('all')
->where(fn (QueryExpression $e) => $e
->or_(
$e->isNull('category_id'),
$e->eq('category_id', $id)
)
);此类 API 天然可静态分析（方法参数类型明确），且编译期即可捕获非法键名（如 $e->eq('category_id = ' . $id, ...) 会因参数类型不符而报错）。
3. 运行时防御性检查（不可或缺）
静态分析缺位时，必须补足运行时护栏。在 _addConditions() 开头添加严格校验：
private function _addConditions(array $conditions, string $conjunction = 'AND'): array
{
// ? 检查所有键是否为 literal-string（即不含变量拼接）
foreach ($conditions as $k => $v) {
if (!is_string($k) || !\is_literal_string($k)) {
throw new InvalidArgumentException("Condition key '$k' is not a literal string");
}
if (is_array($v)) {
$this->_validateNestedConditions($v); // 递归校验子数组
}
}
// ... 实际逻辑
}? 提示：is_literal_string() 是 Psalm 提供的运行时辅助函数（需启用 psalm-plugin-phpstan 或自定义 stub），PHPStan 用户可借助 assert(is_string($k) && ctype_alnum(str_replace(['_', '-'], '', $k))) 做轻量白名单校验。
总结
静态分析是安全链的一环，而非全部。面对递归结构的固有局限，最佳实践是：
✅ 接受工具边界——不强求 array<... array>> 的无限嵌套类型；
✅ 分层约束 + 运行时校验——用联合类型覆盖高频模式，并在入口处做 literal-string 断言；
✅ 优先重构为可分析 API——将 DSL 迁移至面向对象的条件构建器，从根源提升类型可追踪性与安全性。
唯有结合类型提示、运行时防护与架构演进，才能在灵活性与安全性之间取得可持续平衡。
