README

Bolt

PHP 库，用于通过 Bolt 协议规范使用 TCP 套接字与图数据库通信。Bolt 协议由 Neo4j 创建，文档可在 https://www.neo4j.com/ 查找。此库旨在提供底层支持，兼容所有可用版本，并跟上协议消息架构和规范。

🏷️ 版本支持

我们尽力跟上，此库支持 Bolt <= 5.4。

https://www.neo4j.com/docs/bolt/current/bolt-compatibility/

✅ 要求

此库与 PHP 支持版本 保持同步，这意味着它是 PHP^8.1。

PHP 扩展

• mbstring
• sockets（可选）- 当您使用 Socket 连接类时需要
• openssl（可选）- 当您使用启用 SSL 的 StreamSocket 连接类时需要

💾 安装

您可以使用 composer 或从 github 下载此存储库并手动实现它。

Composer

在您的项目中运行以下命令以安装包的最新适用版本

composer require stefanak-michal/bolt

Packagist

手动

1. 从 github 下载源代码
2. 解压
3. 将 src 目录的内容复制到您的项目中

🖥️ 使用

使用概念基于 Bolt 消息。Bolt 消息按 1:1 映射为协议方法。可用的协议方法取决于 Bolt 版本。通信在 pipeline 中进行，您可以在从服务器获取响应之前链式调用多个 Bolt 消息。

主 Bolt 类作为工厂设计模式，根据请求的 Bolt 版本返回协议类的实例。基本使用包括查询执行和获取响应，这些操作分为两个方法。第一个消息 run 用于发送查询。第二个消息 pull 用于从数据库中执行的查询获取响应。Bolt 消息 pull 的数据库响应总是包含 n+1 行，因为最后一项是包含元信息的 success 消息。

ℹ️ 关于可用 Bolt 消息的更多信息： https://www.neo4j.com/docs/bolt/current/bolt/message/

可用方法

Bolt 类

协议类

多个方法接受名为 $extra 的参数。此参数可以包含 Bolt 规范中定义的任何键值对。在 Neo4j 开发期间扩展了此参数，这意味着其内容已更改。在使用此参数时，请注意您正在使用的版本。您可以在 Bolt 文档中了解更多关于额外参数的信息，您可以在其中查看您的版本和 bolt 消息。

ℹ️ 协议类中方法的注释包含指向特定版本和来自所提及文档网站的直接链接。

认证

事务

Bolt 3版本支持事务，协议包含这些方法

• begin
• commit
• rollback

run 如果没有明确打开事务，则会在自动提交事务中执行查询。

Cypher查询参数

也可以提供作为实现 Bolt\packstream\IPackListGenerator 或 Bolt\PackStream\IPackDictionaryGenerator 类的实例的列表或字典。这种方法有助于处理大量数据时的内存管理。要了解更多信息，您可以查看性能测试或打包测试。

⚠️ 结构 Node、Relationship、UnboundRelationship 和 Path 不能用作参数。它们仅作为从数据库接收的数据可用。

示例

// Choose and create connection class and specify target host and port.
$conn = new \Bolt\connection\Socket('127.0.0.1', 7687);
// Create new Bolt instance and provide connection object.
$bolt = new \Bolt\Bolt($conn);
// Set requested protocol versions ..you can add up to 4 versions
$bolt->setProtocolVersions(5.4);
// Build and get protocol version instance which creates connection and executes handshake.
$protocol = $bolt->build();

// Initialize communication with database
$response = $protocol->hello()->getResponse();
// verify $response for successful initialization

// Login into database
$response = $protocol->logon(['scheme' => 'basic', 'principal' => 'neo4j', 'credentials' => 'neo4j'])->getResponse();
// verify $response for successful login

// Pipeline two messages. One to execute query with parameters and second to pull records.
$protocol
    ->run('RETURN $a AS num, $b AS str', ['a' => 123, 'b' => 'text'])
    ->pull();
    
// Fetch waiting server responses for pipelined messages.
foreach ($protocol->getResponses() as $response) {
    // $response is instance of \Bolt\protocol\Response.
    // First response is SUCCESS message for RUN message.
    // Second response is RECORD message for PULL message.
    // Third response is SUCCESS message for PULL message.
}

