Protocol Versions

This document provides an overview of the Bolt protocol versions supported by the php-bolt-driver library, the evolutionary changes between versions, and the trait-based architecture used to implement them. For detailed information about specific protocol versions, see:

• V1 and V2 foundation messages: Protocol V1 and V2 - Foundation
• V3 transaction support: Protocol V3 - Transaction Support
• V4.x streaming and routing: Protocol V4.x Series - Streaming and Routing
• V5.x and V6 modern features: Protocol V5.x and V6 - Modern Features

For information about individual protocol messages, see Message Reference.

Supported Protocol Versions

The library supports Bolt protocol versions 1 through 6, maintaining backward compatibility while implementing the latest features. The following table summarizes the protocol versions and their corresponding PHP class implementations:

Protocol Version	Class Name	Neo4j Support	Key Features
1.0	V1	Neo4j 3.0+	Init, Run, PullAll, DiscardAll, Reset, AckFailure
2.0	V2	Neo4j 3.1+	Same as V1
3.0	V3	Neo4j 3.5+	Hello, Begin, Commit, Rollback, Goodbye
4.0	V4	Neo4j 4.0+	Pull, Discard (parameterized streaming)
4.1	V4_1	Neo4j 4.1+	Enhanced Hello message
4.2	V4_2	Neo4j 4.2+	Minor updates
4.3	V4_3	Neo4j 4.3+	Route message, enhanced structures
4.4	V4_4	Neo4j 4.4+	Route with database parameter
5.x	V5 series	Neo4j 5.0+	Logon, Logoff messages
6.0	V6	Neo4j 5.15+	Vector structure, Telemetry

Sources: README.md31-33 src/protocol/V1.php src/protocol/V2.php src/protocol/V3.php src/protocol/V4.php src/protocol/V4_1.php src/protocol/V4_2.php src/protocol/V4_3.php src/protocol/V4_4.php

Protocol Class Hierarchy

The following diagram shows how protocol versions are implemented as concrete PHP classes in the \Bolt\protocol namespace:

Diagram: Protocol Version Class Hierarchy

Each protocol version is implemented as a separate class extending AProtocol and using trait composition to assemble the appropriate message handlers and structures. This design enables code reuse while maintaining clean separation between protocol versions.

Sources: src/protocol/V1.php12-23 src/protocol/V2.php12-23 src/protocol/V3.php13-28 src/protocol/V4.php13-29 src/protocol/V4_1.php13-30 src/protocol/V4_2.php13-30 src/protocol/V4_3.php13-32 src/protocol/V4_4.php13-32

Trait Composition Architecture

The protocol implementations use PHP traits to compose functionality, allowing selective reuse of message handlers and structures across protocol versions. The following diagram illustrates which traits each protocol version uses:

Diagram: Trait Composition Pattern Across Protocol Versions

This architecture demonstrates several key patterns:

1. Foundational trait reuse: The v1\ResetMessage trait is used across all protocol versions from V3 onwards
2. Progressive enhancement: V4 builds on V3 by adding new traits (v4\PullMessage, v4\DiscardMessage) while reusing transaction control traits from V3
3. Incremental updates: V4.1, V4.2, V4.3, and V4.4 share most traits, differing only in specific enhancements (Hello message, Route message, structures)
4. State management evolution: Each major version (V1, V3, V4) has its own ServerStateTransition trait to handle version-specific state logic

Sources: src/protocol/V1.php14-22 src/protocol/V2.php14-22 src/protocol/V3.php15-27 src/protocol/V4.php15-28 src/protocol/V4_1.php15-29 src/protocol/V4_3.php15-31 src/protocol/V4_4.php15-31

Protocol Version Evolution

The Bolt protocol has evolved significantly over its lifetime. The following table summarizes the major changes introduced in each version:

Version	Major Changes	Deprecated Messages	New Messages
V1 → V2	None (identical implementations)	-	-
V2 → V3	Explicit transaction support, graceful termination	INIT, ACK_FAILURE	HELLO, BEGIN, COMMIT, ROLLBACK, GOODBYE
V3 → V4	Parameterized result streaming	PULL_ALL, DISCARD_ALL	PULL, DISCARD (with n and qid parameters)
V4 → V4.1	Enhanced authentication in HELLO	-	-
V4.1 → V4.2	Minor protocol refinements	-	-
V4.2 → V4.3	Cluster routing support, enhanced structures	-	ROUTE
V4.3 → V4.4	Database parameter in ROUTE	-	-
V4.4 → V5	Authentication separation	-	LOGON, LOGOFF
V5 → V6	Numeric array optimization, monitoring	-	TELEMETRY, Vector structure

