Skip to content

Commit 0ceeee6

Browse files
stefanak-michalstefanak-michal
committed
updated readme to the latest changes and implemented info from wiki
1 parent 37d4bd9 commit 0ceeee6

File tree

1 file changed

+130
-35
lines changed

1 file changed

+130
-35
lines changed

‎README.md‎

Lines changed: 130 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
![Logo](https://repository-images.githubusercontent.com/198229221/fcf334aa-ef6b-4fe9-89ad-d03e4c7d89e3)
22

33
# Bolt
4-
PHP library for communication with [Neo4j](https://neo4j.com/) graph database over TCP socket with Bolt protocol specification. The Bolt documentation is available at [https://www.neo4j.com/](https://www.neo4j.com/docs/bolt/current/). This library is aimed to be low level, support all available versions and keep up with protocol messages architecture and specifications.
4+
PHP library for communication with graph database over TCP socket with Bolt protocol specification. Bolt protocol was created by [Neo4j](https://neo4j.com/) and documentation is available at [https://www.neo4j.com/](https://www.neo4j.com/docs/bolt/current/). This library is aimed to be low level, support all available versions and keep up with protocol messages architecture and specifications.
55

66
![DB Tests PHP7](https://github.com/neo4j-php/Bolt/actions/workflows/db-test-php-7.yml/badge.svg?branch=master)
77
![DB Tests PHP8](https://github.com/neo4j-php/Bolt/actions/workflows/db-test-php-8.yml/badge.svg?branch=master)
@@ -13,17 +13,19 @@ PHP library for communication with [Neo4j](https://neo4j.com/) graph database ov
1313
[![](https://img.shields.io/github/v/release/stefanak-michal/bolt)](https://github.com/neo4j-php/Bolt/releases)
1414
[![](https://img.shields.io/github/commits-since/stefanak-michal/bolt/latest)](https://github.com/neo4j-php/Bolt/releases/latest)
1515

16+
<a href='https://ko-fi.com/Z8Z5ABMLW' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://cdn.ko-fi.com/cdn/kofi1.png?v=3' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a>
17+
1618
## Version support
1719

18-
We are trying to keep up and this library supports **Neo4j <= 4.4** with **Bolt <= 4.4**.
20+
We are trying to keep up and this library supports **Neo4j <= 5.1** with **Bolt <= 5.1**.
1921

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

2224
## Requirements
2325

2426
Keep up with [PHP supported versions](https://www.php.net/supported-versions.php) means we are at **PHP >= 7.4**.
2527

26-
_If you need support for PHP < 7.4 you can use latest v3.x release. Not all new features are implement backwards._
28+
_If you need support for PHP < 7.4 you can use latest v3.x release. Not all new features are implement backwards and this readme is updated to latest released version._
2729

2830
### Extensions
2931

@@ -52,28 +54,74 @@ Run the following command in your project to install the latest applicable versi
5254

5355
## Usage
5456

55-
Concept of usage is based on Bolt messages. Available protocol methods depends on Bolt version.
57+
Concept of usage is based on Bolt messages. Available protocol methods depends on Bolt version. Communication works in [pipeline](https://www.neo4j.com/docs/bolt/current/bolt/message/#pipelining) and you can chain multiple Bolt messages before fetching response from the server.
58+
59+
Main `Bolt` class serves as Factory design pattern and it returns instance of protocol class by requested Bolt version (default is 4 latest versions). Query execution and fetching response is split in two methods. First message `run` is for sending queries. Second message `pull` is for fetching response from last executed query on database.
60+
Response from database for Bolt message `pull` always contains n+1 rows because last entry is `success` message with meta informations.
61+
62+
More info about available Bolt messages: https://www.neo4j.com/docs/bolt/current/bolt/message/
5663

57-
https://www.neo4j.com/docs/bolt/current/bolt/message/
64+
### Example
5865

5966
```php
60-
// Create connection class and specify target host and port
61-
$conn = new \Bolt\connection\Socket();
62-
// Create new Bolt instance and provide connection object
67+
// Create connection class and specify target host and port.
68+
$conn = new \Bolt\connection\Socket('127.0.0.1', 7687);
69+
// Create new Bolt instance and provide connection object.
6370
$bolt = new \Bolt\Bolt($conn);
64-
// Build and get protocol version instance which creates connection and executes handshake
71+
// Build and get protocol version instance which creates connection and executes handshake.
6572
$protocol = $bolt->build();
66-
// Login to database with credentials
73+
// Login to database with credentials.
6774
$protocol->hello(\Bolt\helpers\Auth::basic('neo4j', 'neo4j'));
68-
// Execute query with parameters
69-
$stats = $protocol->run('RETURN $a AS num, $b AS str', ['a' => 123, 'b' => 'text']);
70-
// Pull records from last executed query
71-
$rows = $protocol->pull();
72-
```
7375

74-
Response from database (`$rows`) always contains n+1 rows because last entry are meta informations.
76+
// Pipeline two messages. One to execute query with parameters and second to pull records.
77+
$protocol
78+
->run('RETURN $a AS num, $b AS str', ['a' => 123, 'b' => 'text'])
79+
->pull();
80+
81+
// Fetch waiting server responses for pipelined messages.
82+
foreach ($protocol->getResponses() as $response) {
83+
// $response is instance of \Bolt\protocol\Response.
84+
// First response is SUCCESS message for RUN message.
85+
// Second response is RECORD message for PULL message.
86+
// Third response is SUCCESS message for PULL message.
87+
}
88+
```
7589

76-
[More info](https://github.com/neo4j-php/Bolt/wiki/Usage)
90+
### Available methods
91+
92+
**Bolt class**
93+
94+
| Method / Property | Description | Type | Parameters | Return |
95+
|----------------------|----------------------------------------------------------------------------------------------------|---------------|-------------------------|-----------|
96+
| __construct | Bolt constructor | public | IConnection $connection | Bolt |
97+
| setProtocolVersions | Set allowed protocol versions for connection | public | int/float/string ...$v | Bolt |
98+
| setPackStreamVersion | Set PackStream version | public | int $version = 1 | Bolt |
99+
| build | Create protocol instance. Method creates connection, executes handshake and do a version request. | public | | AProtocol |
100+
| $debug | Print binary communication (as hex) | public static | bool | |
101+
102+
**Protocol class**
103+
104+
| Method / Property | Description | Parameters |
105+
|-------------------|-----------------------------------------------------------------------------|--------------------------------------------------------------------|
106+
| hello | Connect to database (you can use helper to provide required extra argument) | array $extra |
107+
| run | Execute query. Response from database are meta informations. | string $statement<br/>array $parameters = []<br/>array $extra = [] |
108+
| pull | Pull result from executed query | array $extra = [] |
109+
| discard | Discard result waiting for pull | array $extra = [] |
110+
| begin | Start transaction | array $extra = [] |
111+
| commit | Commit transaction | |
112+
| rollback | Rollback transaction | |
113+
| reset | Send message to reset connection | |
114+
| getVersion | Get used protocol version | |
115+
| getResponse | Get waiting response from server | |
116+
| getResponses | Get waiting responses from server | |
117+
| | | |
118+
| init | @see hello | |
119+
| pullAll | @see pull | |
120+
| discardAll | @see discard | |
121+
122+
Many methods accept argument called `$extra`. This argument can contain any of key-value by Bolt specification. This argument was extended during Neo4j development which means the content of it changed. You should keep in mind what version you are working with when using this argument. You can read more about extra parameter in Bolt documentation where you can look into your version and bolt message.
123+
124+
Annotation of methods in protocol classes contains direct link to specific version and message from mentioned documentation website.
77125

78126
### Transactions
79127

@@ -87,28 +135,55 @@ _`run` executes query in auto-commit transaction if explicit transaction was not
87135

88136
### Cypher query parameters
89137

90-
| Neo4j | PHP |
91-
| --- | --- |
92-
| Null | null |
93-
| Boolean | boolean |
94-
| Integer | integer |
95-
| Float | float |
96-
| Bytes | [Bytes class](https://github.com/neo4j-php/Bolt/blob/master/src/structures/Bytes.php) |
97-
| String | string |
98-
| List | array with consecutive numeric keys from 0 |
99-
| Dictionary | object or array which is not considered as list |
100-
| Structure | [directory with structures](https://github.com/neo4j-php/Bolt/tree/master/src/structures) |
138+
| Neo4j | PHP |
139+
|------------|-----------------------------------------------------------------------------------------------------------------------------------|
140+
| Null | null |
141+
| Boolean | boolean |
142+
| Integer | integer |
143+
| Float | float |
144+
| Bytes | [Bytes class](https://github.com/neo4j-php/Bolt/blob/master/src/structures/Bytes.php) |
145+
| String | string |
146+
| List | array with consecutive numeric keys from 0 |
147+
| Dictionary | object or array which is not considered as list |
148+
| Structure | Classes implementing `IStructure` by protocol version ([docs](https://www.neo4j.com/docs/bolt/current/bolt/structure-semantics/)) |
101149

102150
List or dictionary can be also provided as instance of class implementing `Bolt\packstream\IPackListGenerator` or `Bolt\PackStream\IPackDictionaryGenerator`. This approach helps with memory management while working with big amount of data. To learn more you can check [performance test](https://github.com/neo4j-php/Bolt/blob/master/tests/PerformanceTest.php) or [packer test](https://github.com/neo4j-php/Bolt/blob/master/tests/PackStream/v1/PackerTest.php).
103151

104-
Structures Node, Relationship, UnboundRelationship and Path cannot be used as parameter. They are available only as received data from database.
152+
Structures `Node`, `Relationship`, `UnboundRelationship` and `Path` cannot be used as parameter. They are available only as received data from database.
153+
154+
Server state is not available from server but we assume it. Library contains `\Bolt\helpers\ServerState` and you can get used instance of this class with `$bolt->serverState` or `$protocol->serverState` (after you call `build()`).
155+
156+
### Autoload
157+
158+
Directory `src` contains autoload file which accepts only Bolt library namespaces. Main Bolt namespace points to this directory. If you have installed this project with composer, you have to load `vendor/autoload.php`.
159+
160+
## Server state
161+
162+
If assumed server state is different than expected, library does not throw exception. This logic is silent but you can change it and if you would like to implement own logic when assumed server state is different than expected you can assign callable into class property `$serverState->expectedServerStateMismatchCallback`.
163+
164+
## Connection
165+
166+
Bolt class constructor accepts connection argument. This argument has to be instance of class which implements IConnection interface. Currently exists two predefined classes `Socket` and `StreamSocket`.
167+
168+
_We provide two connection classes. `Socket` was created first and it has better memory usage. `StreamSocket` was made because of need to accept TLS._
169+
170+
**\Bolt\connection\Socket**
171+
172+
This class use php extension sockets. More informations here: [https://www.php.net/manual/en/book.sockets.php](https://www.php.net/manual/en/book.sockets.php)
173+
174+
**\Bolt\connection\StreamSocket**
175+
176+
This class uses php stream functions. Which is a part of php and there is no extensions needed. More informations here: [https://www.php.net/manual/en/ref.stream.php](https://www.php.net/manual/en/ref.stream.php)
177+
178+
StreamSocket besides of implemented methods from interface has method to configure SSL. When you want to activate SSL you have to call method `setSslContextOptions`. This method accept array by php specification available here: [https://www.php.net/manual/en/context.ssl.php](https://www.php.net/manual/en/context.ssl.php).
179+
180+
_If you want to use it, you have to enable openssl php extension._
105181

106182
### Neo4j Aura
107183

108-
Connecting to Aura requires encryption which is provided with SSL. To connect to Aura you have to use StreamSocket connection class and enable SSL.
184+
Connecting to Aura requires encryption which is provided with SSL. To connect to Aura you have to use `StreamSocket` connection class and enable SSL.
109185

110186
```php
111-
// url without neo4j+s protocol
112187
$conn = new \Bolt\connection\StreamSocket('helloworld.databases.neo4j.io');
113188
// enable SSL
114189
$conn->setSslContextOptions([
@@ -119,11 +194,31 @@ $bolt = new \Bolt\Bolt($conn);
119194

120195
https://www.php.net/manual/en/context.ssl.php
121196

122-
## Another solutions
197+
### Example on localhost database with self-signed certificate:
198+
199+
```php
200+
$conn = new \Bolt\connection\StreamSocket();
201+
$conn->setSslContextOptions([
202+
'local_cert'=> 'd:\www\bolt\cert\public_cert.pem',
203+
'local_pk' => 'd:\www\bolt\cert\private_key.pem',
204+
'passphrase' => 'password',
205+
'allow_self_signed' => true,
206+
'verify_peer' => false,
207+
'verify_peer_name' => false
208+
]);
209+
$bolt = new \Bolt\Bolt($conn);
210+
```
123211

124-
https://neo4j.com/developer/php/
212+
### Timeout
125213

214+
Connection class constructor contains `$timeout` argument. This timeout is for established socket connection. To set up timeout for establishing socket connection itself you have to set ini directive `default_socket_timeout`.
126215

127-
## Support
216+
_Setting up ini directive isn't part of connection class because function `ini_set` can be disabled on production environments for security reasons._
128217

129-
<a href='https://ko-fi.com/Z8Z5ABMLW' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://cdn.ko-fi.com/cdn/kofi1.png?v=3' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a>
218+
## Another solutions
219+
220+
If you need simple class to cover basic functionality you can use: [neo4j-bolt-wrapper](https://packagist.org/packages/stefanak-michal/neo4j-bolt-wrapper)
221+
222+
When you are in need of enterprise level take a look on: [php-client](https://packagist.org/packages/laudis/neo4j-php-client)
223+
224+
More solutions can be found at: https://neo4j.com/developer/php/

0 commit comments

Comments
 (0)