Repository Pattern

Purpose and Scope

The Repository class provides a unified, high-level API for all cache operations in the hypervel/cache system. It acts as an abstraction layer that wraps any concrete Store implementation, adding event dispatching, TTL calculation, type-safe retrieval methods, and convenience patterns like "remember" for lazy computation. This abstraction enables consistent cache interactions regardless of the underlying storage backend (Redis, Database, Swoole, File, etc.).

For information about the underlying storage implementations, see Store Contracts and Cache Stores. For the factory that creates Repository instances, see Cache Manager. For event details, see Event System.

Architecture Overview

The Repository class is the primary interface through which application code interacts with the cache system. It wraps a Store implementation and delegates storage operations to it while providing additional functionality.

Repository Structure

Sources: src/Repository.php37-71

Key Properties

Property	Type	Purpose
store	Store	The underlying storage backend implementation
events	EventDispatcherInterface	Event dispatcher for cache operation events
default	int	Default TTL in seconds (3600 by default)
config	array	Store configuration including store name

Sources: src/Repository.php44-62

Core Cache Operations

The Repository provides a comprehensive API for cache operations, with all operations dispatching events for observability.

Reading from Cache

Read Methods:

Method	Parameters	Returns	Description
get()	string|array $key, mixed $default	mixed	Retrieve single item or multiple items
many()	array $keys	array	Retrieve multiple items by keys
getMultiple()	iterable $keys, mixed $default	iterable	PSR-16 compatible batch retrieval
has()	string|array $key	bool	Check if item exists
missing()	string $key	bool	Check if item doesn't exist
pull()	string $key, mixed $default	mixed	Retrieve and delete in one operation

Sources: src/Repository.php94-186

Writing to Cache

Write Methods:

Method	Parameters	Returns	Description
put()	string|array $key, mixed $value, int|null $ttl	bool	Store item with TTL
set()	string $key, mixed $value, int|null $ttl	bool	Alias for put()
putMany()	array $values, int|null $ttl	bool	Store multiple items
setMultiple()	iterable $values, int|null $ttl	bool	PSR-16 compatible batch write
add()	string $key, mixed $value, int|null $ttl	bool	Store only if key doesn't exist
forever()	string $key, mixed $value	bool	Store without expiration

Special Behaviors:

• If $ttl is null, put() calls forever()
• If $ttl is <= 0, put() calls forget() to delete the key
• add() delegates to Store::add() if available for atomic operation
• All methods dispatch corresponding events before and after operation

Sources: src/Repository.php191-330

Deleting from Cache

Method	Parameters	Returns	Description
forget()	string $key	bool	Remove single item
delete()	string $key	bool	Alias for forget()
deleteMultiple()	iterable $keys	bool	Remove multiple items
clear()	-	bool	Flush entire cache

Events Dispatched:

• forget(): ForgettingKey → KeyForgotten or KeyForgetFailed
• clear(): CacheFlushing → CacheFlushed or CacheFlushFailed

Sources: src/Repository.php397-443

Remember Pattern

The Repository implements convenience methods for lazy computation and caching - the "remember" pattern.

Remember Methods Flow

Remember Method Variants

Method	Signature	Behavior
remember()	remember(string $key, int|null $ttl, Closure $callback)	Get from cache or execute callback and store with TTL
rememberForever()	rememberForever(string $key, Closure $callback)	Get from cache or execute callback and store forever
sear()	sear(string $key, Closure $callback)	Alias for rememberForever()

Example Usage:

The callback is only executed if the key is not found in cache, making this pattern ideal for expensive computations or database queries.

Sources: src/Repository.php341-394

Type-Safe Retrieval Methods

The Repository provides type-safe getter methods that validate and coerce cached values to specific types, throwing InvalidArgumentException if type validation fails.

Type-Safe Method Matrix

Type Method Details

Method	Return Type	Coercion	Validation
string()	string	None	Must be exactly string
integer()	int	Yes	String to int if valid
float()	float	Yes	String to float if valid
boolean()	bool	None	Must be exactly bool
array()	array	None	Must be exactly array

Error Handling:

All type-safe methods throw Hypervel\Cache\Exceptions\InvalidArgumentException with descriptive error messages when type validation fails:

"Cache value for key [user.name] must be a string, integer given."

Sources: src/Repository.php570-665

Atomic Operations

The Repository delegates atomic increment/decrement operations directly to the underlying store.

Method	Parameters	Returns	Description
increment()	string $key, int $value = 1	int|bool	Increment numeric value
decrement()	string $key, int $value = 1	int|bool	Decrement numeric value

