VOOZH about

URL: https://deepwiki.com/stefanak-michal/php-bolt-driver/6-message-reference

⇱ Message Reference | stefanak-michal/php-bolt-driver | DeepWiki

Loading...
Loading...
Last indexed: 14 February 2026 (a283bd)
Menu

Message Reference

This page provides a comprehensive reference for all Bolt protocol messages supported by the PHP Bolt driver. Messages are the fundamental units of communication in the Bolt protocol, representing discrete client requests and server responses that control connection lifecycle, query execution, transaction management, and result streaming.

For information about how messages are serialized and transmitted over the wire, see Data Serialization (PackStream). For details on protocol version evolution and when specific messages were introduced, see Protocol Versions. For state machine behavior and how messages affect connection state, see Server State Management.

Message System Overview

The Bolt protocol operates through a request-response pattern where clients send request messages and servers respond with SUCCESS, FAILURE, RECORD, or IGNORED messages. Each message type is identified by a unique signature byte and may contain structured parameters encoded using PackStream format.

Message Organization

Messages in this driver are implemented as PHP traits within protocol version namespaces. Each trait provides a standardized interface:

Trait Structure:

src/protocol/
├── v1/
│ ├── InitMessage.php (public init(), protected _init())
│ ├── RunMessage.php (public run(), protected _run())
│ ├── PullAllMessage.php (public pullAll(), protected _pullAll())
│ ├── DiscardAllMessage.php (public discardAll(), protected _discardAll())
│ ├── AckFailureMessage.php (public ackFailure(), protected _ackFailure())
│ └── ResetMessage.php (public reset(), protected _reset())
├── v3/
│ ├── HelloMessage.php (public hello(), protected _hello())
│ ├── RunMessage.php (public run(), protected _run())
│ ├── BeginMessage.php (public begin(), protected _begin())
│ ├── CommitMessage.php (public commit(), protected _commit())
│ ├── RollbackMessage.php (public rollback(), protected _rollback())
│ └── GoodbyeMessage.php (public goodbye())
├── v4/
│ ├── PullMessage.php (public pull(), protected _pull())
│ └── DiscardMessage.php (public discard(), protected _discard())
├── v4_4/
│ └── RouteMessage.php (public route(), protected _route())
├── v5_1/
│ ├── LogonMessage.php (public logon(), protected _logon())
│ └── LogoffMessage.php (public logoff(), protected _logoff())
└── v5_4/
 └── TelemetryMessage.php (public telemetry(), protected _telemetry())

Each trait follows a consistent pattern:

  • Public method: Packs message parameters, writes to connection, appends to $this->pipelinedMessages[], returns $this for fluent chaining
  • Protected method: Reads response(s) from connection, updates $this->serverState, yields Response objects

The Message enum src/enum/Message.php defines enum cases for all message types (RUN, PULL, BEGIN, etc.), while the Signature enum src/enum/Signature.php defines response signatures (SUCCESS=0x70, RECORD=0x71, FAILURE=0x7F, IGNORED=0x7E). The $pipelinedMessages array in AProtocol src/protocol/AProtocol.php tracks outstanding requests awaiting responses.

Sources: src/protocol/v1/InitMessage.php src/protocol/v3/RunMessage.php src/protocol/v4/PullMessage.php src/protocol/v4_4/RouteMessage.php src/protocol/v5_1/LogonMessage.php src/protocol/v5_4/TelemetryMessage.php src/enum/Message.php src/enum/Signature.php src/protocol/AProtocol.php

Message Lifecycle

Message Lifecycle: From Application Call to Response



Key Code Paths:



Sources: src/protocol/AProtocol.php src/protocol/v3/RunMessage.php18-41 src/protocol/v4/PullMessage.php19-45 src/enum/Message.php src/enum/Signature.php src/enum/ServerState.php


Message Categories


Messages are organized into functional categories that correspond to different aspects of Bolt protocol operation:

















































CategoryPurposeExample MessagesSub-Page
Handshake & AuthenticationConnection establishment and authorizationINIT, HELLO, LOGON, LOGOFF6.1
Query ExecutionSubmitting Cypher queriesRUN6.2
Result StreamingRetrieving or discarding query resultsPULL_ALL, PULL, DISCARD_ALL, DISCARD6.3
Transaction ControlManaging explicit transactionsBEGIN, COMMIT, ROLLBACK6.4
Session ManagementConnection lifecycle and error recoveryRESET, GOODBYE, ACK_FAILURE6.5
Advanced FeaturesRouting and telemetryROUTE, TELEMETRY6.6


