php-elasticsearch-dsl 库已停止维护，v0.2.0 是最后一个兼容 es 6.x 的稳定版；es 7.x/8.x 用户应改用 ongr/elasticsearch-dsl 或官方客户端内置 querybuilders，并注意 boolquery 需包裹在 search 中、aggs 与 query 平级、字段需加 .keyword 后缀等关键细节。
直接说结论：PHP-Elasticsearch-DSL 库本身不维护了，elasticsearch-dsl 的 v0.2.0 是最后一个稳定版，且只兼容 Elasticsearch 6.x —— 如果你用的是 ES 7.x 或 8.x，must/should 等布尔子句的结构、match_phrase 的参数格式、甚至 size 默认行为都可能出错，硬集成会掉进隐性兼容坑里。
Composer 安装时得锁死版本并确认 ES 大版本
这个库没发新版多年，composer require bshaffer/elasticsearch-dsl 默认拉 dev-master（已不可用），必须手动指定兼容分支：
-
composer require bshaffer/elasticsearch-dsl:^0.2.0—— 对应 ES 6.8 及以下 - ES 7.x 用户需改用
ongr/elasticsearch-dsl（注意命名不同），它支持bool查询的filter子句写法，且match默认不分析字段需显式加analyzer - 若项目已用官方
elasticsearch/elasticsearch客户端 v8.x，别混用 DSL 库——v8 客户端自带QueryBuilders风格构造器，更轻量也更可控
构建 bool 查询时容易漏掉顶层 wrapper
很多人写完 new BoolQuery() 就直接传给客户端，结果返回 "query malformed, empty clause"。这是因为 DSL 库生成的是子查询对象，不是完整请求体：
- 必须用
new Search()包一层，再调addQuery()，否则toArray()输出缺query根键 -
BoolQuery本身不自动补must，要手动$bool->addMust($term)，空must数组会导致整个 bool 被忽略 - ES 7+ 要求
minimum_should_match必须是整数或字符串（如"1"），传1会被当成布尔值处理而报错
聚合查询嵌套层级易错：aggs 不在 query 下
DSL 库把 aggs 和 query 平级处理，但新手常误以为 addAggregation() 是 BoolQuery 的方法：
-
Search对象才有addAggregation()，不是BoolQuery或MatchQuery -
TermsAggregation的字段名必须带.keyword后缀（ES 7+ 默认 mapping 不开启fielddata），写"title"会静默失败 - 如果同时要排序和聚合，
addSort()和addAggregation()都得挂在Search实例上，顺序无关但缺一不可
最麻烦的其实是 mapping 变更后 DSL 生成的字段路径没同步更新——比如从 status.raw 改成 status.keyword，代码里还写 raw，查不到数据也不会报错，只能靠 explain: true 开关去翻 ES 返回的 reason 字段。这种细节，DSL 库帮不了你。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
