Download the PHP package vinelab/neoclient without Composer

NeoClient

This repository has moved

Neoxygen's NeoClient has been moved to https://github.com/graphaware/neo4j-php-client

Version 3 of this library is still maintained for bug support for the users requiring neoxygen/neoclient in their composer's dependencies.

Version 3 End of Maintenance is planned on September 1, 2016.

Version 4 (with support for the Bolt binary protocol - in current developement) will only be available on the GraphAware's repository.

If you are having issues for the migration, you can open an issue here : https://github.com/graphaware/neo4j-php-client/issues

GraphAware's Enterprise customers can send a direct support email to their first level of support at GraphAware.

A PHP HttpClient for the Neo4j ReST API with MultiDB Support

Supported and Sponsored By

Introduction

NeoClient is the most advanced and flexible Neo4j Client for PHP.

What is Neo4j?

Neo4j is a transactional, open-source graph database. A graph database manages data in a connected data structure, capable of representing any kind of data in a very accessible way. Information is stored in nodes and relationships connecting them, both of which can have arbitrary properties. To learn more visit What is a Graph Database?

Key features

• Supports multiple connections
• Built-in and automatic support for Neo4j Enterprise HA Master-Slave Mode with auto slaves fallback
• Fully extensible (You can create your own extensions)

Neo4j Version Support

Neo4j Feature Support

Requirements

• PHP 5.5+
• A Neo4j database (minimum version 2.1.6)

Getting Help

You can:

• Check out an example application build with NeoClient
• Ask a question on StackOverflow
• Chat with us on Gitter: 
• For bugs, please feel free to create a new issue on GitHub

Installation and basic usage

Installation

Add the library to your composer dependencies :

Require the composer autoloader, configure your connection by providing a connection alias and your connection settings :

You're now ready to connect to your database.