Key evolutionary milestones:

• V1-V2: Foundation with basic query execution and session management
• V3: Transaction support as first-class concept
• V4.x: Progressive refinement of streaming, routing, and authentication
• V5.x: Explicit authentication lifecycle management
• V6: Performance optimization for numeric data and observability

Sources: README.md31-33 src/protocol/V1.php src/protocol/V3.php src/protocol/V4.php src/protocol/V4_3.php

Version Negotiation Process

When establishing a connection, the Bolt client and server perform a handshake to determine the highest mutually supported protocol version. The following sequence diagram illustrates this negotiation:

Diagram: Protocol Version Negotiation Sequence

The negotiation process includes:

1. Version list preparation: The application specifies up to 4 protocol versions in order of preference
2. Binary handshake: The client sends 16 bytes (4 versions × 4 bytes each) to the server
3. Server selection: The server responds with 4 bytes indicating the selected version (or 0 if none supported)
4. Caching: For persistent connections (PStreamSocket), the negotiated version is cached to avoid redundant handshakes on connection reuse
5. Protocol instantiation: The appropriate protocol class is instantiated based on the negotiated version

Sources: README.md172-202 tests/BoltTest.php59-73

Configuring Protocol Versions

The Bolt factory class provides the setProtocolVersions() method to configure which protocol versions to negotiate:

Method signature:

• setProtocolVersions(int|float|string ...$v): Bolt
• Accepts up to 4 version arguments in order of preference (highest to lowest)
• Version can be specified as integer (6), float (5.4), or string ("4.3")
• Returns $this for method chaining

Version format examples:

Input Format	Negotiated As	Protocol Class
6	6.0	V6
5.4	5.4	V5_4
"4.4"	4.4	V4_4
4	4.0	V4

Sources: README.md86-92 README.md178 tests/BoltTest.php30 tests/BoltTest.php50 tests/BoltTest.php67

Default Version Configuration

If setProtocolVersions() is not called, the library uses a default set of protocol versions optimized for modern Neo4j deployments:

Default versions (as of library version):

1. 6.0
2. 5.8, 5.7, 5.6, 5.5, 5.4, 5.3, 5.2, 5.1, 5.0 (one of these based on internal logic)
3. 4.4
4. 4.3

This default configuration ensures compatibility with:

• Neo4j 5.15+ (Bolt 6)
• Neo4j 5.x (Bolt 5.x series)
• Neo4j 4.4 (Bolt 4.4)
• Neo4j 4.3 (Bolt 4.3)

The library prioritizes newer protocol versions to take advantage of performance optimizations and new features like Vector structures and TELEMETRY messages.

Sources: README.md204

Protocol Version Detection in Tests

The test suite includes version detection logic to ensure tests are compatible with the connected database:

This method is used throughout the test suite to dynamically select the appropriate protocol version based on the target database:

The version detection enables:

• Cross-version testing against Neo4j 4.4, 5.x, and 2025 releases
• Automatic test skipping for unsupported features (e.g., transactions in V1/V2)
• Compatibility validation across the supported database ecosystem

Sources: tests/BoltTest.php30-31 tests/BoltTest.php50 tests/BoltTest.php67 tests/BoltTest.php113-115 tests/BoltTest.php150-158 tests/NornicDBTest.php33

Version-Specific Behavior

Different protocol versions exhibit distinct behaviors in key areas:

Query Parameter Syntax

Transaction Support

• V1-V2: No explicit transaction support; all queries run in auto-commit mode
• V3+: begin(), commit(), rollback() messages available

Result Streaming

• V1-V3: pullAll() retrieves all records at once
• V4+: pull(['n' => 1000]) supports batched retrieval

Authentication

• V1-V2: init() message combines connection and authentication
• V3-V4: hello() message handles authentication
• V5+: Separate hello() (connection) and logon() (authentication) messages

Sources: tests/BoltTest.php132-136 tests/BoltTest.php113-115

Summary

The php-bolt-driver implements Bolt protocol versions 1 through 6 using a trait-based composition architecture. This design enables:

1. Code reuse: Common functionality is shared across versions through traits
2. Version isolation: Each protocol version is a self-contained class
3. Progressive enhancement: New versions add features without breaking existing implementations
4. Backward compatibility: All versions from 1.0 to 6.0 are supported

For implementation details of specific protocol versions, refer to the child pages:

• Protocol V1 and V2 - Foundation
• Protocol V3 - Transaction Support
• Protocol V4.x Series - Streaming and Routing
• Protocol V5.x and V6 - Modern Features