Cache Management

Purpose and Scope

This document explains caching operations via the Cache facade, including basic get/put/forget patterns, advanced remember operations, cache stores and drivers, tagging, locking mechanisms, and multi-key operations. Cache Management provides a unified interface for multiple cache backends (Redis, Memcached, file-based, etc.) through the Manager pattern.

For database operations, see Database Operations. For Redis-specific operations beyond caching, see Redis Operations. For general Manager pattern architecture, see Manager Pattern.

---

Cache System Architecture

The cache system follows a layered architecture where the Cache facade provides a static interface to the CacheManager, which manages multiple cache stores/drivers. Each store wraps an underlying cache backend implementation.

Sources: src/Facades/Cache.php1-68

---

Cache Facade Methods

The Cache facade exposes a comprehensive set of methods organized by functionality:

Method Categories

Category	Methods	Description
Driver Management	store(), driver(), getDefaultDriver(), setDefaultDriver(), forgetDriver()	Manage cache stores and default driver
Basic Operations	get(), set(), put(), forget(), delete(), clear(), flush(), has(), missing()	Fundamental cache read/write/delete operations
Remember Patterns	remember(), rememberForever(), sear(), pull()	Retrieve or compute and cache values
Modification	add(), increment(), decrement(), forever()	Conditional writes and atomic operations
Multiple Keys	many(), putMany(), getMultiple(), setMultiple(), deleteMultiple()	Batch operations for efficiency
Tagging	tags(), supportsTags()	Group cache entries for bulk invalidation
Locking	lock(), restoreLock()	Distributed locking mechanisms
Configuration	getPrefix(), getName(), getDefaultCacheTime(), setDefaultCacheTime()	Runtime configuration access

Sources: src/Facades/Cache.php9-57

---

Store and Driver Management

The cache system uses the Manager pattern to support multiple cache stores. Each store represents a connection to a cache backend.

Driver Resolution Methods

Method	Signature	Purpose
store()	store(?string $name = null): Repository	Resolve a specific named store or default
driver()	driver(?string $driver = null): Repository	Alias for store()
repository()	repository(Store $store, array $config = []): Repository	Create repository from store instance
extend()	extend(string $driver, Closure $callback): CacheManager	Register custom driver implementation
forgetDriver()	forgetDriver(array|string|null $name = null): CacheManager	Remove cached driver instance

Sources: src/Facades/Cache.php10-19

---

Basic Cache Operations

Read Operations

The cache provides multiple methods for retrieving values:

Method	Return Type	Behavior
get(string $key, mixed $default = null)	mixed	Retrieve value or return default (evaluates closures)
has(string $key)	bool	Check if key exists
missing(string $key)	bool	Inverse of has()
many(array $keys)	array	Retrieve multiple keys at once
getMultiple(iterable $keys, mixed $default = null)	iterable	PSR-16 compatible batch retrieval

Sources: src/Facades/Cache.php31-46

Write Operations

Write operations support various TTL (time-to-live) formats:

Method	Parameters	TTL Support	Behavior
put()	(string|array $key, mixed $value, int|DateInterval|DateTimeInterface|null $ttl)	Yes	Store value with optional TTL
set()	(string $key, mixed $value, int|DateInterval|null $ttl)	Yes	PSR-16 alias for put()
add()	(string $key, mixed $value, int|DateInterval|DateTimeInterface|null $ttl)	Yes	Store only if key doesn't exist
forever()	(string $key, mixed $value)	No (infinite)	Store value indefinitely
putMany()	(array $values, int $seconds)	Yes (seconds)	Store multiple key-value pairs
setMultiple()	(iterable $values, int|DateInterval|null $ttl)	Yes	PSR-16 batch write

Sources: src/Facades/Cache.php21-43

Delete Operations

Method	Parameters	Return	Description
forget()	(string $key)	bool	Remove single key
delete()	(string $key)	bool	PSR-16 alias for forget()
deleteMultiple()	(iterable $keys)	bool	Remove multiple keys
clear()	none	bool	PSR-16 remove all entries
flush()	none	bool	Remove all entries from store
purge()	(?string $name)	void	Purge specific store or all stores

Sources: src/Facades/Cache.php17-44

---

Remember Patterns

Remember patterns combine retrieval and computation, caching the result if it doesn't exist:

Remember Method Comparison

Method	TTL	Use Case
remember(string $key, int|DateInterval|DateTimeInterface|null $ttl, Closure $callback)	Configurable	Standard caching with expiration
rememberForever(string $key, Closure $callback)	Infinite	Long-lived computed values
sear(string $key, Closure $callback)	Infinite	Alias for rememberForever()
pull(string $key, mixed $default = null)	N/A (deletes)	Retrieve once then remove

Sources: src/Facades/Cache.php20-28

---

Atomic Operations

Atomic operations provide thread-safe increment and decrement functionality:

Method	Return Type	Behavior
increment(string $key, int $value = 1)	int|bool	Atomically increase value by amount
decrement(string $key, int $value = 1)	int|bool	Atomically decrease value by amount

If the key doesn't exist, it is typically initialized to 0 before the operation. Backend support varies:

• Redis/Memcached: Native atomic operations
• File/Database stores: Simulated via locking

Sources: src/Facades/Cache.php23-24

---

Cache Tagging

Cache tagging allows grouping related cache entries for efficient bulk invalidation:

Tagging Support by Store

Store Type	Tags Supported	Implementation
Redis	✓ Yes	Tag namespace keys
Memcached	✓ Yes	Tag revision tracking
File	✗ No	N/A
Database	✗ No	N/A
Array	✓ Yes	In-memory tracking

Tagged Cache Methods

Method	Purpose
tags(mixed $names): TaggedCache	Create tagged cache instance with one or more tags
supportsTags(): bool	Check if current store supports tagging
flush()	When called on tagged cache, invalidates all entries with those tags

Sources: src/Facades/Cache.php41-47

---

Cache Locking

Cache locks provide distributed locking for coordinating work across multiple processes or servers:

Lock Interface Methods

Method	Return Type	Description
lock(string $name, int $seconds = 0, ?string $owner = null)	Lock	Create lock instance with optional TTL and owner ID
restoreLock(string $name, string $owner)	Lock	Restore existing lock using owner token
get(?callable $callback = null)	bool|mixed	Attempt to acquire lock; execute callback if successful
block(int $seconds, ?callable $callback = null)	bool|mixed	Wait up to N seconds to acquire lock
release()	bool	Release owned lock
forceRelease()	void	Force release lock regardless of owner
owner()	string	Get lock owner identifier

Sources: src/Facades/Cache.php39-40

---

Cache Configuration Integration

The cache system integrates with repository-level configuration:

Method	Return Type	Purpose
getPrefix()	string	Retrieve key prefix for namespace isolation
getName()	?string	Get store name identifier
getDefaultCacheTime()	?int	Get default TTL in seconds
setDefaultCacheTime(?int $seconds)	Repository	Set default TTL for operations without explicit TTL

Sources: src/Facades/Cache.php45-52

---

Event Dispatcher Integration

Cache operations can trigger events for monitoring and logging:

Method	Parameters	Purpose
getEventDispatcher()	None	Retrieve current event dispatcher instance
setEventDispatcher(EventDispatcherInterface $events)	Dispatcher	Set event dispatcher for cache events
refreshEventDispatcher()	None	Re-resolve event dispatcher from container

Sources: src/Facades/Cache.php13-51

---

Macro Support

The cache system supports runtime extension via macros:

Method	Purpose
macro(string $name, callable|object $macro)	Register custom method
mixin(object $mixin, bool $replace = true)	Register multiple methods from mixin class
hasMacro(string $name)	Check if macro exists
macroCall(string $method, array $parameters)	Invoke registered macro

This allows adding custom cache patterns without modifying core classes.

Sources: src/Facades/Cache.php53-56

---

PSR-16 SimpleCache Compliance

The cache repository implements the PSR-16 SimpleCache interface:

PSR-16 Method	Cache Method	Notes
get()	get()	Direct mapping
set()	set() / put()	set() is PSR-16, put() is Laravel-style
delete()	delete() / forget()	delete() is PSR-16, forget() is Laravel-style
clear()	clear() / flush()	Both clear all cache entries
getMultiple()	getMultiple()	Batch retrieval
setMultiple()	setMultiple()	Batch storage
deleteMultiple()	deleteMultiple()	Batch deletion
has()	has()	Existence check

This enables interoperability with PSR-16 compliant libraries.

Sources: src/Facades/Cache.php31-38

---

Usage Patterns

Basic Caching Pattern

Remember Pattern

Tagged Cache Pattern

Lock Pattern

Atomic Counter Pattern

---

Store Management Patterns

Multi-Store Operations

Different cache stores can be used within the same application:

Sources: src/Facades/Cache.php10-18

---

Integration with Facade System

The Cache facade follows the standard facade pattern:

The facade resolves to \Hypervel\Cache\Contracts\Factory, which is bound to the CacheManager instance in the service container. This manager pattern enables runtime driver switching and custom driver registration.

Sources: src/Facades/Cache.php63-66

---

Summary

The Cache Management system provides:

• Unified Interface: Single facade for multiple cache backends
• Multiple Stores: Redis, Memcached, File, Database, Array support
• Rich Operations: Get/put/forget, remember patterns, atomic operations
• Advanced Features: Tagging, distributed locking, batch operations
• Standard Compliance: PSR-16 SimpleCache interface
• Extensibility: Manager pattern for custom drivers
• Event Integration: Cache operation events for monitoring
• Testing Support: Swappable and mockable for tests

For testing cache operations, see Testing Overview. For the underlying manager architecture, see Manager Pattern.