webman集成elasticsearch有四种方式：一、用webman-search插件快速接入，含安装、配置、索引初始化；二、手动集成官方客户端实现深度控制；三、通过模型事件自动同步数据；四、增强搜索结果高亮与分页；五、添加连接容错与降级策略。
一、使用 webman-search 插件快速集成 Elasticsearch
Webman 作为高性能 PHP 框架，原生不内置搜索引擎支持，需借助插件实现 Elasticsearch 集成。webman-search 是专为 Webman 设计的搜索抽象层，统一适配 Elasticsearch、MeiliSearch 和 Xunsearch，屏蔽底层差异，降低接入成本。
1、执行 Composer 命令安装插件：composer require shopwwi/webman-search
2、发布配置文件：运行 php webman vendor:publish shopwwi/webman-search 命令，生成 config/plugin/shopwwi/search/app.php 配置项
3、在 app.php 中显式指定搜索引擎类型为 elasticsearch，并设置连接参数：'driver' => 'elasticsearch', 'hosts' => ['http://127.0.0.1:9200']
4、执行索引初始化命令：php webman search:create:index，该命令将自动创建符合当前模型结构的 Elasticsearch 索引并启用默认 mapping
二、手动集成官方 elasticsearch/elasticsearch 客户端
当需要精细控制请求体、自定义 bulk 批量写入逻辑或调试底层通信时，可绕过插件，直接引入官方 PHP 客户端库，实现与 Elasticsearch 的深度对接。
1、安装官方客户端：composer require elasticsearch/elasticsearch
2、在 support/searches 目录下新建 ElasticsearchClient.php，使用 ClientBuilder 构建客户端实例，并禁用签名认证（若 ES 未启用安全模块）：$client = ClientBuilder::create()->setHosts(['127.0.0.1:9200'])->setRetries(0)->build();
3、编写 createIndex 方法，显式定义 settings 和 mappings，例如设置 ik_max_word 分词器：'analysis' => ['analyzer' => ['ik_analyzer' => ['type' => 'custom', 'tokenizer' => 'ik_max_word']]]
4、在控制器中调用 addDoc 方法写入文档时，确保 _id 字段与业务主键一致，便于后续 update 或 delete 操作精准定位：$params = ['index' => 'articles', 'id' => $article['id'], 'body' => $article];
三、基于 Model 自动同步数据至 Elasticsearch
为保障数据库与 Elasticsearch 索引间的数据一致性，需在数据变更生命周期中嵌入同步钩子。Webman 支持通过事件监听或模型观察者机制触发索引更新，避免手动维护带来的遗漏风险。
1、在 Article 模型的 saved 方法中判断是否为新增或更新操作：if ($this->wasRecentlyCreated) { $this->syncToES('create'); }
2、在 deleted 方法中触发删除动作：if ($this->exists === false) { $this->syncToES('delete'); }
Webman 2.2.0版本强化了 TCP/UDP 服务支持，优化路由组管理，并增强异步任务处理能力。结合协程与连接池技术，Webman 能轻松应对高并发场景，适用于网站、接口服务、即时通讯、物联网及游戏开发，兼具高性能、灵活扩展与稳定可靠，是多场景 PHP 服务开发的理想选择。
3、在 syncToES 方法内构造 Elasticsearch 请求参数，区分 create/update/delete 场景：case 'delete': $client->delete(['index' => 'articles', 'id' => $this->id]); break;
4、对批量操作（如后台导入、定时同步）使用 bulk API，将多条操作合并为单次 HTTP 请求，显著提升吞吐量：$bulkParams['body'][] = ['delete' => ['_index' => 'articles', '_id' => $id]];
四、实现搜索结果高亮与分页增强
Elasticsearch 原生支持字段高亮，但需在 query DSL 中正确声明 highlight 参数，并在响应解析阶段提取对应片段。同时，Webman 默认分页组件无法直接适配 ES 的 from/size 分页模型，需做桥接转换。
1、构建 search 请求 body 时，在 highlight 节点中指定 title 和 content 字段，并关闭 pre_tags/post_tags 默认包裹标签：'highlight' => ['fields' => ['title' => new \stdClass(), 'content' => new \stdClass()], 'require_field_match' => false]
2、执行搜索后，遍历 hits.hits 数组，从 highlight 子节点提取高亮文本覆盖原始字段：$item['title'] = $hit['highlight']['title'][0] ?? $item['title'];
3、将 Laravel 风格的 ?page=2&per_page=10 请求参数转换为 ES 兼容的 from/size：$from = ($page - 1) * $per_page; $size = $per_page;
4、在响应中注入 total 字段用于前端分页控件渲染：return response()->json(['data' => $results, 'meta' => ['total' => $response['hits']['total']['value']]]);
五、处理 Elasticsearch 连接异常与降级策略
生产环境中，Elasticsearch 实例可能因负载过高、网络抖动或服务重启而短暂不可用。若搜索请求直接抛出异常导致页面报错，将严重影响用户体验。需设计连接容错与服务降级机制。
1、在客户端初始化时启用重试策略并限制最大重试次数：$client = ClientBuilder::create()->setHosts(['127.0.0.1:9200'])->setRetries(2)->build();
2、捕获 Elasticsearch\Common\Exceptions\NoNodesAvailableException 异常，在 catch 块中返回空结果集并记录告警：Log::warning('ES unavailable, fallback to DB search');
3、配置开关变量控制是否启用 ES 搜索，可通过 config/plugin/shopwwi/search/app.php 中的 'enabled' 键动态切换：if (config('plugin.shopwwi.search.app.enabled') === false) { return $this->fallbackToMysqlSearch($keyword); }
4、对高亮失败场景做兜底处理：当 highlight 字段缺失或为空时，直接返回原始字段值，避免模板渲染错误：isset($hit['highlight']['title']) ? $hit['highlight']['title'][0] : $hit['_source']['title']
