 |
VOOZH | about |
|
VOOZH | about |
This document explains the caching infrastructure and analytics tracking system used by the Bolt PHP library. The caching system provides persistent storage for connection metadata and analytics data using a PSR-16 compliant file-based implementation. The analytics system collects anonymous usage metrics that help improve the library.
For server state tracking during protocol execution, see Server State Management. For persistent connection handling that relies on this cache system, see Persistent Connections with PStreamSocket.
The library uses two primary subsystems for state persistence:
Both subsystems are accessed through the CacheProvider static accessor, which provides a single cache instance shared across all components.
Sources: src/helpers/CacheProvider.php1-29 src/helpers/FileCache.php1-219 src/Bolt.php1-262 src/protocol/AProtocol.php1-192
The FileCache class implements the PSR-16 CacheInterface standard, providing a file-based caching mechanism that works without external dependencies.
| Directory | Purpose | Content |
|---|---|---|
/tmp/php-bolt-filecache/ | Primary cache storage | Serialized PHP values keyed by cache key |
/tmp/php-bolt-filecache/.ttl/ | Time-to-live metadata | Unix timestamps for key expiration |
The cache validates keys against the pattern /^[\w\.]+$/i, allowing only alphanumeric characters, underscores, and dots. All values are serialized with allowed_classes => false for security.
Sources: src/helpers/FileCache.php68-108
FileCache provides additional lock() and unlock() methods beyond the PSR-16 standard to enable thread-safe updates. This is critical for the analytics system where multiple PHP processes may update the same data concurrently.
The $handles property src/helpers/FileCache.php22 maintains an array of file handles for locked keys. The shutdown() method src/helpers/FileCache.php39-46 ensures all locks are released on script termination.
Sources: src/helpers/FileCache.php188-213
TTL values can be specified as either:
The has() method src/helpers/FileCache.php172-186 automatically removes expired entries by comparing the stored timestamp against time().
Sources: src/helpers/FileCache.php90-99 src/helpers/FileCache.php172-186
The CacheProvider class provides a static accessor pattern for the cache instance, ensuring all components share the same cache backend.
| Method | Purpose |
|---|---|
CacheProvider::get() | Returns the current cache instance, lazy-initializing FileCache if needed |
CacheProvider::set(CacheInterface $cache) | Allows replacing the cache implementation with a custom PSR-16 adapter |
This design allows applications to substitute FileCache with Redis, Memcached, or any other PSR-16 implementation by calling CacheProvider::set() early in their bootstrap process.
Sources: src/helpers/CacheProvider.php1-29
The PStreamSocket connection class uses the cache to store protocol version information, enabling connection reuse across PHP requests without re-negotiating the protocol.
The identifier is computed in PStreamSocket::getIdentifier() src/connection/PStreamSocket.php60-65 and used as the cache key.
The 15-minute TTL src/Bolt.php139 balances connection reuse with the risk of stale metadata. When a cached version is found, the protocol is set to ServerState::INTERRUPTED src/Bolt.php174 and a RESET message verifies the connection is still valid src/Bolt.php176-180
Sources: src/Bolt.php138-143 src/Bolt.php159-185 src/connection/PStreamSocket.php60-65
The analytics system collects anonymous usage metrics to help the maintainers understand library adoption and usage patterns. All data is aggregated and anonymized before transmission.
| Event | Tracked Metric | Location |
|---|---|---|
| Protocol message write | queries counter increment | AProtocol::write() increments $writeCalls src/protocol/AProtocol.php68-73 |
| Protocol instance destruction | Aggregate daily counts | AProtocol::__destruct() updates cache src/protocol/AProtocol.php170-191 |
| Bolt instance creation | Upload aggregated data | Bolt::__construct() calls track() src/Bolt.php34 |
Keys are Unix timestamps for midnight UTC of each day (strtotime('today')). The queries count represents the total number of write operations (messages sent), while sessions represents the number of protocol instances destroyed.
Sources: src/protocol/AProtocol.php170-191 src/Bolt.php40-114
The distinct ID anonymously identifies a unique installation without revealing user information:
sha1(php_uname() + disk_total_space('.') + filectime('/') + phpversion())
This combines system name, disk size, filesystem creation time, and PHP version to create a stable identifier that remains constant for a given environment but cannot be reverse-engineered to identify the user src/Bolt.php47
The $insert_id uses the timestamp to ensure idempotency—Mixpanel will deduplicate events with the same ID, preventing double-counting if a request is retried src/Bolt.php54
Sources: src/Bolt.php49-71
Set the BOLT_ANALYTICS_OPTOUT environment variable to any truthy value to disable analytics collection:
This is checked at two locations:
Bolt::__construct() src/Bolt.php30 - Skips uploadAProtocol::__destruct() src/protocol/AProtocol.php172 - Skips aggregationWhen opted out, no data is collected, cached, or transmitted. For transparency, all collected analytics data is publicly viewable at the Mixpanel dashboard: https://eu.mixpanel.com/p/7ttVKqvjdqJtGCjLCFgdeC
Sources: src/Bolt.php30-35 src/protocol/AProtocol.php172-174 README.md288-292
The upload uses cURL with the following configuration:
| Setting | Value | Purpose |
|---|---|---|
| URL | https://api-eu.mixpanel.com/import | EU region endpoint |
| Method | POST | Batch event import |
| Timeout | Connection timeout value | Respects user configuration |
| SSL Verification | Disabled | Avoids certificate issues in varied environments |
| Authorization | Basic MDJhYjRiOWE2YTM4MThmNWFlZDEzYjNiMmE5M2MxNzQ6 | Service account token |
Only data from previous days ($time < strtotime('today')) is uploaded, ensuring today's in-progress counts remain in the cache for further aggregation src/Bolt.php51
Sources: src/Bolt.php78-114
Both the cache and analytics systems require writable directories in the system temporary directory:
| Directory | Created By | Purpose |
|---|---|---|
/tmp/php-bolt-filecache/ | FileCache::__construct() | General cache storage |
/tmp/php-bolt-filecache/.ttl/ | FileCache::__construct() | TTL metadata |
/tmp/php-bolt-analytics/ | Bolt::__construct() | Analytics working directory |
All directories are created with mkdir(recursive: true) only if they don't exist and the parent directory is writable. If the temporary directory is not writable, both caching and analytics are silently disabled.
Sources: src/helpers/FileCache.php24-34 src/Bolt.php30-33
The locking mechanism in FileCache ensures safe concurrent access in environments where multiple PHP processes may execute simultaneously (e.g., PHP-FPM, parallel test execution).
The locking is exclusive (LOCK_EX), meaning only one process can hold a lock at a time. Other processes attempting to lock the same key will block until the lock is released src/helpers/FileCache.php198
The analytics update in AProtocol::__destruct() demonstrates proper locking usage:
The method_exists() checks allow compatibility with PSR-16 implementations that don't support locking src/protocol/AProtocol.php176
Sources: src/protocol/AProtocol.php176-190 src/Bolt.php100-112
The test infrastructure sets up the analytics directory if needed:
This ensures tests can run even when analytics is enabled, though most test environments set BOLT_ANALYTICS_OPTOUT=1 to avoid network calls during CI execution.
Refresh this wiki