Skip to content

Commit 1001515

Browse files
stefanak-michalstefanak-michal
authored
revised. updated..
1 parent 605ef9b commit 1001515

File tree

1 file changed

+69
-76
lines changed

1 file changed

+69
-76
lines changed

‎README.md‎

Lines changed: 69 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,7 @@
22

33
# Bolt
44

5-
PHP library for communication with graph database over TCP socket with Bolt protocol specification. Bolt protocol was
6-
created by [Neo4j](https://neo4j.com/) and documentation is available
7-
at [https://www.neo4j.com/](https://www.neo4j.com/docs/bolt/current/). This library is aimed to be low level, support
5+
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
86
all available versions and keep up with protocol messages architecture and specifications.
97

108
[![](https://img.shields.io/github/stars/stefanak-michal/Bolt)](https://github.com/neo4j-php/Bolt/stargazers)
@@ -16,28 +14,24 @@ all available versions and keep up with protocol messages architecture and speci
1614

1715
<a href='https://jb.gg/OpenSourceSupport' target='_blank'><img src="https://resources.jetbrains.com/storage/products/company/brand/logos/jb_beam.png" alt="JetBrains Logo (Main) logo." width="100" /></a>
1816

19-
## Version support
17+
## :label: Version support
2018

2119
We are trying to keep up and this library supports **Bolt <= 5.4**.
2220

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

25-
## Requirements
23+
## :white_check_mark: Requirements
2624

27-
Keep up with [PHP supported versions](https://www.php.net/supported-versions.php) means we are at **PHP^8.1**.
25+
This library keep up with [PHP supported versions](https://www.php.net/supported-versions.php) what means it is at **PHP^8.1**.
2826

29-
_If you need support for end-of-life PHP versions, here is a short list: PHP < 7.4 - v3.x, PHP 7.4 - v5.x, PHP 8.0 - v6.x
30-
Not all new features are implement backwards and this readme is updated to latest released version._
31-
32-
### Extensions
27+
### PHP Extensions
3328

3429
- [mbstring](https://www.php.net/manual/en/book.mbstring.php)
3530
- [sockets](https://www.php.net/manual/en/book.sockets.php) (optional) - Required when you use Socket connection class
3631
- [openssl](https://www.php.net/manual/en/book.openssl.php) (optional) - Required when you use StreamSocket connection
3732
class with enabled SSL
38-
- [phpunit](https://phpunit.de/) (development)
3933

40-
## Installation
34+
## :floppy_disk: Installation
4135

4236
You can use composer or download this repository from github and manually implement it.
4337

@@ -55,52 +49,14 @@ Run the following command in your project to install the latest applicable versi
5549
2. Unpack
5650
3. Copy content of `src` directory into your project
5751

58-
## Usage
52+
## :desktop_computer: Usage
5953

60-
Concept of usage is based on Bolt messages. Available protocol methods depends on Bolt version. Communication works
61-
in [pipeline](https://www.neo4j.com/docs/bolt/current/bolt/message/#pipelining) and you can chain multiple Bolt messages
62-
before fetching response from the server.
54+
Concept of usage is based on Bolt messages. Bolt messages are mapped 1:1 as protocol methods. 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 consuming response from the server.
6355

64-
Main `Bolt` class serves as Factory design pattern and it returns instance of protocol class by requested Bolt version. Query execution and fetching response is split in two methods. First message `run` is for
65-
sending queries. Second message `pull` is for fetching response from last executed query on database.
66-
Response from database for Bolt message `pull` always contains n+1 rows because last entry is `success` message with
56+
Main `Bolt` class serves as Factory design pattern and it returns instance of protocol class by requested Bolt version. Basic usage consist of query execution and fetching response which is split in two methods. First message `run` is for sending queries. Second message `pull` is for fetching response from executed query on database. Response from database for Bolt message `pull` always contains n+1 rows because last entry is `success` message with
6757
meta informations.
6858

69-
More info about available Bolt messages: https://www.neo4j.com/docs/bolt/current/bolt/message/
70-
71-
### Example
72-
73-
```php
74-
// Choose and create connection class and specify target host and port.
75-
$conn = new \Bolt\connection\Socket('127.0.0.1', 7687);
76-
// Create new Bolt instance and provide connection object.
77-
$bolt = new \Bolt\Bolt($conn);
78-
// Set requested protocol versions ..you can add up to 4 versions
79-
$bolt->setProtocolVersions(5.4);
80-
// Build and get protocol version instance which creates connection and executes handshake.
81-
$protocol = $bolt->build();
82-
83-
// Initialize communication with database
84-
$response = $protocol->hello()->getResponse();
85-
// verify $response for successful initialization
86-
87-
// Login into database
88-
$response = $protocol->logon(['scheme' => 'basic', 'principal' => 'neo4j', 'credentials' => 'neo4j'])->getResponse();
89-
// verify $response for successful login
90-
91-
// Pipeline two messages. One to execute query with parameters and second to pull records.
92-
$protocol
93-
->run('RETURN $a AS num, $b AS str', ['a' => 123, 'b' => 'text'])
94-
->pull();
95-
96-
// Fetch waiting server responses for pipelined messages.
97-
foreach ($protocol->getResponses() as $response) {
98-
// $response is instance of \Bolt\protocol\Response.
99-
// First response is SUCCESS message for RUN message.
100-
// Second response is RECORD message for PULL message.
101-
// Third response is SUCCESS message for PULL message.
102-
}
103-
```
59+
:information_source: More info about available Bolt messages: https://www.neo4j.com/docs/bolt/current/bolt/message/
10460

10561
### Available methods
10662

@@ -137,12 +93,12 @@ foreach ($protocol->getResponses() as $response) {
13793
| pullAll | @see pull | |
13894
| discardAll | @see discard | |
13995

140-
Many methods accept argument called `$extra`. This argument can contain any of key-value by Bolt specification. This
96+
Multiple methods accept argument called `$extra`. This argument can contain any of key-value by Bolt specification. This
14197
argument was extended during Neo4j development which means the content of it changed. You should keep in mind what
14298
version you are working with when using this argument. You can read more about extra parameter in Bolt documentation
14399
where you can look into your version and bolt message.
144100

145-
Annotation of methods in protocol classes contains direct link to specific version and message from mentioned
101+
:information_source: Annotation of methods in protocol classes contains direct link to specific version and message from mentioned
146102
documentation website.
147103

148104
### Authentification
@@ -184,52 +140,81 @@ of data. To learn more you can
184140
check [performance test](https://github.com/neo4j-php/Bolt/blob/master/tests/PerformanceTest.php)
185141
or [packer test](https://github.com/neo4j-php/Bolt/blob/master/tests/PackStream/v1/PackerTest.php).
186142

187-
Structures `Node`, `Relationship`, `UnboundRelationship` and `Path` cannot be used as parameter. They are available only
143+
:warning: Structures `Node`, `Relationship`, `UnboundRelationship` and `Path` cannot be used as parameter. They are available only
188144
as received data from database.
189145

146+
### Example
147+
148+
```php
149+
// Choose and create connection class and specify target host and port.
150+
$conn = new \Bolt\connection\Socket('127.0.0.1', 7687);
151+
// Create new Bolt instance and provide connection object.
152+
$bolt = new \Bolt\Bolt($conn);
153+
// Set requested protocol versions ..you can add up to 4 versions
154+
$bolt->setProtocolVersions(5.4);
155+
// Build and get protocol version instance which creates connection and executes handshake.
156+
$protocol = $bolt->build();
157+
158+
// Initialize communication with database
159+
$response = $protocol->hello()->getResponse();
160+
// verify $response for successful initialization
161+
162+
// Login into database
163+
$response = $protocol->logon(['scheme' => 'basic', 'principal' => 'neo4j', 'credentials' => 'neo4j'])->getResponse();
164+
// verify $response for successful login
165+
166+
// Pipeline two messages. One to execute query with parameters and second to pull records.
167+
$protocol
168+
->run('RETURN $a AS num, $b AS str', ['a' => 123, 'b' => 'text'])
169+
->pull();
170+
171+
// Fetch waiting server responses for pipelined messages.
172+
foreach ($protocol->getResponses() as $response) {
173+
// $response is instance of \Bolt\protocol\Response.
174+
// First response is SUCCESS message for RUN message.
175+
// Second response is RECORD message for PULL message.
176+
// Third response is SUCCESS message for PULL message.
177+
}
178+
```
179+
190180
### Autoload
191181

192182
Directory `src` contains autoload file which accepts only Bolt library namespaces. Main Bolt namespace points to this
193183
directory. If you have installed this project with composer, you have to load `vendor/autoload.php`.
194184

195-
## Server state
185+
## :vertical_traffic_light: Server state
196186

197-
Server state is not reported by server but it is evaluated by received response. You can access current state through `$protocol->serverState`. This property is updated with every call `getResponse(s)`.
187+
Server state is not reported by server but it is evaluated by received response. You can access current state through property `$protocol->serverState`. This property is updated with every call `getResponse(s)`.
198188

199-
## Connection
189+
## :chains: Connection
200190

201-
Bolt class constructor accepts connection argument. This argument has to be instance of class which implements
202-
IConnection interface. Currently exists two predefined classes `Socket` and `StreamSocket`.
203-
204-
_We provide two connection classes. `Socket` was created first and it has better memory usage. `StreamSocket` was made
205-
because of need to accept TLS._
191+
Bolt class constructor accepts connection argument. This argument has to be instance of class which implements IConnection interface. Library offers few options.
206192

207193
**\Bolt\connection\Socket**
208194

209-
This class use php extension sockets. More informations
195+
This class use php extension sockets and has better memory usage. More informations
210196
here: [https://www.php.net/manual/en/book.sockets.php](https://www.php.net/manual/en/book.sockets.php)
211197

212198
**\Bolt\connection\StreamSocket**
213199

214200
This class uses php stream functions. Which is a part of php and there is no extensions needed. More informations
215201
here: [https://www.php.net/manual/en/ref.stream.php](https://www.php.net/manual/en/ref.stream.php)
216202

217-
StreamSocket besides of implemented methods from interface has method to configure SSL. When you want to activate SSL
203+
StreamSocket besides of implemented methods from interface has method to configure SSL. SSL option requires php extension openssl. When you want to activate SSL
218204
you have to call method `setSslContextOptions`. This method accept array by php specification available
219205
here: [https://www.php.net/manual/en/context.ssl.php](https://www.php.net/manual/en/context.ssl.php).
220206

221-
_If you want to use it, you have to enable openssl php extension._
222-
223207
**\Bolt\connection\PStreamSocket**
224208

225-
This class extends StreamSocket and adds support for persistent connections.
209+
This class extends StreamSocket and adds support for persistent connections. Upon reuse of connection remaining buffer is consumed and message RESET is automatically sent. PHP is stateless therefore using this connection class requires storing meta information about active TCP connection. Default storage is `\Bolt\helper\FileCache` which you can change with method `setCache` (PSR-16 Simple Cache).
226210

227-
todo add more description, maybe copy it from class annotation
211+
:warning: If your system reuse persistent connection and meta information about it was lost for some reason, your attemt to connect will end with ConnectionTimeoutException. Repeated attempt to connect will succeed.
212+
213+
## :lock: SSL
228214

229215
### Neo4j Aura
230216

231-
Connecting to Aura requires encryption which is provided with SSL. To connect to Aura you have to use `StreamSocket`
232-
connection class and enable SSL.
217+
Connecting to Aura requires encryption which is provided with SSL. To connect to Aura you have to use `StreamSocket` connection class and enable SSL.
233218

234219
```php
235220
$conn = new \Bolt\connection\StreamSocket('helloworld.databases.neo4j.io');
@@ -257,18 +242,18 @@ $conn->setSslContextOptions([
257242
$bolt = new \Bolt\Bolt($conn);
258243
```
259244

260-
You can also take a look at my article on how to implement SSL for Neo4j running on localhost
245+
:bookmark: You can also take a look at my article on how to implement SSL for Neo4j running on localhost
261246
at [Neo4j and self signed certificate](https://ko-fi.com/post/Neo4j-and-self-signed-certificate-on-Windows-S6S2I0KQT).
262247

263-
### Timeout
248+
## :stopwatch: Timeout
264249

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

268253
_Setting up ini directive isn't part of connection class because function `ini_set` can be disabled on production
269254
environments for security reasons._
270255

271-
## Another solutions
256+
## :pushpin: More solutions
272257

273258
If you need simple class to cover basic functionality you can
274259
use: [neo4j-bolt-wrapper](https://packagist.org/packages/stefanak-michal/neo4j-bolt-wrapper)
@@ -279,3 +264,11 @@ on: [php-client](https://packagist.org/packages/laudis/neo4j-php-client)
279264
PDO implementation is available at [pdo-bolt](https://github.com/stefanak-michal/pdo-bolt)
280265

281266
More informations can be found at: https://neo4j.com/developer/php/
267+
268+
## :recycle: Old versions
269+
270+
If you need support for end-of-life PHP versions, here is a short info list. Not all new features are implement backwards and this readme is updated to latest released version.
271+
272+
* PHP < 7.4 - v3.x
273+
* PHP 7.4 - v5.x
274+
* PHP 8.0 - v6.x

0 commit comments

Comments
 (0)