If you use default database settings in a local environment (meaning http://localhost:7474), you can use the handy addDefaultLocalConnection method :

The build method will process configuration settings and return you a Client instance.

Configuring the connection timeout

You can configure the default timeout during the build process :

Usage

You have now full access to the database.

getRoot | Returns the root endpoint

Note: As the library provide full support for working with multiple databases, each method explained in the documentation can take a $conn parameter which you can use to define on which connection you want to execute the method. The default connection will be used when the parameter is not set.

For more information on how to set up multiple connections, read the Multiple connections section of the documentation.

getNeo4jVersion | Returns the Neo4j version of the current connection

Sending Cypher Queries

In order to send a Cypher Query, you need to pass the query as a string, and an optional array of paramaters as arguments :

`

Handling such response format is not really practical and boring. You can ask the client to format the response in a pretty way and have this format available to you :

To get the pretty format :

Labels, Indexes and Constraints Management

Managing labels

The library provide handy methods for managing your labels :

getLabels | Returns the labels indexed in the database

renameLabel | Fetch all nodes for that label and rename the label of the nodes

Note that depending on the amount of nodes for the given label, this can take some time.

Call the renameLabel method and pass the old label name and the new label name as arguments :

Managing Indexes and Constraints

Indexes and Constraints management is also an easy task

createIndex | Creates an index for a label/property pair

listIndex | List indexed properties for a given label

Returns you an array of indexed properties for the given label

listIndexes | List indexed properties for given labels or all labels

Returns you an array of indexed properties by the form ['Label' => ['prop1','prop2']].

dropIndex | Drop an index for a given label/property pair

isIndexed | Checks whether or not a given label/property pair is indexed

Returns true or false

createUniqueConstraint | Create a uniqueness constraint for a given label/property pair

If an index already exist on the combination Label, property you can ask the client to drop the index and create the constraint instead of throwing an exception, just pass true as a third parameter.

dropUniqueConstraint | Drop a uniqueness constraint for a given label/property pair

getUniqueConstraints | Returns all the uniqueness constraints by label

Returns ['User' => ['username','email'], 'Movie' => ['imdb_id']]

Handling Graph Results

The Response Formatter will format graph results in a pretty format of nodes and relationships objects.

If you've setup the autoFormatResponse configuration value, when a graph result is available, a graph representation is available for you :

Using get

Commonly, you'll use identifiers in your return statements, you can access them in an easy way :

Results in table format

Sometimes you will deal with results in table format, there is a dedicated method getTableFormat that will format the results for you :

Sending multiple statements in one transaction

There are 2 ways for sending multiple statements in one and only transaction.

1. Using an open transaction throughout the process (see the next section "Transaction Management")
2. Using a PreparedTransaction instance

PreparedTransaction

Handy if you want to keep a PreparedTransaction instance throughout your code :

Transaction Management

The library comes with a Transaction Manager removing you the burden of parsing commit urls and transaction ids.

Usage is straightforward :

Note that a commited or a rolled back transaction will not accept pushQuery calls anymore.

Working with multiple connections

Define multiple connections

You can work with as many connections you want :

When calling commands, you can specify to which connection the command has to be executed by passing the connection alias as argument :

HA (High-Availibilty)

HA Mode for Neo4j Enterprise

NB: There are ongoing changes for improving the HA Mode of the Enterprise Edition, stay tuned ;-)

The library provide a powerful system for handling the HA Mode of Neo4j available in Neo4j Enterprise.

The convention is to send write queries to the master, and read queries to slaves.

To enable the HA Mode and defining which connections are master or slave, you need to add some method call during the build process of the client :

Your configuration is now set. The client has convenience methods for HA usage, respectively sendReadQuery and sendWriteQuery.

Automatically, write queries will be executed against the master connection, while read queries against slave connections.

If a slave is no more reachable, it will automatically check if other slaves are configured. If yes it will attempt to send the query again to the other slave connections.

If you have loggers settled up, an alert entry will be logged to inform you of slave connection failure.

NB: The above methods do not take the $conn argument as the choice of the connection is done in the library internals.

Note: You can always retrieve the Master and the first Slave connection alias from the client if you want to specify them when using other commands :

Please also note, that when using the Transaction Manager, all queries will be run against the same connection. Transaction instances are bounded to one and only connection.

Checking your Master/Slave Configuration

You can check that your defined master and slaves connections are running and setup correctly :

Query Mode Headers

When the High Availibity Mode is enabled, an additional header will be set to the http request. This header defines the query mode of the transaction : READ or WRITE.

By default, all queries, live transactions and prepared transactions are assumed WRITE.

You can define it your self by using the Client's constants Client::NEOCLIENT_QUERY_MODE_WRITE and Client::NEOCLIENT_QUERY_MODE_READ or by simply passing a string with those values to the following methods:

The default headers are the following :

• The header key is Neo4j-Query-Mode
• The write transactions will have a header value of : NEO4J_QUERY_WRITE
• The read transactions will have a header value of : NEO4J_QUERY_READ

You can define your own headers definition via the configuration :

yaml

php

Secured connections

Authenticated connection

For Neo4j 2.2

Provide the user and the password when building the connection :

changing the password

The client has a built-in method for changing the password :

Before Neo4j 2.2 using the Auth Extension

If you are using the authenticated-extension or using GrapheneDB instance, you can specify to use the authMode for the connection and provide your username and password :

Your password will automatically be encoded in base64 for the Authorization.

Convenience methods for the Authentication extension

listUsers | List the users registered in the connection authentication extension

addUser | Adds a user to the extensions

The third argument of the addUser method is the readOnly parameter, default to false

removeUser | Removes a user from the extension

Events & Logging

Event Listeners

You can add listeners to hook into the built-in event system, for all list of all available events, look inside the NeoEvents.php file.

A listener can be a \Closure instance, an object implementing an __invoke method, a string representing a function, or an array representing an object method or a class method.

Event listeners are currently not configurable with the yaml file, it will come soon...

Logging

You can add your logging system or ask the library to use the default built-in logging mechanism (currently only stream and ChromePHP are supported).

If you integrate your own logging, he must be compatible with the PSR-3 standard.

The library is shipped with two default Monolog handlers that you can use : Stream and ChromePHP. Registering them is straightforward :

Extending NeoClient

Creating your own commands

You can extend the library by creating your own commands.

Create your Command class, this class must extend Neoxygen\NeoClient\Command\AbstractCommand and must implement the execute method.

By extending the AbstractCommand class, you have access to the http client, and also the connection alias that is used when invoking the command.

The best way to execute a command is by calling the send request of the HttpClient and passing the method, path, body and connectionAlias arguments :

Then you have to register your command when building the client by passing an alias for your command and the class FQDN :

Then to use your command, just use the invoke method of the client :

Creating an Extension

When you have a lot of commands, it may be good to create a command extension. Creating a command extension is quite simple :

You need to create a class that extends the Neoxygen\NeoClient\Extension\AbstractExtension, and you have to implement the getAvailableCommands method that return an array of command aliases bounded to command classes :

And then register your extension when building the client by giving an alias and the class FQDN of your extension :

Production settings

The library uses a Dependency Injenction Container and service files definitions, while this provide full flexibility and robust code, this comes at a price.

By providing a cache path where the container and all the configuration can be dumped, you'll have the best of both worlds.

Don't forget to add full permissions to the cache path : chmod -R 777 your/cache/path and also to empty the cache dir when you do changes to your configuration.

Configuration Reference

YAML

License

The library is released under the MIT License, refer to the LICENSE file.

Tests

To run the test suite, you need to copy the tests/database_settings.yml.dist to tests/database_settings.yml, as it will create nodes to a real database.

Run vendor/bin/phpunit