These operations are atomic at the store level (e.g., Redis INCR/DECR commands), making them safe for concurrent access.

Sources: src/Repository.php298-312

Array Access Interface

The Repository implements ArrayAccess, enabling array-like syntax for cache operations.

Array Access Mapping

Behavior:

• offsetSet() uses the repository's default TTL for expiration
• All operations maintain the same event dispatching as their method equivalents

Sources: src/Repository.php524-563

Event System Integration

The Repository dispatches events for all cache operations, enabling comprehensive observability and logging.

Event Dispatch Timeline

Complete Event List

Operation	Before Event	Success Event	Failure Event
get()	RetrievingKey	CacheHit	CacheMissed
many()	RetrievingManyKeys	CacheHit (per key)	CacheMissed (per key)
put()	WritingKey	KeyWritten	KeyWriteFailed
putMany()	WritingManyKeys	KeyWritten (per key)	KeyWriteFailed (per key)
forget()	ForgettingKey	KeyForgotten	KeyForgetFailed
clear()	CacheFlushing	CacheFlushed	CacheFlushFailed

All events include the store name and relevant context (keys, values, TTL).

Sources: src/Repository.php124-137 src/Repository.php207-214 src/Repository.php401-409 src/Repository.php432-441 src/Repository.php730-733

Tagged Caching Support

The Repository provides access to tagged caching functionality when the underlying store supports it.

Tag Support Flow

Tag Methods

Method	Signature	Returns	Description
tags()	tags(mixed $names): TaggedCache	TaggedCache	Begin tagged cache operation
supportsTags()	supportsTags(): bool	bool	Check if store supports tagging

Behavior:

• Only RedisStore supports tagging in this implementation
• Throws BadMethodCallException if store doesn't support tags
• Returns a TaggedCache instance with events and default TTL configured
• For details on tagged caching, see Cache Tagging

Sources: src/Repository.php445-472

Configuration and Metadata

The Repository provides methods to access and configure its properties.

Configuration Methods

Method	Signature	Purpose
getStore()	getStore(): Store	Access underlying store implementation
getEventDispatcher()	getEventDispatcher(): ?EventDispatcherInterface	Get event dispatcher
setEventDispatcher()	setEventDispatcher(EventDispatcherInterface $events): void	Set event dispatcher
getName()	getName(): ?string	Get store name from config
getDefaultCacheTime()	getDefaultCacheTime(): ?int	Get default TTL in seconds
setDefaultCacheTime()	setDefaultCacheTime(?int $seconds): static	Set default TTL

Store Name:

The store name comes from $config['store'] and is used in all event dispatching to identify which cache store generated the event.

Sources: src/Repository.php477-522

Extensibility

The Repository is designed for extensibility through the Macroable trait and magic method delegation.

Extensibility Mechanisms

Macro Support

The Macroable trait allows registering custom methods on the Repository class:

Store Method Delegation

The __call magic method delegates unknown method calls to the underlying store, enabling direct access to store-specific functionality:

This delegation pattern is documented in the class docblock: @mixin \Hypervel\Cache\Contracts\Store

Sources: src/Repository.php35-36 src/Repository.php40-42 src/Repository.php74-83

TTL Calculation and Time Handling

The Repository uses the InteractsWithTime trait to handle various TTL formats.

TTL Format Support

Input Type	Example	Behavior
int	3600	Direct seconds
DateInterval	new DateInterval('PT1H')	Converted to seconds
DateTimeInterface	Carbon::now()->addHour()	Calculates diff from now
null	null	Stores forever
<= 0	-1 or 0	Deletes the key

The getSeconds() method normalizes all TTL formats to integer seconds:

Sources: src/Repository.php14 src/Repository.php39 src/Repository.php714-725

Key Formatting

The itemKey() method provides a hook for key transformation before passing to the store.

In the base Repository, this is a no-op pass-through. However, it can be overridden in subclasses (like TaggedCache) to add prefixes or namespace keys.

Sources: src/Repository.php707-711

PSR-16 SimpleCache Compliance

The Repository implements PSR-16 SimpleCache interface through the CacheContract interface, providing standard cache methods:

PSR-16 Method	Repository Method	Notes
get()	get()	Direct implementation
set()	set() / put()	set() is alias
delete()	delete() / forget()	delete() is alias
clear()	clear()	Direct implementation
getMultiple()	getMultiple()	Delegates to many()
setMultiple()	setMultiple()	Delegates to putMany()
deleteMultiple()	deleteMultiple()	Iterates forget()
has()	has()	Direct implementation

Sources: src/Repository.php15 src/Repository.php37 src/Repository.php161-170 src/Repository.php257-260 src/Repository.php412-428