Webman连接Neo4j应使用graphaware/neo4j-php-client，通过Bolt协议（端口7687）或HTTP协议建立连接，需配置超时参数、启用keep-alive，并采用参数化查询防止注入；注意Neo4j 5.x默认禁用HTTP接口，且该客户端非协程安全，协程环境下需禁用协程或改用同步模式。
Webman里怎么连上Neo4j？用neo4j-php-client最稳
Webman本身不内置图数据库驱动，得靠第三方客户端。目前 PHP 生态里 neo4j-php-client 是维护最勤、兼容性最好的选择（支持 Neo4j 4.x–5.x，HTTP 和 Bolt 协议都行）。别用过时的 everyman/neo4jphp，它早就不更新了，连 PHP 8 都跑不起来。
安装命令直接走 Composer：
composer require graphaware/neo4j-php-client
连接建议放在 Webman 的 app/bootstrap.php 或单独建个 app/Service/Neo4jService.php 里初始化，避免每次请求都新建连接。Bolt 协议比 HTTP 快不少，开发时用默认端口 7687，记得确认 Neo4j 服务开了 dbms.connector.bolt.enabled=true。
- 用户名密码默认是
neo4j/neo4j，首次登录后必须改密码，否则客户端会报AuthorizationFailedException - 如果连本地 Docker 实例，
host别写localhost，改用host.docker.internal（Mac/Windows）或宿主机 IP（Linux） - Webman 是常驻内存模型，连接对象可以复用，但别全局 static 存句柄——事务没结束就丢掉引用，可能卡住连接池
怎么安全地执行 Cypher 查询？别直接拼字符串
用户输入进 Cypher 是高危操作，WHERE name = '$name' 这种写法等于给 SQL 注入开绿灯。必须用参数化查询，neo4j-php-client 的 run() 方法原生支持：
$session = $client->createSession();
$result = $session->run('MATCH (u:User) WHERE u.id = $id RETURN u.name', ['id' => $userId]);
所有动态值都塞进第二个参数数组，键名和 Cypher 里的 $xxx 对齐。注意：节点标签（User）、关系类型（FOLLOWS）、属性名（name）不能参数化，只能白名单校验后拼接。
- 批量写入别用多个
run()，改用writeTransaction()包一层，不然性能断崖式下跌 - 读多写少场景下，把常用查询封装成方法，比如
findUserById(int $id)，内部统一处理参数和异常 - 返回结果别直接
json_encode($result)—— 它是迭代器，得先->records()取出数组，否则前端收不到数据
Webman中间件里怎么加 Neo4j 请求超时控制？
Neo4j 响应慢会拖垮整个 Webman 进程，尤其在高并发查复杂路径时。PHP 默认 socket 超时是永久等待，必须显式设限。
Webman 2.2.0版本强化了 TCP/UDP 服务支持，优化路由组管理，并增强异步任务处理能力。结合协程与连接池技术，Webman 能轻松应对高并发场景，适用于网站、接口服务、即时通讯、物联网及游戏开发，兼具高性能、灵活扩展与稳定可靠，是多场景 PHP 服务开发的理想选择。
创建客户端时传入配置数组，重点盯紧这三个键：
-
connection_timeout：建立 TCP 连接的上限，设3.0秒足够（单位是秒，支持小数） -
timeout：单次请求总耗时上限，查深度遍历建议设10.0，简单点查设2.0 -
keep_alive：保持长连接，设true减少握手开销
示例配置：
$client = ClientBuilder::create()
->withDefaultTimeout(10.0)
->withConnectionTimeout(3.0)
->withKeepAlive(true)
->addConnection('http', 'http://neo4j:neo4j@localhost:7474')
->build();
如果用了 Bolt 协议，addConnection() 改成 addBoltConnection()，端口换 7687。注意：超时抛的是 GraphAware\Neo4j\Client\Exception\NetworkException，不是通用 Exception，捕获时要写全名。
为什么查出来是空数组？检查这三处硬伤
明明 Neo4j Browser 里 Cypher 跑得好好的，Webman 里却返回空，大概率不是语法问题，而是环境或协议错位：
- Neo4j 5.x 默认关闭 HTTP 接口，只留 Bolt。如果代码里还用
http://地址，run()会静默失败（返回空结果，不报错），换成bolt://或启用dbms.connector.http.enabled=true - Webman 开了协程（如使用
webman-plugin/swoole），但neo4j-php-client不是协程安全的，socket 层会阻塞整个 worker。此时必须关掉协程，或改用同步模式启动 Webman - 节点/关系有中文属性值，但 Neo4j 服务端字符集不是 UTF-8（比如 Docker 启动时没挂载
-e NEO4J_dbms_default__database__encoding=UTF-8），查出来字段就变 null
调试时最有效的办法：在 run() 后立刻加一行 var_dump($result->summarize()->getCounters());，看 nodesCreated、containsUpdates 等字段，比猜“有没有数据”快得多。
