Adapter Common Laravel Package

Getting Started

Install via Composer: composer require cache/adapter-common. This package provides foundational classes (AbstractCachePool, CacheItem) for PSR-6 cache adapters but does not provide a working pool by itself. Your first step is to either:

• Use an existing adapter (e.g., cache/file-adapter, cache/array-adapter, symfony/cache adapters that depend on it), or
• Extend AbstractCachePool to build a custom adapter (implement doFetch(), doSave(), doDelete(), etc.).
  Start by examining CacheItem to understand item lifecycle (serialization, expiration, validation) and AbstractCachePool to see how deferred commits and logging are handled.

Implementation Patterns

• Custom Adapter Development: Extend AbstractCachePool and implement only backend-specific logic in do* methods. The base class handles PSR-6 boilerplate (deferred items, expiration math, validation).
• Tagging Workflows: Pair with cache/tag-interop (which this package often depends on). Use InvalidateTagCacheTrait or manually invalidate tags via save($item->expiresAt(time() - 1))—this exploits PSR-6’s expiration semantics for tag invalidation without extra storage.
• Logging & Debugging: AbstractCachePool implements LoggerAwareInterface—inject any PSR-3 logger (e.g., Laravel’s log() channel) to get automatic debug logs for fetch/save/deletes with cache keys and expiry details.
• Deferred Operations: Use defer($item) to queue items, then call commit() (typically once per request or job). Ideal for batch cache writes (e.g., after database transactions) or background tasks via queues.

Gotchas and Tips

• ⚠️ No standalone functionality: This package is only a foundation. Never install it alone expecting cache behavior—always pair with a real adapter (e.g., cache/array-adapter).
• ⚠️ commit() is mandatory for deferred items: Deferred items persist only on explicit commit() calls. Forgetting this is the #1 cause of “item vanished” bugs in custom adapters.
• ⚠️ Negative expiration = invalidation: Calling expiresAt(time() - 10) invalidates the item on save—this is intentional for tag cleanup, but may surprise newcomers expecting only expiry behavior.
• Protected access for extension: $deferred and $logger are protected, allowing subclass inspection or extension (e.g., custom logging filters), but avoid overriding core methods like save()—use doSave() instead.
• Validate against integration tests: Run tests from php-cache/integration-tests against your adapter to guarantee PSR-6 compliance—this package’s tests often expose edge cases (e.g., invalid key characters, null keys, concurrent commits).