Sources: src/protocol/v1/ src/protocol/v3/ src/protocol/v4/ src/protocol/v5/


Complete Message Reference


The following table lists all messages supported by the driver, organized by protocol version introduced:































































































































































MessageSignatureProtocolTrait FilePublic Method SignaturePurpose
INIT0x01V1, V2v1\InitMessage.phpinit(string $userAgent, array $authToken)Initialize connection with authentication
RUN0x10V1, V2v1\RunMessage.phprun(string $statement, array $parameters)Execute Cypher query (2 params)
RUN0x10V3+v3\RunMessage.phprun(string $statement, array $parameters, array $extra)Execute Cypher query (3 params)
DISCARD_ALL0x2FV1, V2v1\DiscardAllMessage.phpdiscardAll()Discard all remaining results
PULL_ALL0x3FV1, V2v1\PullAllMessage.phppullAll()Retrieve all remaining results
ACK_FAILURE0x0EV1, V2v1\AckFailureMessage.phpackFailure()Acknowledge server failure (V1/V2 only)
RESET0x0FV1+v1\ResetMessage.phpreset()Reset connection to ready state
HELLO0x01V3+v3\HelloMessage.phphello(array $extra)Initialize connection (replaces INIT)
GOODBYE0x02V3+v3\GoodbyeMessage.phpgoodbye()Gracefully close connection
BEGIN0x11V3+v3\BeginMessage.phpbegin(array $extra)Begin explicit transaction
COMMIT0x12V3+v3\CommitMessage.phpcommit()Commit explicit transaction
ROLLBACK0x13V3+v3\RollbackMessage.phprollback()Rollback explicit transaction
DISCARD0x2FV4+v4\DiscardMessage.phpdiscard(array $extra)Discard results with n parameter
PULL0x3FV4+v4\PullMessage.phppull(array $extra)Retrieve results with n parameter
ROUTE0x66V4.3, V4.4v4_4\RouteMessage.phproute(array $routing, array $bookmarks, array $extra)Request cluster routing table
LOGON0x6AV5.1+v5_1\LogonMessage.phplogon(array $authToken)Authenticate after HELLO
LOGOFF0x6BV5.1+v5_1\LogoffMessage.phplogoff()Deauthenticate connection
TELEMETRY0x54V5.4+v5_4\TelemetryMessage.phptelemetry(int $api)Report driver API usage


Parameter Details:


    

  • 

    $extra (array): Optional metadata dictionary supporting keys:
    

      

    • db (string): Target database name
      • 

    • bookmarks (array): Transaction bookmarks for causal consistency
      • 

    • tx_timeout (int): Transaction timeout in milliseconds
      • 

    • tx_metadata (array): Custom transaction metadata
      • 

    • mode (string): Access mode ('r' for read, 'w' for write)
      • 

    • imp_user (string): Impersonated user for query execution
      • 

    

    • 

  • 

    $authToken (array): Authentication credentials with keys:
    

      

    • scheme (string): 'none', 'basic', 'bearer', or 'kerberos'
      • 

    • principal (string): Username (for basic/kerberos)
      • 

    • credentials (string): Password or token
      • 

    

    • 

  • 

    $extra for PULL/DISCARD (array): Streaming control parameters:
    

      

    • n (int): Number of records to fetch/discard; -1 means all remaining records
      • 

    • qid (int): Query ID for streaming control (typically -1 for default stream)
      • 

    

    • 



Test Coverage Examples:


The test suite demonstrates message usage across protocol versions:




Sources: tests/protocol/V1Test.php27-53 tests/protocol/V3Test.php27-53 tests/protocol/V3Test.php70-98 tests/protocol/V4Test.php27-46 tests/protocol/V4_3Test.php27-45 tests/protocol/V4_4Test.php27-47 src/protocol/v1/InitMessage.php src/protocol/v1/RunMessage.php src/protocol/v3/HelloMessage.php src/protocol/v3/RunMessage.php src/protocol/v4/PullMessage.php src/protocol/v4/DiscardMessage.php src/protocol/v4_4/RouteMessage.php src/protocol/v5_1/LogonMessage.php src/protocol/v5_4/TelemetryMessage.php


