Array and Null Stores

Purpose and Scope

This page documents the two simplest cache store implementations in the hypervel/cache system: ArrayStore and NullStore. These stores provide minimal caching functionality for specific use cases. ArrayStore offers in-memory volatile caching within a single process, while NullStore provides a no-op implementation that effectively disables caching.

For persistent storage options, see File Store and Database Store. For distributed caching, see Redis Store and Swoole Store. For multi-tier caching strategies, see Stack Store.

Sources: src/CacheManager.php204-207 src/CacheManager.php225-228 src/NullStore.php1-92

---

ArrayStore

Overview

ArrayStore provides in-memory caching using a PHP array as the storage backend. Data stored in this cache exists only for the lifetime of the current process and is not shared across requests or workers. This makes it suitable for caching data within a single request or for testing scenarios where persistence is not required.

The store supports optional serialization of cached values, controlled by the serialize configuration parameter. When serialization is enabled, values are serialized before storage and unserialized upon retrieval, mimicking the behavior of persistent stores.

Sources: src/CacheManager.php204-207

Configuration

The ArrayStore is configured in the cache.php configuration file under the stores array:

Configuration Key	Type	Default	Description
driver	string	'array'	Must be set to 'array'
serialize	bool	false	Whether to serialize values before storage

The serialize option is useful when testing code that will eventually use a persistent store, as it ensures that only serializable values can be cached.

Sources: src/CacheManager.php204-207

Store Creation Flow

Sources: src/CacheManager.php204-207 src/CacheManager.php74-81

Implementation Characteristics

The ArrayStore implements the Store interface and provides the following characteristics:

Operation	Behavior	Returns
get(key)	Retrieves value from internal array	Value or null
put(key, value, seconds)	Stores value in array with expiration	bool
forever(key, value)	Stores value without expiration	bool
increment(key, value)	Atomically increments numeric value	int
decrement(key, value)	Atomically decrements numeric value	int
forget(key)	Removes key from array	bool
flush()	Clears all cached items	bool

Key Characteristics:

• Volatility: All data is lost when the process terminates or restarts
• Scope: Data is not shared between different processes, workers, or requests
• Performance: Extremely fast as it uses in-memory PHP arrays
• Serialization: Optional, controlled by constructor parameter
• No Persistence: Data does not survive process restarts

Sources: src/CacheManager.php204-207

Lock Support

ArrayStore implements the LockProvider interface and creates ArrayLock instances for distributed locking. However, these locks are only effective within the same process and cannot provide distributed locking across multiple workers or servers.

Lock Characteristics:

• Scope: Process-local only, not distributed
• Refreshable: Supports lock renewal via RefreshableLock interface
• Fast: No I/O overhead, pure in-memory operations
• Non-persistent: Locks are lost on process termination

For distributed locking across workers or servers, see Distributed Locking.

Sources: src/CacheManager.php204-207

Use Cases

Use Case	Suitability	Rationale
Single-request caching	✓ Excellent	Fast, no overhead
Testing and development	✓ Excellent	Simple, no external dependencies
Unit tests	✓ Excellent	Predictable, isolated
Production caching	✗ Poor	Not persistent, not distributed
Multi-worker applications	✗ Poor	Data not shared between workers
Long-term storage	✗ Poor	Data lost on restart

Recommended Scenarios:

1. Development and Testing: When you need a quick cache without setting up Redis or other infrastructure
2. Request-Scoped Data: Caching computations that are only relevant within a single request
3. Unit Testing: Testing cache-dependent code without external dependencies
4. Prototyping: Quick prototyping before implementing persistent storage

Sources: src/CacheManager.php204-207

---

NullStore

Overview

NullStore is a no-op cache implementation that effectively disables caching. All retrieval operations return null, and all storage operations silently succeed without actually storing anything. This store is useful for temporarily disabling caching in development, testing specific scenarios without cache interference, or providing a cache instance in contexts where caching is not desired.

The store extends TaggableStore, providing tag-related methods that also perform no operations.

Sources: src/NullStore.php9-92 src/CacheManager.php225-228

Configuration

The NullStore requires minimal configuration and can be created on-demand:

Alternatively, it can be instantiated directly without configuration by requesting the 'null' driver:

The CacheManager treats 'null' as a special case and creates a NullStore with an empty configuration array.

Sources: src/CacheManager.php225-228 src/CacheManager.php329-334

Implementation Details

Sources: src/NullStore.php9-12

Operation Behavior

The NullStore implements all required cache operations with the following consistent behavior:

