Statamic CMS 中单术语过滤失效问题分析与解决方案

问题背景

在Statamic CMS的最新版本中，用户报告了一个关于术语过滤功能的异常现象。当在集合条目列表中使用分类术语进行过滤时，如果蓝图中限制了每个条目只能关联一个术语（即max_items设置为1），过滤功能会返回"无结果"，而实际上应该匹配到相关条目。

技术分析

这个问题本质上与Statamic处理分类术语关联的方式有关。在蓝图中将术语关联限制为单一时，系统会将术语存储为单个值而非数组。而Statamic的过滤查询逻辑在5.43.0版本后发生了变化，主要针对JSON数组格式的术语存储进行了优化。

具体来说，过滤查询现在默认使用whereJsonContains方法来匹配存储在JSON数组中的术语。然而，当max_items设置为1时，术语被存储为简单字符串而非数组，导致whereJsonContains查询无法正确匹配。

影响范围

该问题影响以下版本组合：

• Statamic 5.43.0及以上版本
• 使用分类法术语过滤功能的集合
• 蓝图中设置了max_items: 1的术语关联字段

解决方案

针对这个问题，开发者可以考虑以下几种解决方案：

1. 临时解决方案：在蓝图中移除max_items限制，允许术语以数组形式存储。

2. 代码修复方案：修改查询逻辑，使其能够同时处理数组和单值形式的术语存储。可以在查询中添加orWhere条件：

$query
    ->whereJsonContains($handle, $values['term'])
    ->orWhere($handle, $values['term'])

3. 版本回退：暂时回退到5.43.0之前的版本，等待官方修复。

最佳实践建议

为了避免类似问题，建议开发者在处理分类术语关联时：

• 统一使用数组形式存储术语，即使max_items设置为1
• 在自定义查询中同时考虑单值和数组形式的术语存储
• 在升级Statamic版本时，特别注意分类法相关功能的测试

总结

这个案例展示了数据存储格式与查询逻辑之间的微妙关系。在开发内容管理系统时，保持数据存储方式的一致性对于确保查询功能的可靠性至关重要。Statamic团队已经注意到这个问题，预计会在未来的版本中提供更完善的解决方案。