Upgrade cache dependency for reconnection support

[premtsd-code]

Summary

• Upgrade utopia-php/cache from 0.13.* to 1.0.*
• Upgrade utopia-php/pools from 0.8.* to 1.0.* (required dependency)

Test plan

• Unit tests pass
• Adapter tests pass

Summary by CodeRabbit

• Chores

  • Updated PHP minimum requirement to 8.4
  • Upgraded cache and pools packages to new major versions

• Breaking Changes

  • Pool initialization now requires an adapter parameter; existing instantiation must be updated

• Tests

  • Updated end-to-end pool tests for the new initialization pattern
  • Added end-to-end cache reconnection test to validate Redis recovery and data consistency after reconnects

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Updated platform and dependencies in composer.json; adapted Pool constructor usage to accept an Adapter in tests; added an end-to-end Redis cache reconnect test and helper to wait for Redis readiness.

Changes

Cohort / File(s)	Summary
Composer manifest composer.json	Bumped PHP requirement to >=8.4; upgraded utopia-php/cache to 1.0.* and utopia-php/pools to 1.0.*.
Pool usage / tests tests/e2e/Adapter/PoolTest.php	Updated UtopiaPool instantiation to pass an adapter first (new UtopiaPool(new Stack(), 'mysql', 10, ...)) and added use import for the adapter to match the new constructor signature.
Cache reconnect e2e test tests/e2e/Adapter/Scopes/GeneralTests.php	Added testCacheReconnect() and waitForRedis() helper; added imports for Utopia\Cache\Adapter\Redis and Utopia\Cache\Cache; test simulates Redis stop/start and verifies cache reconnect behavior (two identical insertions present in diff).

Sequence Diagram(s)

(omitted)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• updated pools #789 — Directly related: pools v1 upgrade and updating UtopiaPool constructor to accept an Adapter first.
• Fix pool tests #796 — Affects UtopiaPool constructor signature and adapter handling.

Suggested reviewers

• abnegate

Poem

