利用Composer库实现支持高性能全文检索的Elasticsearch PHP DSL-composer-PHP中文网

elasticsearch php 官方客户端需手动构造严格层级的数组dsl，must/filter等必须为数组而非对象，空对象用new stdclass()，响应建议转关联数组或封装dto，批量操作须分片且检查errors字段。

利用composer库实现支持高性能全文检索的elasticsearch php dsl

用 `elasticsearch/elasticsearch` 官方客户端写 DSL 查询，别碰 `ruflin/Elastica`

官方客户端虽然原生不带“DSL 构建器”，但结构清晰、类型安全、可链式调用，比 Elastica 更容易控制请求体和响应解析。Elastica 的 DSL 封装看似方便，实际隐藏了 query body 的构造逻辑，调试时经常卡在“为什么没命中”却查不到真实发出去的 JSON。

直接用官方客户端 + 手动构造数组 DSL 是最可控的方式。示例：一个带 multi_match 和 bool 过滤的查询：

$client = ClientBuilder::create()->build();
$params = [
    'index' => 'products',
    'body' => [
        'query' => [
            'bool' => [
                'must' => [
                    ['multi_match' => [
                        'query' => 'wireless headphones',
                        'fields' => ['title^3', 'description']
                    ]]
                ],
                'filter' => [
                    ['term' => ['status' => 'active']],
                    ['range' => ['price' => ['gte' => 50]]]
                ]
            ]
        ],
        'highlight' => [
            'fields' => ['title' => new \stdClass(), 'description' => new \stdClass()]
        ]
    ]
];
$response = $client->search($params);

new \stdClass() 是必须的——Elasticsearch PHP 客户端对空对象（{}）有特殊处理，用 [] 会丢掉 highlight 配置
所有嵌套 query 类型（match、range、term）都必须是独立数组项，不能合并成一个大数组，否则会被忽略
字段名里的 ^3 是 boost 写法，直接写字符串即可，客户端不做解析，原样发给 ES

避免 `search()` 返回 `stdClass` 导致的类型断裂

默认返回的是 stdClass 对象，但 PHP 8.2+ 开启严格模式后，foreach 或 isset() 操作可能意外失败；更麻烦的是 IDE 无法推导属性，补全失效，重构风险高。

推荐两种解法：

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

用 json_decode(json_encode($response), true) 强制转成关联数组——简单粗暴，适合快速原型，但多一次序列化开销
封装一层响应处理器，把关键路径（如 $response['hits']['hits']）映射为 typed array 或 DTO 类——适合中大型项目，尤其当你要做聚合结果解析或高亮提取时
注意：不要依赖 $response->hits->total 这种写法，ES 7.0+ 的 total 是对象（{"value": 123, "relation": "eq"}），直接取 ->value 才安全

批量写入时别用 `bulk()` 默认参数，小心内存爆掉

大批量索引数据时，bulk() 默认把全部操作打包成一个请求发过去，如果单次传入 10 万条文档，PHP 进程很可能 OOM，ES 端也会触发 circuit_breaking_exception。

务必手动分批，每批 ≤ 1000 条（根据文档平均大小调整），用 array_chunk() 切分
每个 bulk 请求的 body 必须是“动作行 + 文档行”的交错结构，不是纯文档数组——漏掉 index 或 create 动作行会导致整批静默失败
检查响应中的 errors 字段，哪怕 HTTP 状态码是 200，也可能部分失败；$response['errors'] === true 时，要遍历 $response['items'] 找具体哪条失败

中文分词必须自己配 IK 插件，官方客户端不解决语言问题

PHP 客户端只负责发请求，分词效果完全取决于 ES 集群配置。没装 ik 或 hanlp 插件，match 查询对中文基本无效——搜“手机”匹配不到“智能手机”，因为默认标准分词器按字切分。

确认插件已安装：访问 http://es-host:9200/_cat/plugins?v，看到 ik 行才算成功
创建索引时显式指定 analyzer，例如："analyzer": "ik_max_word"，别依赖默认设置
调试分词效果用 _analyze API：GET /products/_analyze?q=智能手机&analyzer=ik_max_word，看输出是否含预期 token
PHP 里不要尝试用 mb_ 函数预处理文本——ES 分词器在服务端运行，客户端传原始 UTF-8 字符串即可