Cache Watcher

Purpose and Scope

The CacheWatcher class monitors cache operations by listening to cache events dispatched by Hypervel's cache system. It records four types of cache operations: hits (key found), misses (key not found), writes (key set/updated), and deletions (key forgotten). All recorded entries are sent to Telescope::recordCache() for storage.

This watcher requires two-phase initialization because cache events must be enabled in configuration before cache stores instantiate. See page 2.3.1 for base watcher pattern details and page 2.1.1 for entry recording mechanics.

Sources: src/Watchers/CacheWatcher.php1-155

---

Class Structure and Dependencies

The CacheWatcher class extends Watcher and uses event listeners to monitor cache operations. Unlike other watchers, it requires configuration changes to enable cache events before the cache system initializes.

CacheWatcher Class Diagram

Key Components

Component	Location	Role
CacheWatcher::$eventsEnabled	src/Watchers/CacheWatcher.php23	Static flag indicating if cache events are configured
CacheWatcher::enableCacheEvents()	src/Watchers/CacheWatcher.php46-54	Modifies cache store configs to enable event dispatching
CacheWatcher::register()	src/Watchers/CacheWatcher.php28-40	Registers event listeners with EventDispatcherInterface
TelescopeServiceProvider::registerCacheEvents()	Referenced in initialization	Calls enableCacheEvents() during registration phase

Sources: src/Watchers/CacheWatcher.php18-155

---

Two-Phase Initialization Process

Cache events must be enabled in cache store configurations before the cache system instantiates. This requires initialization in two phases coordinated by TelescopeServiceProvider.

Initialization Sequence Diagram

Phase Details

Phase 1: Configuration Modification (src/Watchers/CacheWatcher.php46-54)

1. CacheWatcher::enableCacheEvents() retrieves all cache store keys from config('cache.stores')
2. For each store, sets cache.stores.{store}.events to true
3. Sets static property CacheWatcher::$eventsEnabled = true

Phase 2: Event Listener Registration (src/Watchers/CacheWatcher.php28-40)

1. CacheWatcher::register() checks if $eventsEnabled is true
2. If false, returns early without registering listeners
3. If true, registers four event listeners via EventDispatcherInterface::listen()

This pattern prevents listener registration if cache events are not enabled in configuration.

Sources: src/Watchers/CacheWatcher.php28-54

---

Event-Based Monitoring

The CacheWatcher listens to four cache event types dispatched by Hypervel's cache system. Each event type corresponds to a specific cache operation.

Monitored Cache Events

Event Class	Operation	Recorded Type	Data Captured
CacheHit	Cache key found and retrieved	hit	key, value
CacheMissed	Cache key not found	missed	key
KeyWritten	Cache key set or updated	set	key, value, expiration
KeyForgotten	Cache key deleted	forget	key

Event Recording Methods

Each cache event type has a dedicated recording method in CacheWatcher:

Cache Hit Recording:

recordCacheHit(CacheHit $event)
├─ Checks Telescope::isRecording()
├─ Checks shouldIgnore($event)
├─ Formats value with formatValue($event)
└─ Calls Telescope::recordCache() with type='hit'

Cache Miss Recording:

recordCacheMissed(CacheMissed $event)
├─ Checks Telescope::isRecording()
├─ Checks shouldIgnore($event)
└─ Calls Telescope::recordCache() with type='missed'

Cache Write Recording:

recordKeyWritten(KeyWritten $event)
├─ Checks Telescope::isRecording()
├─ Checks shouldIgnore($event)
├─ Formats value with formatValue($event)
├─ Formats expiration with formatExpiration($event)
└─ Calls Telescope::recordCache() with type='set'

Cache Deletion Recording:

recordKeyForgotten(KeyForgotten $event)
├─ Checks Telescope::isRecording()
├─ Checks shouldIgnore($event)
└─ Calls Telescope::recordCache() with type='forget'

Sources: src/Watchers/CacheWatcher.php59-117

---

Configuration

The CacheWatcher is configured in the config/telescope.php file under the watchers array. It supports enabling/disabling and privacy controls.

Configuration Options

The CacheWatcher is configured via the watchers array in config/telescope.php:

Option	Type	Default	Purpose
enabled	bool	env('TELESCOPE_CACHE_WATCHER', true)	Enables/disables cache monitoring
hidden	array	[]	Cache key patterns for value masking

Configuration Example:

Hidden Key Pattern Matching: The hidden array accepts wildcard patterns. Cache values for keys matching any pattern are replaced with '********' in recorded entries. Pattern matching uses Hyperf\Stringable\Str::is() for wildcard support.

Sources: src/Watchers/CacheWatcher.php132-138

---

Data Recording Process

When a cache operation occurs and events are enabled, the following process executes to record the entry in Telescope.

Cache Entry Recording Flow

Entry Data Structure

Each recorded cache entry includes the following data passed to IncomingEntry::make():

Event Type	Entry Type	Fields
CacheHit	"hit"	key, value (masked if hidden)
CacheMissed	"missed"	key
KeyWritten	"set"	key, value (masked if hidden), expiration
KeyForgotten	"forget"	key

Sources: src/Watchers/CacheWatcher.php65-117

---

Value Privacy and Filtering

The CacheWatcher implements two filtering mechanisms to prevent sensitive data exposure and reduce noise in Telescope entries.

Value Masking Implementation

Method: shouldHideValue() (src/Watchers/CacheWatcher.php132-138)

• Retrieves $this->options['hidden'] array from watcher configuration
• Uses Hyperf\Stringable\Str::is() for pattern matching against $event->key
• Returns true if key matches any pattern in hidden array

Method: formatValue() (src/Watchers/CacheWatcher.php122-127)

• Calls shouldHideValue($event)
• If true: returns '********'
• If false: returns $event->value

Automatic Key Filtering

Method: shouldIgnore() (src/Watchers/CacheWatcher.php148-154)

Filters internal system cache keys to prevent recursive recording:

Pattern	Purpose
illuminate:queue:restart	Queue system control key
telescope:*	All Telescope internal keys (including telescope:pause-recording)

This check executes at the start of each recordCacheX() method before value formatting or entry creation.

Sources: src/Watchers/CacheWatcher.php122-154

---

Expiration Time Formatting

Method: formatExpiration() (src/Watchers/CacheWatcher.php140-143)

Returns the TTL in seconds from a KeyWritten event object. Implementation:

return $event->seconds;

The method receives the TTL directly from the $event->seconds property. This value is included in entries with type "set" under the expiration field.

Sources: src/Watchers/CacheWatcher.php140-143

---

Integration Summary

The CacheWatcher integrates with multiple system components:

Component	Integration Point	Purpose
TelescopeServiceProvider	registerCacheEvents()	Enables cache events during registration phase
ConfigInterface	cache.stores.*.events	Configures event firing in cache stores
EventDispatcherInterface	Event listeners	Receives cache operation events
Telescope	recordCache()	Records formatted entries
Cache System	Events fired	Source of cache operation data

The watcher is unique among Telescope watchers in requiring pre-initialization configuration changes to the cache system itself, rather than simply listening to existing events.

Sources: src/Watchers/CacheWatcher.php1-157 src/TelescopeServiceProvider.php139-146