Message Structure and Encoding


Each message follows a consistent structure when serialized:




Signature Bytes and Trait Mapping


Signature Byte to Trait Implementation Mapping (Code Entities)




Key Observations:


    

  • Signature Reuse: Signature bytes 0x01 (INIT/HELLO), 0x2F (DISCARD_ALL/DISCARD), and 0x3F (PULL_ALL/PULL) are reused across protocol versions with different parameter counts and semantics
    • 

  • Trait Composition: Protocol classes (V1, V3, V4, V5, V6) use traits to compose message capabilities, importing only the traits relevant to their version
    • 

  • Packer Abstraction: All message traits call $this->packer->pack() (src/packstream/IPacker.php), delegating binary serialization to version-specific Packer implementations (src/packstream/v1/Packer.php)
    • 



Example Code Path for RUN Message:


    

  1. Application calls $protocol->run('RETURN 1', []) (README.md102)
    2. 

  2. RunMessage trait's public run() method executes (src/protocol/v3/RunMessage.php18-28)
    3. 

  3. Calls $this->write($this->packer->pack(0x10, $statement, (object)$parameters, (object)$extra)) (src/protocol/v3/RunMessage.php20-25)
    4. 

  4. Packer::pack() encodes signature byte 0x10 followed by three PackStream structures (src/packstream/v1/Packer.php)
    5. 

  5. AProtocol::write() chunks the binary data and appends 0x00 0x00 terminator (src/protocol/AProtocol.php)
    6. 

  6. IConnection::write() transmits to Neo4j over TCP socket (src/connection/IConnection.php)
    7. 



Sources: src/protocol/v1/InitMessage.php19 src/protocol/v3/HelloMessage.php20 src/protocol/v1/RunMessage.php19 src/protocol/v3/RunMessage.php20-25 src/protocol/v1/PullAllMessage.php20 src/protocol/v4/PullMessage.php23 src/protocol/v1/DiscardAllMessage.php19 src/protocol/v4/DiscardMessage.php24 src/protocol/v3/BeginMessage.php20 src/protocol/v3/CommitMessage.php20 src/protocol/v3/RollbackMessage.php20 src/protocol/v3/GoodbyeMessage.php23 src/protocol/v4_4/RouteMessage.php20 src/protocol/v1/ResetMessage.php18 src/protocol/v5_1/LogonMessage.php19 src/protocol/v5_1/LogoffMessage.php18 src/protocol/v5_4/TelemetryMessage.php19 src/packstream/IPacker.php src/packstream/v1/Packer.php


Response Handling


All request messages receive responses from the server. The Response class src/protocol/Response.php encapsulates the response data:
































Response SignatureDescriptionContent
SUCCESS (0x70)Request completed successfullyMetadata dictionary (fields, qid, bookmarks, etc.)
RECORD (0x71)Result record from queryArray of field values
FAILURE (0x7F)Request failedError code and message
IGNORED (0x7E)Request ignored due to previous failureEmpty


Response Reading Pattern


Response Reading Flow by Message Type (Code Paths)




Code Implementation Examples:


Single-Response Message (_run in V3):




Streaming-Response Message (_pull in V4):




Transaction Control Message (_commit in V3):




Key Differences:


    

  • _run(): Single read, checks for qid key to increment openStreams counter for result streaming
    • 

  • _pull(): Loop until non-RECORD, checks has_more metadata to manage openStreams counter
    • 

  • _commit(): Single read, resets openStreams to zero (ends transaction)
    • 

  • _pullAll(): Loop until non-RECORD, no has_more checking (V1/V2 behavior)
    • 



Sources: src/protocol/v3/RunMessage.php35-41 src/protocol/v3/BeginMessage.php30-35 src/protocol/v3/CommitMessage.php30-35 src/protocol/v3/RollbackMessage.php30-35 src/protocol/v4/PullMessage.php33-45 src/protocol/v4/DiscardMessage.php34-40 src/protocol/v1/PullAllMessage.php29-35 src/protocol/AProtocol.php src/protocol/Response.php


Message Pipelining


The driver supports message pipelining, allowing multiple requests to be sent before consuming responses. This significantly improves performance by reducing round-trip latency.


Pipelining Mechanism




The $pipelinedMessages array src/protocol/AProtocol.php tracks the order of sent messages as Message enum values. Each trait appends to this array after writing:




src/protocol/v3/RunMessage.php20-27


