Connection Implementations

Purpose and Scope

This document details the two primary connection implementations available in the Bolt library: Socket and StreamSocket. These classes implement the IConnection interface and provide different approaches to establishing TCP connections with graph databases.

For information about persistent connections, see Persistent Connections with PStreamSocket. For SSL/TLS configuration, see SSL/TLS Configuration and Security. For timeout handling, see Timeout Configuration and Error Handling.

Sources: README.md211-234 src/connection/IConnection.php1-42

---

Connection Layer Architecture

The connection layer follows a clear inheritance hierarchy with IConnection defining the contract, AConnection providing shared functionality, and Socket and StreamSocket implementing specific transport mechanisms.

Sources: src/connection/IConnection.php14-42 src/connection/AConnection.php12-61 src/connection/Socket.php16-160 src/connection/StreamSocket.php17-145

---

IConnection Interface

The IConnection interface defines the contract for all connection implementations. Every connection class must implement these methods to support the Bolt protocol communication.

Interface Contract

Method	Parameters	Return	Purpose
__construct()	string $ip, int $port, float $timeout	-	Initialize connection with target endpoint
connect()	-	bool	Establish TCP connection
write()	string $buffer	void	Write binary data to connection
read()	int $length	string	Read binary data from connection
disconnect()	-	void	Close connection gracefully
getIp()	-	string	Get target IP address
getPort()	-	int	Get target port
getTimeout()	-	float	Get current timeout value
setTimeout()	float $timeout	void	Update timeout value

All I/O methods (connect(), write(), read()) throw ConnectException or ConnectionTimeoutException on failure.

Sources: src/connection/IConnection.php14-42

---

AConnection Base Class

AConnection is an abstract class that implements shared functionality across all connection implementations. It handles URL parsing, timeout storage, and debug output.

Constructor URL Handling

The constructor accepts URLs with schemes and automatically strips them:

The scheme stripping logic is at src/connection/AConnection.php20-25

Debug Output

When Bolt::$debug is enabled, AConnection provides the printHex() method to display binary data as hexadecimal. This is used by both implementations to trace protocol messages.

Sources: src/connection/AConnection.php12-61

---

Socket Implementation

Socket uses PHP's sockets extension to provide low-level TCP communication. This implementation offers better memory efficiency at the cost of requiring the sockets extension.

Key Characteristics

Extension Check

The constructor verifies the sockets extension is loaded at src/connection/Socket.php30-32:

Connection Establishment

The connect() method follows these steps:

1. Create socket - socket_create(AF_INET, SOCK_STREAM, SOL_TCP) at src/connection/Socket.php38
2. Set blocking mode - socket_set_block() at src/connection/Socket.php43
3. Configure options - Set TCP_NODELAY and SO_KEEPALIVE at src/connection/Socket.php47-48
4. Apply timeout - Call configureTimeout() at src/connection/Socket.php49
5. Connect to endpoint - socket_connect() at src/connection/Socket.php52

Timeout Configuration

Timeouts are configured using socket_set_option() for both send and receive operations at src/connection/Socket.php131-141:

Error Handling

The implementation handles specific socket error codes defined at src/connection/Socket.php23-26:

• SOCKET_EINTR - Interrupted system call (retry)
• SOCKET_EWOULDBLOCK - Resource temporarily unavailable (retry)

Write operations retry on these codes at src/connection/Socket.php74-76 while read operations do the same at src/connection/Socket.php100-102

Sources: src/connection/Socket.php16-160 tests/BoltTest.php19-37 tests/NornicDBTest.php26-44

---

StreamSocket Implementation

StreamSocket uses PHP's stream functions for TCP communication. This implementation requires no extensions, supports SSL/TLS, and uses built-in PHP stream APIs.

Key Characteristics

Connection Establishment

The connect() method creates a stream context with TCP and SSL options at src/connection/StreamSocket.php39-67:

1. Create context - Configure tcp_nodelay and SSL options at src/connection/StreamSocket.php41-46
2. Open stream - Use stream_socket_client() with the context at src/connection/StreamSocket.php48
3. Set blocking - Enable blocking mode via stream_set_blocking() at src/connection/StreamSocket.php54
4. Enable SSL - If SSL is configured, call stream_socket_enable_crypto() at src/connection/StreamSocket.php58-62
5. Configure timeout - Apply timeout settings at src/connection/StreamSocket.php64

SSL Context Options

The setSslContextOptions() method enables SSL configuration at src/connection/StreamSocket.php34-37:

Passing null disables SSL, while passing an empty array enables SSL with default settings. The options array follows PHP's SSL context parameters.

Write Operations

Write operations use fwrite() with timeout tracking at src/connection/StreamSocket.php69-90:

Read Operations

Read operations use stream_get_contents() and check for stream timeout at src/connection/StreamSocket.php92-114:

Sources: src/connection/StreamSocket.php17-145 tests/BoltTest.php39-57 tests/BoltTest.php59-73

---

Implementation Comparison

The following table summarizes the differences between the two implementations:

Feature	Socket	StreamSocket
PHP Extension	sockets required	None required
Memory Usage	Lower	Higher
SSL/TLS Support	No	Yes (via context options)
API Complexity	Direct socket API	Stream abstraction
Error Handling	Socket-specific error codes	Stream meta data
Timeout Mechanism	socket_set_option()	stream_set_timeout()
Suitable For	Local databases, high performance	Production, Neo4j Aura, SSL required
Connection Function	socket_connect()	stream_socket_client()
Read Function	socket_recv()	stream_get_contents()
Write Function	socket_write()	fwrite()

Sources: README.md211-234

---

Usage Examples

Basic Socket Connection

For local development with better memory efficiency:

Sources: tests/BoltTest.php24-30 tests/NornicDBTest.php31-37

Basic StreamSocket Connection

For production environments or when SSL is needed:

Sources: tests/BoltTest.php61-67 README.md172-180

StreamSocket with SSL (Neo4j Aura)

For connecting to Neo4j Aura or other SSL-enabled endpoints:

Sources: tests/BoltTest.php41-50 README.md243-248

URL Scheme Handling

Both implementations strip URL schemes automatically:

The scheme stripping occurs in the AConnection constructor at src/connection/AConnection.php20-25

Sources: src/connection/AConnection.php14-26

---

Connection Lifecycle

Sources: src/connection/Socket.php36-57 src/connection/StreamSocket.php39-67 src/connection/Socket.php117-123 src/connection/StreamSocket.php116-122

---

Extension Requirements

Socket Implementation

The sockets extension must be loaded. Check availability:

Enable in php.ini:

Sources: src/connection/Socket.php30-32 README.md52

StreamSocket Implementation

No extensions are required for basic operation. However, SSL support requires openssl:

Enable in php.ini (for SSL only):

Sources: README.md53-54 src/connection/StreamSocket.php58-62

---

Common Implementation Details

Binary String Handling

Both implementations use mb_strlen() and mb_strcut() with '8bit' encoding to handle binary data correctly:

This ensures binary data is not corrupted by multi-byte string operations.

Sources: src/connection/Socket.php70-81 src/connection/StreamSocket.php74-88

Debug Hex Output

When Bolt::$debug is enabled, both implementations output hex dumps of sent and received data via the printHex() method inherited from AConnection:

Client messages use 'C: ' prefix, server responses use 'S: ' prefix.

Sources: src/connection/AConnection.php29-40 src/connection/Socket.php65-67 src/connection/Socket.php110-112 src/connection/StreamSocket.php71-72 src/connection/StreamSocket.php110-111