Connection Management

Purpose and Scope

This page provides an overview of the connection management system in the php-bolt-driver library. It covers the connection abstraction layer, the three available connection implementations, and how connections integrate with the Bolt protocol factory.

For detailed information on specific topics, see:

• Implementation details and comparison: Connection Implementations
• Persistent connection handling and caching: Persistent Connections with PStreamSocket
• SSL/TLS setup and security configuration: SSL/TLS Configuration and Security
• Timeout settings and error handling patterns: Timeout Configuration and Error Handling

Connection Architecture

The library uses an interface-based abstraction layer that decouples the Bolt protocol implementation from the underlying transport mechanism. This design enables support for multiple connection strategies while maintaining a consistent API.

Class Hierarchy

Sources: src/connection/IConnection.php1-43 src/connection/AConnection.php1-62 src/connection/Socket.php1-161 src/connection/StreamSocket.php1-146

IConnection Interface

The IConnection interface src/connection/IConnection.php14-42 defines the contract that all connection implementations must fulfill. It specifies methods for establishing connections, performing I/O operations, and managing connection lifecycle.

Method	Purpose	Throws
connect()	Establish TCP connection to database	ConnectException
write(string $buffer)	Send binary data to server	ConnectException
read(int $length)	Receive binary data from server	ConnectException
disconnect()	Close connection and release resources	-
setTimeout(float $timeout)	Update timeout for I/O operations	-

Sources: src/connection/IConnection.php14-42

AConnection Base Class

The AConnection abstract class src/connection/AConnection.php12-61 provides common functionality shared by all implementations:

• URL Parsing: The constructor src/connection/AConnection.php14-26 automatically strips protocol schemes from URLs (e.g., neo4j+s://host becomes host)
• Debug Support: The printHex() method src/connection/AConnection.php31-40 formats binary data as hexadecimal output when Bolt::$debug is enabled
• Property Management: Standard getters for ip, port, and timeout properties

Sources: src/connection/AConnection.php1-62

Connection Implementations Comparison

The library provides three connection implementations, each optimized for different use cases:

Implementation	Extension Required	SSL Support	Persistent	Memory Usage	Primary Use Case
Socket	ext-sockets	No	No	Lower	High-performance scenarios
StreamSocket	None (core PHP)	Yes	No	Standard	Production with SSL/TLS
PStreamSocket	None (core PHP)	Yes	Yes	Standard	Reduced connection overhead

Sources: README.md211-232 src/connection/Socket.php16-34 src/connection/StreamSocket.php17-37

Socket Implementation

The Socket class src/connection/Socket.php16-160 uses the PHP sockets extension (ext-sockets) and provides the most efficient memory usage. It requires explicit extension installation and cannot be used in environments where ext-sockets is unavailable.

Key characteristics:

• Uses socket_create() src/connection/Socket.php38 socket_connect() src/connection/Socket.php52
• Configures TCP_NODELAY and SO_KEEPALIVE options src/connection/Socket.php47-48
• Implements retry logic for SOCKET_EINTR and SOCKET_EWOULDBLOCK errors src/connection/Socket.php23-26
• Better memory management for high-throughput scenarios

Sources: src/connection/Socket.php1-161 README.md215-219

StreamSocket Implementation

The StreamSocket class src/connection/StreamSocket.php17-145 uses PHP's stream functions and requires no extensions. It is the most versatile implementation, supporting SSL/TLS encryption through the setSslContextOptions() method src/connection/StreamSocket.php34-37

Key characteristics:

• Uses stream_socket_client() src/connection/StreamSocket.php48 with stream contexts
• SSL enabled via stream_socket_enable_crypto() src/connection/StreamSocket.php59
• Configures tcp_nodelay option src/connection/StreamSocket.php43
• Required for Neo4j Aura and cloud deployments

Sources: src/connection/StreamSocket.php1-146 README.md220-228

PStreamSocket Implementation

The PStreamSocket class extends StreamSocket to provide persistent connection support. It uses PSR-16 cache to store connection metadata across PHP requests, enabling connection reuse.

Key characteristics:

• Extends StreamSocket with persistence layer
• Stores metadata in PSR-16 cache (see Caching and Analytics)
• Automatically sends RESET message on connection reuse
• 15-minute TTL for cached metadata

Sources: README.md229-233

Connection Lifecycle

The following diagram illustrates the typical lifecycle of a connection from instantiation through use by the Bolt protocol:

Sources: README.md172-202 tests/BoltTest.php59-73 src/connection/Socket.php36-57

Connection Parameters

All connection implementations accept three constructor parameters:

IP Address / Hostname

The $ip parameter src/connection/AConnection.php15 accepts:

• IPv4 addresses (e.g., 127.0.0.1)
• IPv6 addresses
• Hostnames (e.g., localhost, neo4j.example.com)
• URLs with protocol schemes (e.g., neo4j+s://host.databases.neo4j.io)

When a URL with a protocol scheme is provided, the AConnection constructor src/connection/AConnection.php20-25 automatically strips the scheme portion, extracting only the hostname.

Sources: src/connection/AConnection.php14-26 tests/BoltTest.php41

Port

The $port parameter src/connection/AConnection.php16 specifies the TCP port. Default is 7687, which is the standard Bolt protocol port. Neo4j also supports port 7473 for HTTP+Discovery and port 7474 for HTTP browser interface.

Sources: src/connection/AConnection.php16

Timeout

The $timeout parameter src/connection/AConnection.php17 controls the timeout for established socket operations (read/write). It does not control the connection establishment timeout, which is governed by the PHP default_socket_timeout ini directive README.md271-276

Timeouts can be updated after construction using setTimeout() src/connection/IConnection.php41 which dynamically reconfigures the underlying socket.

Sources: src/connection/AConnection.php17 src/connection/Socket.php126-141 README.md270-277

Integration with Bolt Factory

Connections are injected into the Bolt factory class, which manages protocol negotiation and instantiation:

Sources: README.md172-202 tests/BoltTest.php19-37

Factory Usage Pattern

The typical initialization pattern follows these steps:

1. Instantiate Connection: Create a connection implementation with desired configuration
2. Create Factory: Pass connection to Bolt constructor
3. Configure Protocol: Optionally call setProtocolVersions() to specify desired versions
4. Build Protocol: Call build() to establish connection and negotiate protocol version
5. Use Protocol: Returned protocol instance uses the connection for all I/O operations

Example:

Sources: README.md173-180 tests/BoltTest.php24-30

Error Handling

Connection operations throw two primary exception types:

Exception	Thrown By	Meaning
ConnectException	connect(), write(), read()	Connection failure, I/O error, or socket error
ConnectionTimeoutException	write(), read()	Operation exceeded configured timeout

Both exceptions are defined in the \Bolt\error namespace. ConnectionTimeoutException extends ConnectException.

Sources: src/connection/Socket.php6-7 src/connection/Socket.php149-159 src/connection/StreamSocket.php7-8

Debug Mode

All connection classes support debug mode through the static Bolt::$debug flag. When enabled, connections output hexadecimal representations of sent and received data using the printHex() method src/connection/AConnection.php31-40

Output format:

• Client messages: Prefixed with C:
• Server messages: Prefixed with S:
• Formatted as 8-character hex groups with spaces

This feature is useful for protocol debugging and packet inspection.

Sources: src/connection/AConnection.php31-40 src/connection/Socket.php65-67 src/connection/StreamSocket.php71-72 README.md93