Taggable Cache Laravel Package

Getting Started

Start by installing the package via Composer:

composer require cache/taggable-cache

This package provides a decorator that wraps any PSR-6 pool to add tagging support — it does not implement caching itself. First, instantiate a base PSR-6 pool (e.g., PhpBuffersPool, ArrayPool, or a Doctrine/Filesystem pool), then wrap it with Cache\Taggable\TaggableCachePool. Example:

$pool = new \Cache\Taggable\TaggableCachePool(new \Cache\Adapter\ ArrayAdapter());
$pool->save($pool->getItem('user:123')->set($userData)->tag(['users', 'profile']));

The most common first use case is caching entities by ID with associated tags (e.g., post:42 tagged with posts, author:5) to enable invalidating all posts by author 5 later.

Implementation Patterns

• Tagging on Save: Always tag items during save() or saveDeferred() — tags are attached via ItemInterface::tag(['tag1', 'tag2']).
• Bulk Invalidation: Use TaggableCachePool::clearTags(['tag1', 'tag2']) to evict all items with matching tags.
• Nested / Hierarchical Tags: Though tags are flat strings, adopt a naming convention (e.g., model:Post:123, author:5) to simulate grouping.
• Laravel Integration: Wrap Laravel’s default cache driver (Cache::driver()->getStore()) in a TaggableCachePool and inject it where tagging is needed (though native Cache::tags() is preferred in Laravel unless special tagging behavior is required).
• Lazy Loading: For deferred operations, remember to commit() after saveDeferred(), and tags are stored persistently with the item.
• Integration with Adapters: Works seamlessly with PSR-6 adapters like php-cache/filesystem, php-cache/apcu, or symfony/cache (via Symfony\Component\Cache\Adapter\ArrayAdapter).

Gotchas and Tips

• Tag Name Validation: Tags must be non-empty strings; invalid characters or null throw InvalidArgumentException. Normalize tag names consistently (e.g., mb_strtolower, slugify).
• No Native Tag Indexing: Tagged items rely on internal metadata stored with each item — clearing tags requires scanning underlying storage, which may be slow for large pools or filesystem-based adapters. For high-scale apps, consider a dedicated tag store (e.g., Redis-based tagging wrapper).
• Compatibility with PSR-6: This package extends PSR-6 via decoration — all standard getItem, save, etc., behave normally, but clearTags() is the only non-standard method.
• Memory Use: Tags increase item size slightly (metadata stored alongside payload). Avoid excessive tagging per item (e.g., >5 tags).
• Deferred Items: Tags attached to deferred items are only persisted on commit() — if the script exits before commit, tags are lost.
• Debugging: Enable adapter logging to see tag overhead (e.g., extra write operations during save() with tags).
• Future Proofing: The package is stable but unmaintained since 2022. For new projects, consider migrating to PSR-6-compatible tagging via php-cache/cache or PSR-16 (simple cache) alternatives like symfony/cache with tags (though PSR-16 doesn’t standardize tags).