feat(#46): bound the process-wide database cache - #82
Merged
Conversation
FoundationDB::open()/openWithConnectionString() now keep a bounded LRU cache (default 8) of Database objects instead of retaining every distinct database for the process lifetime. Eviction drops only the cache reference; a Database still held by the app keeps working and its native handle is released when the last reference disappears or on close(). Adds FoundationDB::setMaxDatabases()/getMaxDatabases() (>=1) and resets the bound via FoundationDB::reset(). Updates docs/advanced.md and CHANGELOG.md. Unit coverage in tests/Unit/FoundationDBDatabaseCacheTest.php.
5 tasks
…plicit CI resolves latest deps because composer.lock is gitignored; phpstan 2.2.9 (2026-08-22) newly flags the overflow-checking '$value < 0' in Tuple::decodePositiveInt as always-false, and 2.2.9 is also incompatible with rector. Pin the known-good versions from the last green CI run (#80): phpstan 2.2.8, rector 2.6.3. decodePositiveInt now detects the >= 2^63 overflow explicitly via the top byte (8 bytes + MSB set) instead of relying on 64-bit int overflow that static analysis cannot model. Behavior is identical (an 8-byte value with the MSB clear like PHP_INT_MAX still returns an int), unit-verified by the tuple roundtrip tests, and the check is robust against future PHPStan versions.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #46 — bounds the process-wide
Databasecache so an application opening many distinct cluster files or connection strings no longer retains an unbounded number of live nativeFDBDatabasehandles for the process lifetime.Changes
src/FoundationDB.php: replaced the unbounded static cache with a bounded LRU cache (default capacity 8).open()/openWithConnectionString()reuse cached instances and evict the least-recently-used entry when over capacity. Eviction drops only the cache reference — aDatabasestill held by the application keeps working, and its native handle is released when the last reference disappears (destructor) or onclose().FoundationDB::setMaxDatabases(int)/getMaxDatabases()(rejects0/negative withInvalidArgumentException; rejected values leave the current bound untouched).FoundationDB::reset()restores the default bound and clears the cache.tests/Unit/FoundationDBDatabaseCacheTest.php: unit tests for LRU eviction, capacity bound, config validation, shrinks, idempotent trim and reset — pure cache logic via reflection, no live cluster needed.docs/advanced.md: new "Database Cache" section documenting lifetime, ownership and the new knob.CHANGELOG.md:[#46]entry underChanged.Verification
composer lint— clean (PHPCS + Rector dry-run + PHPStan)composer test:unit— 469 tests, 946 assertions