 |
VOOZH | about |
|
VOOZH | about |
This document covers installation requirements, setup procedures, and basic usage patterns for establishing connections and executing queries with the Bolt PHP library. For detailed architecture information, see Core Architecture. For advanced connection configuration including SSL/TLS and persistent connections, see Connection Management.
The Bolt library requires PHP 8.1 or higher and follows PHP supported versions. The library maintains compatibility with Neo4j 4.4 through 2025.x releases, as well as Memgraph, Amazon Neptune, DozerDB, ONgDB, LadybugDB, and NornicDB.
Required PHP Extensions:
mbstring - Multi-byte string operations for binary data handlingcurl - HTTP client for analytics submissionOptional PHP Extensions:
sockets - Required when using Socket connection class src/connection/Socket.phpopenssl - Required when using StreamSocket connection class with SSL/TLS encryption src/connection/StreamSocket.phpSources: README.md45-54 composer.json10-14 composer.json47-52
Install the latest version using Composer:
The package is available at packagist.org/packages/stefanak-michal/bolt. Composer automatically handles PSR-4 autoloading for the Bolt\ namespace.
src directory into your projectrequire_once 'path/to/src/autoload.php';The autoload file at src/autoload.php handles namespace resolution for all Bolt library classes.
Sources: README.md56-72 README.md206-209 composer.json37-41
The Bolt library uses a factory pattern where the Bolt class negotiates protocol versions and returns an appropriate protocol instance. The following diagram illustrates the initialization sequence:
Sources: README.md172-202 src/Bolt.php120-143 tests/BoltTest.php59-73
The library provides three connection implementations implementing the IConnection interface:
| Class | Use Case | Requirements | Persistence |
|---|---|---|---|
\Bolt\connection\Socket | Memory-efficient connections using PHP sockets extension | ext-sockets | No |
\Bolt\connection\StreamSocket | Standard connections with optional SSL/TLS support | ext-openssl (for SSL) | No |
\Bolt\connection\PStreamSocket | Persistent connections across PHP requests with metadata caching | ext-openssl (for SSL), PSR-16 cache | Yes |
Constructor parameters for all connection classes:
$ip (string): Hostname or IP address (default: '127.0.0.1')$port (int): Port number (default: 7687)$timeout (int): Socket timeout in seconds (default: 15)The StreamSocket class accepts URI schemes including neo4j://, neo4j+s://, neo4j+ssc://, and bolt:// for convenience.
Sources: README.md211-233 src/connection/Socket.php src/connection/StreamSocket.php src/connection/PStreamSocket.php
The following example demonstrates the minimal steps to connect, authenticate, and execute a query:
The setProtocolVersions() method accepts up to 4 version specifications as integers (e.g., 4), floats (e.g., 5.2), or strings (e.g., '4.4.4'). If not called, defaults to versions [6, 5.8, 4.4] as configured in src/Bolt.php37
Sources: README.md170-202 tests/BoltTest.php59-90 src/Bolt.php187-193
The logon() method (V5+) and hello() method (V1-V4, when used with authentication) accept an $auth array. The authentication scheme determines required keys:
| Scheme | scheme | principal | credentials |
|---|---|---|---|
| None | 'none' | - | - |
| Basic | 'basic' | username | password |
| Bearer | 'bearer' | - | token |
| Kerberos | 'kerberos' | - | token |
Example for basic authentication:
Example for no authentication:
Sources: README.md126-135 tests/BoltTest.php33-36 tests/NornicDBTest.php40-41
The handshake sends a magic byte sequence 0x6060B017 followed by four packed version specifiers. The server responds with the highest supported version from the client's list. The Bolt class then instantiates the corresponding protocol class using the pattern \Bolt\protocol\V{version} where dots are replaced with underscores (e.g., \Bolt\protocol\V5_2).
Sources: src/Bolt.php145-157 src/Bolt.php205-220 src/Bolt.php243-261
When passing parameters to the run() method, PHP types are automatically serialized to PackStream format:
| Neo4j Type | PHP Type | Notes |
|---|---|---|
| Null | null | |
| Boolean | bool | |
| Integer | int | |
| Float | float | |
| String | string | |
| Bytes | \Bolt\packstream\Bytes | Binary data wrapper |
| List | array | Consecutive numeric keys from 0 |
| Dictionary | array or object | Non-list arrays or objects |
| Structure | IStructure implementations | Duration, Point2D, Point3D, Vector, etc. |
Note: Node, Relationship, UnboundRelationship, and Path structures are read-only and cannot be used as parameters. They are only returned from query results.
Example with various types:
For memory-efficient handling of large datasets, parameters can implement IPackListGenerator or IPackDictionaryGenerator interfaces for lazy evaluation.
Sources: README.md147-165 tests/BoltTest.php178-203 tests/PerformanceTest.php
Neo4j Aura requires encrypted connections. Use StreamSocket with SSL enabled:
The setSslContextOptions() method accepts an array of SSL context options as defined in the PHP SSL context documentation. For details on SSL/TLS configuration, see SSL/TLS Configuration and Security.
Sources: README.md239-250 tests/BoltTest.php39-57
For protocol versions 3 and higher, explicit transaction control is available:
Transaction methods return the protocol instance, enabling method chaining. For complete transaction semantics and state management, see Transaction Control Messages.
Sources: README.md137-145 tests/BoltTest.php111-143
Enable debug mode to inspect binary communication:
This outputs hexadecimal representations of all sent and received data to standard output. The timeout for socket connections is configured via the connection constructor's $timeout parameter (default: 15 seconds). To adjust the timeout for establishing the initial connection, modify the default_socket_timeout PHP INI directive before creating the connection.
Sources: README.md270-276 src/Bolt.php26 src/Bolt.php207-208
The library collects anonymous analytics data (query counts and session counts) stored in PSR-16 cache and submitted once daily. This data is aggregated and publicly available at Mixpanel. To disable analytics, set the environment variable:
The analytics implementation is located in src/Bolt.php30-114 and src/protocol/AProtocol.php170-191
Sources: README.md288-292 src/Bolt.php30-114
After completing basic setup, explore:
Refresh this wiki