Method	Parameters	Return Value	Description
get(key)	string $key	null	Always returns null
put(key, value, seconds)	string $key, mixed $value, int $seconds	false	Always returns false
increment(key, value)	string $key, int $value	false	Always returns false
decrement(key, value)	string $key, int $value	false	Always returns false
forever(key, value)	string $key, mixed $value	false	Always returns false
forget(key)	string $key	true	Always returns true (success)
flush()	-	true	Always returns true (success)
getPrefix()	-	''	Always returns empty string

Key Behavioral Notes:

• Retrieval Operations: Always return null, indicating cache miss
• Write Operations: Return false, indicating failure to write
• Deletion Operations: Return true, as there's nothing to delete (successful no-op)
• Trait Usage: Uses RetrievesMultipleKeys for many() and putMany() implementations

Sources: src/NullStore.php16-92

Lock Support

The NullStore implements LockProvider and creates NoLock instances. These locks always succeed immediately and provide no actual locking functionality:

Lock Methods:

NoLock Characteristics:

• Always Succeeds: All acquire operations immediately return true
• No Blocking: Never blocks or waits
• No Protection: Provides no actual mutual exclusion
• Testing Friendly: Useful for testing code that uses locks without actual locking behavior

Sources: src/NullStore.php54-67

Use Cases

Use Case	Suitability	Rationale
Disabling cache in development	✓ Excellent	Safe, predictable behavior
Testing without cache side effects	✓ Excellent	Isolates tests from caching
Feature flags (disable caching)	✓ Excellent	Clean way to toggle caching
Debugging cache-related issues	✓ Good	Eliminates cache as variable
Production use	⚠ Conditional	Only when caching is intentionally disabled

Recommended Scenarios:

1. Development Environment: Temporarily disable caching to see uncached behavior
2. Testing: Test application logic without cache interference or mocking
3. Cache Bypass: Provide a cache instance where caching is not desired
4. Debugging: Isolate issues by eliminating caching as a factor
5. Feature Flags: Runtime toggle of caching functionality

Sources: src/NullStore.php1-92

---

Store Comparison

Feature Matrix

Feature	ArrayStore	NullStore
Storage Backend	PHP array (memory)	None
Persistence	Process lifetime	None
Serialization	Optional	N/A
Data Retention	Until process ends	None
Get Operations	Returns stored value or null	Always null
Put Operations	Stores in memory	No-op (returns false)
Delete Operations	Removes from memory	No-op (returns true)
Lock Provider	ArrayLock (local)	NoLock (no-op)
Tag Support	Via TaggableStore	Via TaggableStore (no-op)
Performance	Very fast (in-memory)	Instant (no-op)
Use Case	Request-scoped caching	Disable caching
Testing	Isolated per-test data	No cache side effects

Sources: src/CacheManager.php204-228 src/NullStore.php1-92

Operation Flow Comparison

Sources: src/NullStore.php16-27

---

Choosing Between Stores

Decision Matrix

Sources: src/CacheManager.php204-228

Selection Guidelines

Choose ArrayStore when:

• Caching data within a single request or process
• Testing code that requires a functioning cache
• Prototyping before implementing persistent storage
• No external dependencies are available
• Performance testing cache-dependent code

Choose NullStore when:

• Temporarily disabling caching for debugging
• Testing application behavior without cache side effects
• Implementing feature flags to toggle caching
• Cache is conditionally required based on configuration
• Providing a safe default when cache configuration is missing

Choose Other Stores when:

• Data must persist across requests: See File Store or Database Store
• Need distributed caching: See Redis Store
• Need high-performance shared memory: See Swoole Store
• Need multi-tier caching: See Stack Store

Sources: src/CacheManager.php204-335

---

Integration with CacheManager

Driver Registration

Both stores are built-in drivers registered in the CacheManager class:

Driver Creation Methods:

Method	Location	Purpose
createArrayDriver(array $config)	src/CacheManager.php204-207	Creates ArrayStore with serialization option
createNullDriver()	src/CacheManager.php225-228	Creates NullStore with empty config

Sources: src/CacheManager.php204-228 src/CacheManager.php329-334

Configuration Resolution

The CacheManager handles the 'null' driver specially:

This allows the null store to be requested without explicit configuration in cache.php.

Sources: src/CacheManager.php327-334

---

Testing Considerations

ArrayStore in Tests

ArrayStore is ideal for unit testing as it provides:

• Isolation: Each test can have its own store instance
• Speed: No I/O operations or external dependencies
• Predictability: Deterministic behavior within process scope

Example test scenario:

NullStore in Tests

NullStore is useful for testing code that depends on cache but where caching behavior is not the focus:

• Eliminates Side Effects: No cached data between test runs
• Tests Cache Misses: Always simulates cache miss scenario
• Simplifies Mocking: No need to mock complex cache behavior

Sources: src/CacheManager.php204-228 src/NullStore.php1-92