 |
VOOZH | about |
|
VOOZH | about |
This document details the system requirements, dependencies, and installation setup for the php-bolt-driver library. It covers PHP version requirements, required and optional extensions, the PSR-16 cache interface requirement, and development dependencies for contributors. For information about running tests after setup, see Running Tests. For connection-specific configuration after installation, see Connection Implementations and SSL/TLS Configuration.
This page documents the dependency requirements and installation process for the php-bolt-driver library. It explains which dependencies are mandatory, which are optional based on feature usage, and the roles each dependency plays in the library's operation.
The library requires PHP 8.1 or higher as specified in composer.json11 The codebase leverages modern PHP features including typed properties, constructor property promotion, and union types that were introduced in PHP 8.x versions. Testing is performed across PHP versions 8.2 through 8.5 as documented in the CI/CD workflows.
| Package | Version | Purpose |
|---|---|---|
psr/simple-cache | ^3.0 | PSR-16 cache interface for persistent connection metadata |
The psr/simple-cache package provides the CacheInterface that is required for persistent connection management via the PStreamSocket class. See Persistent Connections with PStreamSocket for details on cache usage.
| Extension | Purpose | Used By |
|---|---|---|
ext-mbstring | Multibyte string operations for UTF-8 handling in PackStream serialization | Packer, Unpacker classes |
ext-curl | HTTP requests for anonymous analytics tracking | Analytics class |
The ext-mbstring extension is critical for correct handling of UTF-8 encoded strings during PackStream serialization and deserialization. The ext-curl extension enables the optional analytics feature that tracks library usage statistics anonymously.
Sources: composer.json10-14
The ext-sockets extension is required only when using the Socket connection class, which provides low-level socket operations using PHP's socket functions.
The Socket class directly uses socket functions such as socket_create(), socket_connect(), socket_set_option(), socket_read(), and socket_write() which are only available when ext-sockets is installed. If you choose to use StreamSocket or PStreamSocket instead, this extension is not required.
When to use Socket:
Sources: composer.json50 src/connection/Socket.php
The ext-openssl extension is required when using the StreamSocket class with SSL/TLS encryption enabled. This is essential for secure connections to cloud-hosted Neo4j instances or any deployment requiring encrypted transport.
The StreamSocket::setSslContextOptions() method accepts an array of SSL context options that are passed directly to PHP's stream_context_create() function. Without ext-openssl, SSL/TLS connections will fail with a runtime error.
When to use OpenSSL:
For detailed SSL/TLS configuration, see SSL/TLS Configuration and Security.
Sources: composer.json51 src/connection/StreamSocket.php
The library requires a PSR-16 compatible cache implementation when using persistent connections via PStreamSocket. The cache interface is declared as a dependency in composer.json14 but no concrete implementation is included in the library.
The library includes a basic FileCache class in src/FileCache.php that stores cache entries as JSON files in a specified directory. This implementation is suitable for development and single-server deployments but has limitations:
ttl parameterFor production deployments, especially with multiple application servers, you should provide a distributed cache implementation:
| Cache Type | Use Case | Example Packages |
|---|---|---|
| Redis | Multi-server deployments, high performance | symfony/cache, cache/redis-adapter |
| Memcached | Multi-server deployments, distributed caching | symfony/cache, cache/memcached-adapter |
| APCu | Single-server deployments, in-memory caching | symfony/cache, cache/apcu-adapter |
| Filesystem | Development, single-server simple deployments | Built-in FileCache |
The cache is used for:
PStreamSocket successfully connects and negotiates a protocol version, it caches the version number to avoid redundant handshakes on subsequent connectionsFor details on cache usage in persistent connections, see Persistent Connections with PStreamSocket.
Sources: composer.json14 src/FileCache.php src/connection/PStreamSocket.php src/Analytics.php
Contributors and developers running tests require additional dependencies specified in the require-dev section:
| Package | Version | Purpose |
|---|---|---|
phpunit/phpunit | ^9 | Testing framework for unit and integration tests |
PHPUnit 9 is used for the comprehensive test suite covering:
The test suite is organized into multiple configurations in phpunit.xml:
For detailed testing instructions, see Running Tests. For CI/CD pipeline details, see CI/CD Pipeline and Cross-Version Testing.
Sources: composer.json16-18 phpunit.xml
This installs the library with all required dependencies. The autoloader configuration uses PSR-4 mapping from the Bolt\ namespace to the src/ directory as defined in composer.json37-40
If using the Socket connection class:
If using SSL/TLS with StreamSocket:
For contributors who need to run tests:
The composer test script is configured in composer.json53-58 to run PHPUnit with appropriate environment settings.
After installation, verify that required extensions are enabled:
You can also check PHP version compatibility:
Sources: composer.json1-60
This diagram shows the complete dependency tree from application code down to specific extensions and interfaces. Solid lines indicate direct usage, dashed lines indicate conditional requirements or interface implementations.
Sources: composer.json10-52 src/Bolt.php src/protocol/AProtocol.php src/packstream/Packer.php src/packstream/Unpacker.php src/connection/Socket.php src/connection/StreamSocket.php src/connection/PStreamSocket.php src/Analytics.php src/FileCache.php
| Requirement | Type | Used By | Notes |
|---|---|---|---|
| PHP 8.1+ | Mandatory | All code | Tested on 8.2-8.5 |
| ext-mbstring | Mandatory | Packer, Unpacker | UTF-8 string handling |
| ext-curl | Mandatory | Analytics | HTTP requests for tracking |
| psr/simple-cache ^3.0 | Mandatory | PStreamSocket, Analytics | Interface only, implementation required |
| ext-sockets | Optional | Socket | Only if using Socket class |
| ext-openssl | Optional | StreamSocket | Only if using SSL/TLS |
| phpunit/phpunit ^9 | Dev only | Test suite | For contributors |
Sources: composer.json10-18
Refresh this wiki