The getResponses() method src/protocol/AProtocol.php processes the pipeline in FIFO order, calling the appropriate _messageType() method for each queued message.


Sources: src/protocol/AProtocol.php src/protocol/v3/RunMessage.php20-27 src/protocol/v4/PullMessage.php19-26 src/protocol/v3/CommitMessage.php18-23


Protocol Version Differences


Message availability and behavior varies across protocol versions. The driver implements protocol-specific traits that compose into versioned protocol classes through PHP's trait composition mechanism.


Message Evolution Across Versions (Protocol Class Composition)




Key Differences by Version:































































































VersionProtocol ClassAuthenticationTransaction ControlResult StreamingAdvanced Features
V1Bolt\protocol\V1init($userAgent, $authToken)Auto-commit onlypullAll(), discardAll()ackFailure() for error recovery
V2Bolt\protocol\V2Same as V1Same as V1Same as V1Same as V1
V3Bolt\protocol\V3hello($extra) with embedded authbegin($extra), commit(), rollback()Same as V1goodbye() for graceful disconnect
V4Bolt\protocol\V4Same as V3Same as V3pull($extra), discard($extra) with n paramParameterized streaming
V4.1Bolt\protocol\V4_1Enhanced hello() with routing hintsSame as V3Same as V4Enhanced authentication
V4.3Bolt\protocol\V4_3Same as V4.1Same as V3Same as V4route($routing, $bookmarks, $extra)
V4.4Bolt\protocol\V4_4Same as V4.1Same as V3Same as V4route() with db parameter
V5.1Bolt\protocol\V5_1hello($extra) + logon($authToken) (2-phase)Same as V3Same as V4logoff() for re-authentication
V5.4Bolt\protocol\V5_4Same as V5.1Same as V3Same as V4telemetry($api) for usage tracking
V6Bolt\protocol\V6Same as V5Same as V3Same as V4Same as V5.4 + Vector structures


RUN Message Evolution (Code Examples):


V1/V2 RUN (2 parameters):




V3+ RUN (3 parameters):




PULL/DISCARD Evolution:


V1/V2 PULL_ALL (no parameters):




V4+ PULL (parameterized):




Test Demonstrations:




Sources: src/protocol/V1.php src/protocol/V2.php src/protocol/V3.php src/protocol/V4.php src/protocol/V4_1.php src/protocol/V4_3.php src/protocol/V4_4.php src/protocol/V5_1.php src/protocol/V5_4.php src/protocol/V6.php src/protocol/v1/InitMessage.php src/protocol/v1/RunMessage.php17-22 src/protocol/v1/PullAllMessage.php17-23 src/protocol/v3/HelloMessage.php src/protocol/v3/RunMessage.php18-28 src/protocol/v3/BeginMessage.php src/protocol/v3/CommitMessage.php src/protocol/v4/PullMessage.php19-26 src/protocol/v4/DiscardMessage.php src/protocol/v4_4/RouteMessage.php src/protocol/v5_1/LogonMessage.php src/protocol/v5_4/TelemetryMessage.php tests/protocol/V1Test.php27-90 tests/protocol/V3Test.php27-130 tests/protocol/V4Test.php27-46 tests/protocol/V4_3Test.php27-45


Message State Requirements


Messages can only be sent in valid server states. The state machine governs message availability:






























































MessageValid StatesResulting State
INIT/HELLOCONNECTEDREADY (on SUCCESS)
LOGONNEGOTIATIONREADY (on SUCCESS)
RUNREADY, TX_READYSTREAMING, TX_STREAMING (on SUCCESS)
PULL/PULL_ALLSTREAMING, TX_STREAMINGREADY/TX_READY (when complete)
DISCARD/DISCARD_ALLSTREAMING, TX_STREAMINGREADY/TX_READY
BEGINREADYTX_READY (on SUCCESS)
COMMITTX_READYREADY (on SUCCESS)
ROLLBACKTX_READYREADY (on SUCCESS)
RESETAny except DEFUNCTREADY (on SUCCESS)
GOODBYEREADYDISCONNECTED


See Server State Management for detailed state transition rules and the ServerState enum src/enum/ServerState.php


Sources: src/enum/ServerState.php src/protocol/AProtocol.php


Detailed Message Documentation


For comprehensive documentation on individual messages including parameters, examples, and version-specific behavior, see the following sub-pages: