README

Neo4j 企业级客户端

简介

Neo4j-PHP-Client 是最先进且灵活的 Neo4j PHP 客户端。

什么是 Neo4j?

Neo4j 是一个事务性、开源的图数据库。图数据库通过连接数据结构管理数据，能够以非常便捷的方式表示任何类型的数据。信息存储在节点及其连接的边中，节点和边都可以有任意属性。了解更多请访问 什么是图数据库？

主要特性

• 支持多连接
• 支持 Bolt 二进制协议
• 内置并自动支持 Neo4j 企业 HA 主从模式，带自动从节点回退

Neo4j 版本支持

Neo4j 功能支持

要求

• PHP >= 5.6
• ext-bcmath
• ext-mbstring
• A Neo4j 数据库（最低版本 2.2.6）

获取帮助

您可以

• 在 StackOverflow 上提问
• 对于错误，请在 GitHub 上创建新问题

实现

• Symfony 框架包

安装和基本用法

安装

将库添加到您的 composer 依赖项

composer require "graphaware/neo4j-php-client:^4.0"

需要 composer 自动加载器，通过提供连接别名和连接设置来配置您的连接

<?php

require_once 'vendor/autoload.php';

use GraphAware\Neo4j\Client\ClientBuilder;

$client = ClientBuilder::create()
    ->addConnection('default', 'http://neo4j:password@localhost:7474') // Example for HTTP connection configuration (port is optional)
    ->addConnection('bolt', 'bolt://neo4j:password@localhost:7687') // Example for BOLT connection configuration (port is optional)
    ->build();

现在您已经准备好连接到数据库了。

注意：构建方法将处理配置设置并返回一个 Client 实例。

基本用法

发送 Cypher 查询

$client->run('CREATE (n:Person)');

带参数的 Cypher 查询

$client->run('CREATE (n:Person) SET n += {infos}', ['infos' => ['name' => 'Ales', 'age' => 34]]);

读取结果

$result = $client->run('MATCH (n:Person) RETURN n');
// a result always contains a collection (array) of Record objects

// get all records
$records = $result->getRecords();

// get the first or (if expected only one) the only record

$record = $result->getRecord();

Record对象包含Cypher查询中一条记录的值

$query = 'MATCH (n:Person)-[:FOLLOWS]->(friend) RETURN n.name, collect(friend) as friends';
$result = $client->run($query);

foreach ($result->getRecords() as $record) {
    echo sprintf('Person name is : %s and has %d number of friends', $record->value('name'), count($record->value('friends')));
}

Cypher语句和堆栈

理想情况下，您应该将语句堆叠起来，并一次性发出所有语句以改善性能。

您可以创建作为Bag操作的Cypher语句堆栈，并使用客户端运行此堆栈，例如：

$stack = $client->stack();

$stack->push('CREATE (n:Person {uuid: {uuid} })', ['uuid' => '123-fff']);
$stack->push('MATCH (n:Person {uuid: {uuid1} }), (n2:Person {uuid: {uuid2} }) MERGE (n)-[:FOLLOWS]->(n2)', ['uuid1' => '123-fff', 'uuid2' => '456-ddd']);

$results = $client->runStack($stack);

标记您的Cypher语句

有时，您可能希望从堆栈中检索特定的结果，一种简单的方法是标记您的Cypher语句。

标记通过run或push方法的第三个参数传递

$stack = $client->stack();

$stack->push('CREATE (n:Person {uuid: {uuid} })', ['uuid' => '123-fff'], 'user_create');
$stack->push('MATCH (n:Person {uuid: {uuid1} }), (n2:Person {uuid: {uuid2} }) MERGE (n)-[r:FOLLOWS]->(n2) RETURN id(r) as relId', ['uuid1' => '123-fff', 'uuid2' => '456-ddd'], 'user_follows');

$results = $client->runStack($stack);

$followResult = $results->get('user_follows');
$followRelationshipId = $followResult->getRecord()->value('relId');

处理结果集

基础

run方法返回一个单独的Result对象。其他可以期望返回多个结果的方法返回一个可遍历的ResultCollection对象。

Result对象包含语句的records和summary，API中提供了以下方法：

$result->firstRecord(); // Returns the first record of the Statement Result

$result->records(); // Returns all records

$result->summarize(); // Returns the ResultSummary

摘要

ResultSummary包含Statement、统计信息以及可选的查询计划

$summary = $result->summarize();

$query = $summary->statement()->text();

$stats = $summary->updateStatistics();