I nibble bytes beneath the moon,
Adapters tucked in cozy tune,
Redis sleeps, then wakes to play,
Tests hop on, then pass the day,
Rabbit cheers — new versions bloom 🐇✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: upgrading the cache dependency (utopia-php/cache from 0.13.* to 1.0.*) to enable reconnection support, which is the primary objective of the PR.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@composer.json`:
- Around line 41-42: composer.json currently pins "utopia-php/cache" and
"utopia-php/pools" to 1.0.* but v1.0.0 contains breaking changes (PHP 8.4+
requirement and concurrency refactor); update the PR by either (a) pinning both
deps to the last compatible v0.x.y versions or (b) upgrading application code to
be compatible: ensure CI/test matrix uses PHP 8.4+, run and fix failing adapter
tests in src/Database/Database.php (Cache usage) and
src/Database/Adapter/Pool.php (Pool usage) to handle the new concurrent
behavior, and verify all adapter tests pass before merging.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Find usages of utopia-php/cache and utopia-php/pools in the codebase
cd "$(git rev-parse --show-toplevel)" 2>/dev/null || true

echo "=== Searching for Cache class/namespace usage ==="
rg -n 'Utopia\\Cache|use.*Cache' --type php -C2 | head -100

echo ""
echo "=== Searching for Pools class/namespace usage ==="
rg -n 'Utopia\\Pools|use.*Pool' --type php -C2 | head -100

echo ""
echo "=== Checking for direct instantiation/calls ==="
rg -n '(new Cache|Cache::|->cache\(|new Pool|Pool::)' --type php -C1 | head -50

echo ""
echo "=== Current composer.json versions ==="
rg '"utopia-php/(cache|pools)"' composer.json -A1

Repository: utopia-php/database

Length of output: 10616

---

🌐 Web query:

utopia-php cache 1.0.0 release breaking changes

💡 Result:

As of January 28, 2026, utopia-php/cache 1.0.0 was released on GitHub, and the release notes do not call out any explicit breaking changes—they only mention: “Implement Reconnection for caches” (PR #61). [1]

That said, the main upgrade risk / likely breaking change I can confirm from the 1.0.0 code changes is a dependency constraint bump:

• utopia-php/pools requirement changed from 0.8.* → 1.* (in composer.json). This can break installs that are pinned to utopia-php/pools 0.x or have other dependencies that still require 0.x. [2]

Also note: Packagist may lag GitHub—at the time of this check, Packagist still showed 0.13.1 as the latest published version for utopia-php/cache, so composer require utopia-php/cache:^1.0 may not resolve until Packagist updates. [3]

Sources:
[1] (github.com)
[2] (github.com)
[3] (packagist.org)

Citations:

• 1: https://github.com/utopia-php/cache/releases/tag/1.0.0
• 2: utopia-php/cache@d3cb826
• 3: https://packagist.org/packages/utopia-php/cache

---

🌐 Web query:

utopia-php pools 1.0.0 release breaking changes

💡 Result:

For utopia-php/pools v1.0.0 (released Jan 16, 2026), the project’s release notes do not list any explicit API “breaking changes”, but there are two practical breaking-impact items to be aware of:

• PHP minimum version bump: Packagist shows v1.0.0 requires PHP >=8.4 (whereas the prior 0.8.x line required >=8.3). This is a breaking change for anyone running PHP 8.3 or lower. [1]
• Concurrency-focused refactor: The only functional change called out in the v1.0.0 release notes is “Refactoring pools for concurrent operations” (PR #24). This may affect behavior in concurrent/coroutine usage even if method signatures stayed the same. [2]

Sources:
[1] Packagist package page (shows v1.0.0/v1.0.1 and PHP requirement) (root.packagist.org)
[2] GitHub v1.0.0 release notes (github.com)

Citations:

• 1: https://root.packagist.org/packages/utopia-php/pools
• 2: https://github.com/utopia-php/pools/releases/tag/1.0.0

---

Resolve breaking changes in major version upgrades before merging.

Both dependencies have confirmed breaking changes in v1.0.0:

• utopia-php/pools: PHP minimum version bumped from 8.3 to 8.4+ (hard requirement) and refactored for concurrent operations (PR #24), which may affect runtime behavior.
• utopia-php/cache: Dependency on utopia-php/pools upgraded to v1.0.

The codebase actively uses both packages (Cache in src/Database/Database.php and Pool in src/Database/Adapter/Pool.php). Given that adapter tests are "not yet passing," verify:

1. PHP 8.4+ is available in test/deployment environment
2. Pool concurrency behavior is compatible with current usage patterns
3. All adapter tests pass before merging

🤖 Prompt for AI Agents

In `@composer.json` around lines 41 - 42, composer.json currently pins
"utopia-php/cache" and "utopia-php/pools" to 1.0.* but v1.0.0 contains breaking
changes (PHP 8.4+ requirement and concurrency refactor); update the PR by either
(a) pinning both deps to the last compatible v0.x.y versions or (b) upgrading
application code to be compatible: ensure CI/test matrix uses PHP 8.4+, run and
fix failing adapter tests in src/Database/Database.php (Cache usage) and
src/Database/Adapter/Pool.php (Pool usage) to handle the new concurrent
behavior, and verify all adapter tests pass before merging.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@tests/e2e/Adapter/Scopes/GeneralTests.php`:
- Around line 702-769: Wrap the body of testCacheReconnect in a try/finally:
before changing state, save the original cache (call getCache()/setCache
references) and the current authorization state; in the try do the Redis
stop/start, create Cache with RedisAdapter and run assertions; in finally always
ensure Redis is started (use a readiness probe: reconnect loop that new
\Redis()->connect('redis',6379) and ->ping() with retries instead of sleep),
call $database->getAuthorization()->reset(), restore the original cache via
$database->setCache(...), and delete the test collection only if
$database->collectionExists('testCacheReconnect') (or similar exists() call) to
guarantee cleanup even on failures. Reference: testCacheReconnect,
Database::setCache/getCache, RedisAdapter::setMaxRetries,
Database::getAuthorization/reset, createCollection/deleteCollection/exists.