自动加载

目录 src 包含自动加载文件，该文件仅接受 Bolt 库命名空间。主 Bolt 命名空间指向此目录。如果您使用 composer 安装了此项目，则必须加载 vendor/autoload.php。

⛓️ 连接

Bolt 类构造函数接受连接参数。此参数必须是实现 IConnection 接口的类的实例。库提供了一些选项。

\Bolt\connection\Socket

此类使用 php 扩展 sockets，具有更好的内存使用。更多信息请参阅：https://php.ac.cn/manual/en/book.sockets.php

\Bolt\connection\StreamSocket

此类使用 php 流功能。这是 php 的一部分，无需扩展。更多信息请参阅：https://php.ac.cn/manual/en/ref.stream.php

StreamSocket 除了实现接口的方法外，还有一个用于配置 SSL 的方法。SSL 选项需要 php 扩展 openssl。当您想激活 SSL 时，必须调用 setSslContextOptions 方法。此方法接受数组，符合 php 规范，如下所示：https://php.ac.cn/manual/en/context.ssl.php。

\Bolt\connection\PStreamSocket

此类扩展了 StreamSocket 并添加了对持久连接的支持。在重用连接时，将消耗剩余的缓冲区，并自动发送消息 RESET。由于 PHP 是无状态的，因此使用此连接类需要存储有关活动 TCP 连接的元信息。默认存储是 \Bolt\helper\FileCache，您可以通过 setCache 方法（PSR-16 Simple Cache）来更改它。

⚠️ 如果您的系统重用持久连接，并且由于某种原因丢失了有关它的元信息，那么您的连接尝试将以 ConnectionTimeoutException 结束。重复尝试连接将成功。

🔒 SSL

Neo4j Aura

连接到 Aura 需要 SSL 加密，SSL 加密由 SSL 提供。要连接到 Aura，必须使用 StreamSocket 连接类并启用 SSL。

$conn = new \Bolt\connection\StreamSocket('helloworld.databases.neo4j.io');
// enable SSL
$conn->setSslContextOptions([
    'verify_peer' => true
]);
$bolt = new \Bolt\Bolt($conn);

https://php.ac.cn/manual/en/context.ssl.php

示例：在本地主机数据库上使用自签名证书

$conn = new \Bolt\connection\StreamSocket();
$conn->setSslContextOptions([
    'local_cert'=> 'd:\www\bolt\cert\public_cert.pem',
    'local_pk' => 'd:\www\bolt\cert\private_key.pem',
    'passphrase' => 'password',
    'allow_self_signed' => true,
    'verify_peer' => false,
    'verify_peer_name' => false
]);
$bolt = new \Bolt\Bolt($conn);

🔖 您还可以查看我在Neo4j 和自签名证书上如何实现 SSL 的文章。

⏱️ 超时

连接类构造函数包含 $timeout 参数。此超时用于已建立的套接字连接。要为建立套接字连接本身设置超时，您必须设置 ini 指令 default_socket_timeout。

设置 ini 指令不是连接类的一部分，因为 ini_set 函数可以在生产环境中出于安全原因被禁用。

🚦 服务器状态

服务器状态不是由服务器报告的，而是通过接收到的响应进行评估的。您可以通过属性 $protocol->serverState 访问当前状态。每次调用 getResponse(s) 时，此属性都会更新。

📊 分析

Bolt 会收集匿名分析数据。这些数据以离线方式存储（作为临时目录中的文件），并每天提交一次。您可以使用环境变量 BOLT_ANALYTICS_OPTOUT 选择退出。

分析数据是公开的，可在 Mixpanel 上找到。

📌 更多解决方案

如果您需要一个简单的类来覆盖基本功能，可以使用： neo4j-bolt-wrapper

如果您需要企业级解决方案，请查看： php-client

PDO 实现可在 pdo-bolt 找到

更多信息可在： https://neo4j.com/developer/php/ 找到

♻️ 旧版本

如果您需要支持已到寿命的 PHP 版本，这里有一个简短的信息列表。并非所有新功能都实现了向下兼容，此说明文件已更新到最新发布的版本。

• PHP < 7.4 - v3.x
• PHP 7.4 - v5.x
• PHP 8.0 - v6.x