$nodesUpdated = $stats->nodesUpdated();
$propertiesSet = $stats->propertiesSet();

// Does the statement affected the graph ?
$affected = $stats->containsUpdates();

记录值

每个记录包含Cypher查询返回的一行值

$query = 'MATCH (n:Person) n, n.name as name, n.age as age';
$result = $client->run($query);

foreach ($result->records() as $record) {
    print_r($record->get('n')); // nodes returned are automatically hydrated to Node objects

    echo $record->value('name') . PHP_EOL;
    echo $record->value('age') . PHP_EOL;
}

客户端负责将图对象水分解为PHP对象，因此对于节点、关系和路径都是如此

节点

• labels()：返回一个标签（字符串）数组
• identity()：返回节点的内部ID
• values()：返回节点的属性（数组）
• value($key)：返回给定属性键的值
• hasValue($key)：返回节点是否有给定键的属性
• keys()：返回一个表示节点属性键的数组
• hasLabel($label)：返回节点是否有给定的标签（布尔值）

关系

• type()：返回关系类型
• identity()：返回关系的内部ID
• values()：返回关系的属性（数组）
• value($key)：返回给定属性键的值
• hasValue($key)：返回关系是否有给定键的属性
• keys()：返回一个表示关系属性键的数组
• startNodeIdentity：返回起始节点ID
• endNodeIdentity：返回结束节点ID

路径

• start()：返回路径的起始节点
• end()：返回路径的结束节点
• length()：返回路径的长度
• nodes()：返回路径中的所有节点
• relationships：返回路径中的所有关系

处理结果（从v3到v4）

此主题有三个主要概念

1. 结果
2. 记录
3. 记录值

让我们看看浏览器中执行的一个包含多种类型可能性的查询。

MATCH (n:Address)
RETURN n.address as addr, n, collect(id(n)) as ids
LIMIT 5

结果

结果是一组记录对象，你能在浏览器中看到的每一行都是记录，它包含记录值。

• 蓝色表示结果
• 橙色表示记录
• 绿色表示记录值

记录

与客户端的先前版本相比，不再自动将所有记录合并为一个大的记录，因此您需要遍历结果中的所有记录。

$query = 'MATCH (n:Address)
RETURN n.address as addr, n, collect(id(n)) as ids
LIMIT 5';
$result = $client->run($query);

foreach ($result->records() as $record) {
  // here we do what we want with one record (one row in the browser result)
  print_r($record);
}

记录值

每个记录包含一个记录值的集合，这些值通过一个键来标识，键是您在Cypher查询的RETURN子句中给出的标识符。在我们的例子中，一个记录将包含以下键

• addr
• n
• ids

为了访问值，您可以在记录对象上使用get()方法。

$address = $record->get('addr');

值的类型取决于您从Neo4j返回的内容，在我们的情况下，将返回以下值

• addr值为字符串
• n值为节点
• ids值为整数的数组

这意味着

$record->get('addr'); // returns a string
$record->get('n'); // returns a Node object
$record->get('ids'); // returns an array

节点、关系和路径对象有进一步的方法，因此如果您知道由标识符n返回的节点具有countries属性，您可以这样访问它

$addressNode = $record->get('n');
$countries = $addressNode->value('countries');

记录对象包含三个用于IDE友好性的方法，即

$record->nodeValue('n');
$record->relationshipValue('r');
$record->pathValue('p');

这并没有提供额外的东西，只是docblocks为IDE的自动完成提供了提示。

额外：结果集合

当您使用堆栈对象一次性发送多个语句时，它将返回一个包含多个结果的结果集合对象。因此，在访问记录之前，您需要遍历结果。

使用事务

客户端提供了一个Transaction对象，它简化了您使用事务的方式。

创建事务

$tx = $client->transaction();

在这个阶段，还没有将任何内容发送到服务器（尚未发送BEGIN语句），这允许在提交之前堆叠查询或堆栈对象。

堆叠查询

$tx->push('CREATE (n:Person) RETURN id(n)');

再次，到目前为止，还没有发送任何内容。

在事务中运行查询

有时您想立即获得事务内语句的结果，这可以通过run方法完成

$result = $tx->run('CREATE (n:Person) SET n.name = {name} RETURN id(n)', ['name' => 'Michal']);

echo $result->getRecord()->value("id(n)");

如果事务尚未开始，事务的BEGIN将自动执行。

您也可以推送或运行堆栈

