Cache Tagging

Purpose and Scope

This document covers the Redis-based cache tagging system, which enables grouping related cache entries under one or more tags for bulk invalidation. The tagging functionality is implemented through the RedisTagSet and RedisTaggedCache classes and relies exclusively on the Redis storage backend.

For information about the underlying Redis storage implementation, see Redis Store. For general distributed locking mechanisms, see Distributed Locking.

---

Overview

Cache tagging allows multiple cache entries to be associated with one or more string identifiers (tags) and subsequently invalidated as a group. This is particularly useful for scenarios where cache entries have logical relationships, such as:

• Invalidating all cached data related to a specific user
• Clearing product-related cache entries when inventory changes
• Removing category-based caches when taxonomies are updated

The implementation uses Redis sorted sets to maintain tag-to-entry mappings, with scores representing expiration timestamps for automatic stale entry detection.

Sources: src/RedisTagSet.php1-122 src/RedisTaggedCache.php1-125

---

Architecture

The tagging system consists of two primary classes that work in conjunction with the Redis storage backend:

Key Components:

Component	File	Responsibility
RedisTaggedCache	src/RedisTaggedCache.php	Extends TaggedCache to intercept cache operations and maintain tag associations
RedisTagSet	src/RedisTagSet.php	Manages tag metadata using Redis sorted sets, handles entry addition and retrieval
RedisStore	src/RedisStore.php	Provides Redis connection and basic operations

Sources: src/RedisTaggedCache.php1-125 src/RedisTagSet.php1-122

---

Tag Storage Mechanism

Tags are stored in Redis sorted sets where:

• Key: tag:{name}:entries (with cache prefix applied)
• Member: The full cache key (including prefix)
• Score: Expiration timestamp (Unix timestamp) or -1 for permanent entries

The tagId() and tagKey() methods both return the same format: tag:{name}:entries. This identifier is used as the Redis sorted set key.

Sources: src/RedisTagSet.php110-121

---

Adding Entries to Tags

When cache operations occur on tagged cache instances, entries are automatically registered in all associated tag sets:

The addEntry() method in RedisTagSet handles the registration:

src/RedisTagSet.php22-33

Parameter	Type	Purpose
$key	string	The cache key (with prefix)
$ttl	int	Time-to-live in seconds (0 for permanent)
$updateWhen	?string	Redis option like 'NX' (only if not exists)

The score calculation converts TTL to Unix timestamp: now()->addSeconds($ttl)->getTimestamp(), or -1 for permanent entries.

Sources: src/RedisTagSet.php22-33 src/RedisTaggedCache.php43-59

---

Cache Operations with Tags

Each cache operation method in RedisTaggedCache registers the entry with its tags before delegating to the parent implementation:

Write Operations

Method Implementations:

• put() src/RedisTaggedCache.php43-59 - Adds entry with TTL before storing
• add() src/RedisTaggedCache.php30-38 - Adds entry only if key doesn't exist
• forever() src/RedisTaggedCache.php84-89 - Adds entry with score -1 for no expiration
• increment()/decrement() src/RedisTaggedCache.php64-79 - Use 'NX' option to avoid overwriting existing entries

Sources: src/RedisTaggedCache.php30-89

---

Retrieving Tagged Entries

The entries() method returns a lazy collection of all cache keys associated with the tag set:

Implementation details src/RedisTagSet.php38-75:

• Uses Redis ZSCAN for efficient iteration over large sorted sets
• Handles cursor-based pagination with 1000 entries per scan
• Accommodates different PHP Redis extension versions for cursor default values
• Returns LazyCollection to avoid loading all entries into memory at once

Sources: src/RedisTagSet.php38-75

---

Flushing Tagged Entries

The tagging system provides multiple flush operations with different scopes:

Complete Flush

RedisTaggedCache::flush() removes all entries associated with any of the tags:

The implementation src/RedisTaggedCache.php94-114:

1. Retrieves all entries via entries()
2. Chunks keys into batches of 1000
3. Deletes cache values with DEL command
4. Clears tag metadata with flush()

Tag-Specific Flush

RedisTagSet::flushTag() invalidates a single tag by resetting its sorted set:

src/RedisTagSet.php92-105

This operation:

1. Forgets the tag key from Redis (FORGET tag:{name}:entries)
2. Returns a new tag identifier (effectively the same format)
3. Orphans existing tagged entries (they remain in cache but are no longer associated)

Sources: src/RedisTaggedCache.php94-114 src/RedisTagSet.php92-105

---

Stale Entry Management

The tagging system includes automatic cleanup of expired entries from tag sets:

Flush Stale Entries

RedisTagSet::flushStaleEntries() removes entries with expired TTLs from tag sorted sets:

src/RedisTagSet.php80-87

The operation uses:

• ZREMRANGEBYSCORE to remove members with scores between 0 and current timestamp
• Redis pipeline for batching multiple tag operations efficiently
• Scores of -1 (permanent entries) are preserved since they're below the range

This is exposed via RedisTaggedCache::flushStale() src/RedisTaggedCache.php119-124

Important: This only removes references from tag sets, not the actual cache entries. Expired cache keys are handled by Redis TTL expiration or explicit deletion.

Sources: src/RedisTagSet.php80-87 src/RedisTaggedCache.php119-124

---

Code Entity Reference

Class Methods Mapping

Natural Language	Code Entity	File Reference
Register cache key with tags	RedisTagSet::addEntry()	src/RedisTagSet.php22-33
Get all tagged entries	RedisTagSet::entries()	src/RedisTagSet.php38-75
Remove expired tag references	RedisTagSet::flushStaleEntries()	src/RedisTagSet.php80-87
Invalidate specific tag	RedisTagSet::flushTag()	src/RedisTagSet.php92-95
Reset tag metadata	RedisTagSet::resetTag()	src/RedisTagSet.php100-105
Get tag sorted set key	RedisTagSet::tagId()	src/RedisTagSet.php110-113
Get tag key format	RedisTagSet::tagKey()	src/RedisTagSet.php118-121
Store with tags	RedisTaggedCache::put()	src/RedisTaggedCache.php43-59
Conditional store with tags	RedisTaggedCache::add()	src/RedisTaggedCache.php30-38
Increment tagged value	RedisTaggedCache::increment()	src/RedisTaggedCache.php64-69
Decrement tagged value	RedisTaggedCache::decrement()	src/RedisTaggedCache.php74-79
Store permanently with tags	RedisTaggedCache::forever()	src/RedisTaggedCache.php84-89
Remove all tagged entries	RedisTaggedCache::flush()	src/RedisTaggedCache.php94-100
Delete tagged cache values	RedisTaggedCache::flushValues()	src/RedisTaggedCache.php105-114
Clean up stale references	RedisTaggedCache::flushStale()	src/RedisTaggedCache.php119-124

Redis Command Usage

Operation	Redis Command	Purpose	Location
Add entry to tag	ZADD	Insert cache key with expiration score	src/RedisTagSet.php28-31
Scan tag entries	ZSCAN	Iterate over all members in tag set	src/RedisTagSet.php52-57
Remove expired	ZREMRANGEBYSCORE	Delete members with scores in range	src/RedisTagSet.php84
Delete cache values	DEL	Remove actual cache entries	src/RedisTaggedCache.php112

Sources: src/RedisTagSet.php1-122 src/RedisTaggedCache.php1-125