$stack = $client->stack();
$stack->push('CREATE (n:Person {uuid: {uuid} })', ['uuid' => '123-fff']);
$stack->push('MATCH (n:Person {uuid: {uuid1} }), (n2:Person {uuid: {uuid2} }) MERGE (n)-[:FOLLOWS]->(n2)', ['uuid1' => '123-fff', 'uuid2' => '456-ddd']);

$tx->pushStack($stack);
// or
$results = $tx->runStack($stack);

提交和回滚

如果您在事务中已排队语句（那些使用push方法添加的）并且已完成您的任务，您可以提交事务并接收结果

$stack = $client->stack();
$stack->push('CREATE (n:Person {uuid: {uuid} })', ['uuid' => '123-fff']);
$stack->push('MATCH (n:Person {uuid: {uuid1} }), (n2:Person {uuid: {uuid2} }) MERGE (n)-[:FOLLOWS]->(n2)', ['uuid1' => '123-fff', 'uuid2' => '456-ddd']);

$tx->pushStack($stack);
$tx->pushQuery('MATCH (n) RETURN count(n)');

$results = $tx->commit();

提交后，您将无法在此事务中push或run语句。

处理多个连接

一般来说，您最好在集群环境中使用HAProxy来运行Neo4j。然而，有时对发送语句的实例拥有完全控制权是有意义的。

让我们假设一个包含3个neo4j节点的环境

$client = ClientBuilder::create()
    ->addConnection('node1', 'bolt://10.0.0.1')
    ->addConnection('node2', 'bolt://10.0.0.2')
    ->addConnection('node3', 'bolt://10.0.0.3')
    ->setMaster('node1')
    ->build();

默认情况下，$client->run()命令将您的Cypher语句发送到列表中注册的第一个连接。

您可以通过指定其别名作为run参数的第四个参数来指定要将语句发送到哪个连接。

$result = $client->run('CREATE (n) RETURN n', null, null, 'node1');

客户端也了解手动配置的主连接，因此使用以下方法发送您的写入数据会更简单：

$client->runWrite('CREATE (n:User {login: 123})');

辅助方法

$client->getLabels();

返回一个Label对象的数组。

事件分发

在run方法期间分发了3种类型的事件

• PreRunEvent：在执行语句或堆栈之前。
• PostRunEvent：在执行语句或堆栈之后。
• FailureEvent：在出现失败的情况下，您可以使用此事件禁用客户端抛出异常。

注册监听器

示例

$client = ClientBuilder::create()
    ->addConnection('default', 'bolt://localhost')
    ->registerEventListener(Neo4jClientEvents::NEO4J_PRE_RUN, array($listener, 'onPreRun')
    ->build();

事件分发器可以通过客户端的$client->getEventDispatcher方法获得。

设置

超时（已弃用）

您可以为连接配置一个全局超时。

$client = ClientBuilder::create()
    ->addConnection('default', 'http://localhost:7474')
    ->setDefaultTimeout(3)
    ->build();

默认超时时间为5秒。

此功能已弃用，将在版本5中删除。请参阅以下HTTP客户端设置。

TLS

您可以在构建连接时通过传递一个Configuration实例来启用Bolt协议的TLS加密，以下是一个简单的示例：

$config = \GraphAware\Bolt\Configuration::newInstance()
    ->withCredentials('bolttest', 'L7n7SfTSj')
    ->withTLSMode(\GraphAware\Bolt\Configuration::TLSMODE_REQUIRED);

$client = ClientBuilder::create()
    ->addConnection('default', 'bolt://hodccomjfkgdenl.dbs.gdb.com:24786', config)
    ->build();

HTTP客户端设置

我们使用HTTPlug为您提供对HTTP客户端的完全控制。Neo4jClient的版本4默认包含Guzzle6以保持向后兼容。版本5将为您提供选择任何客户端的选项。有关HTTPlug的更多信息，请参阅他们的文档。

要配置您的客户端，您可能需要将其添加到Configuration。以下是一个使用php-http/curl-client的示例。

use Http\Client\Curl\Client;

$options = [
    CURLOPT_CONNECTTIMEOUT => 3, // The number of seconds to wait while trying to connect.
    CURLOPT_SSL_VERIFYPEER => false // Stop cURL from verifying the peer's certificate
];
$httpClient = new Client(null, null, $options);

$config = \GraphAware\Neo4j\Client\HttpDriver\Configuration::create($httpClient);
$client = ClientBuilder::create()
    ->addConnection('default', 'http://neo4j:password@localhost:7474', $config)
    ->build();

许可

此库根据MIT许可证发布，请参阅此包捆绑的LICENSE文件。