Download the PHP package noga-ng/ncache without Composer

NCache

A lightweight, multi-driver caching library for PHP 8.1+.

NCache provides a unified caching API for file-based storage, SQLite, Redis, and Memcached while keeping profiles, TTL, namespaces, signatures, tags, metadata, and cache invalidation consistent across drivers.

NCache also provides PSR-6 and PSR-16 adapters for applications and libraries that rely on standard PHP-FIG caching interfaces.

Features

• PHP 8.1+
• Unified multi-driver cache API
• PSR-6 CacheItemInterface and CacheItemPoolInterface
• PSR-16 CacheInterface
• JSON cache
• Serialized PHP cache
• String cache
• PHP array cache (ARRAY_PHP) with OPcache-friendly files
• SQLite cache
• Redis cache
• Memcached cache
• Configurable default driver
• Multiple isolated cache profiles
• Profile-aware cache key isolation
• Immutable resolved configuration state per cache instance
• Relative cache paths resolved from the configuration file
• Cache namespaces and scoped directories
• Persistent cache, default TTL, and explicit TTL
• Human-readable TTL expressions
• Shared Redis/Memcached configuration with driversFrom
• Redis database selection
• Cache signatures
• Callable values and signatures
• Cache tags and global tag invalidation
• Lazy deletion of tag-invalidated entries
• Cache registry with metadata
• Transactional registry updates using file locking
• Atomic file replacement for file-based cache writes
• Lazy recursive cache-directory iteration
• Per-driver and scoped cache clearing

Requirements

• PHP >= 8.1
• Composer

Depending on the selected driver:

• ext-redis for Redis
• ext-memcached for Memcached
• ext-pdo_sqlite for SQLite

Installation

Quick Start

Create a configuration file:

Load the configuration and select a profile:

Store a value:

Retrieve it:

Check whether it exists:

Delete it:

Callable Values

NCache supports callables for dynamically resolved cache values.

Instead of resolving a value before passing it to NCache:

a callable can be passed directly:

Callables are also supported by append():

Signatures can also be dynamically resolved:

and validated against the current resource state:

Callable support is part of the native NCache API and is also available when values pass through the PSR adapters.

PSR Compatibility

NCache provides compatibility adapters for the standard PHP-FIG caching interfaces without coupling the native API to PSR-specific behavior.

PSR-16 — Simple Cache

NCache implements Psr\SimpleCache\CacheInterface through the SimpleCache adapter.

PSR-16 provides a portable key/value caching API with TTL, multiple operations, deletion, and cache clearing.

Read the PSR-16 documentation

PSR-6 — Caching Interface

NCache implements:

• Psr\Cache\CacheItemInterface
• Psr\Cache\CacheItemPoolInterface

Create a cache pool:

Retrieve and store an item:

PSR-6 also supports deferred persistence:

Read the PSR-6 documentation

Which API Should I Use?

The PSR adapters are compatibility layers. They do not replace or restrict the native NCache API.

Configuration

NCache uses a JSON configuration file containing one or more cache profiles.

Select a profile:

Profile Isolation

When NCache::key() creates a cache instance, NCache captures the resolved state of the currently selected profile.

Changing the active profile later does not mutate cache instances that were already created.

The resulting instances remain independent:

A later call to use() does not switch the configuration of either existing cache instance.

Cache identity also includes the active profile, preventing identical cache keys from colliding when multiple profiles share the same cache directory.

Relative Cache Paths

Relative cachePath values are resolved from the directory containing the configuration file, not from the application's current working directory.

Example:

With:

NCache resolves the path relative to config/ncache.config.json.

Cache Drivers

A profile can define its default driver:

The driver can then be omitted:

A driver can also be selected explicitly:

An explicitly provided driver takes precedence over defaultDriver.

PHP Array Cache

CType::ARRAY_PHP stores cache data as a PHP file returning an array.

The generated cache is equivalent to:

Because the generated cache is loaded as PHP, this driver can benefit from PHP OPcache instead of requiring JSON decoding or unserialization for each read.

Configure the extension with:

TTL

NCache distinguishes between persistent cache, configured default TTL, and explicit TTL.

Persistent Cache

If ttl() is not called:

the cache has no expiration.

Default TTL

Calling ttl() without a value uses the active profile's defaultTtl:

Explicit TTL

Passing a TTL explicitly overrides the configured default:

Human-readable TTL

Configuration files support duration expressions:

Examples:

A numeric TTL can also be used:

Use null when no default TTL should be defined.

Namespaces and Scopes

Each profile can define a namespace:

A cache operation can also use an additional directory or scope:

For file-based drivers, the scope is resolved below the configured cachePath.

This allows identical keys to remain isolated between different profiles or cache scopes.

Shared Driver Configuration

driversFrom allows a profile to reuse Redis and Memcached connection settings from another profile.

The inherited driver configuration is resolved into the selected profile state.

Redis

Redis configuration is defined in drivers.redis:

The database option selects the Redis database used by the connection.

Memcached

Memcached configuration is defined in drivers.memcached:

Cache Tags

Tags allow multiple cache entries to be grouped logically and invalidated together without depending on a specific cache driver.

Attach one tag:

Attach multiple tags:

The registry stores tag metadata with the cache entry:

Tag Invalidation

Invalidate every cache entry associated with a tag:

Tag invalidation is intentionally lazy.

invalidateTag() does not immediately delete the underlying cached value. Matching registry entries are marked as invalid:

The next get() or has() detects the invalid tag state, deletes the cached value through its own driver, and removes the corresponding registry entry.

This keeps tag invalidation independent from the storage backend and gives file caches, SQLite, Redis, and Memcached the same invalidation lifecycle.

Tags are intentionally separate from TTL and signatures:

• TTL controls time-based expiration.
• Tags provide explicit group invalidation.
• Signatures validate cached data against the state of another resource.

Cache Signatures

A signature associates cached data with the state or version of another resource.

Validate it later:

Signatures also support callables:

The current state can then be resolved dynamically during validation:

For file-based cache entries, registry metadata such as stored file size can also be used as an additional consistency check.

Append Data

Append data to an existing cache value:

append() also accepts a callable:

TTL Information

Retrieve the remaining TTL:

Inspect the TTL state:

Registry

NCache maintains cache metadata independently from the cached value.

Registry metadata includes:

• cache type
• original cache name
• internal hashed key
• namespace
• associated file
• file size when applicable
• signature
• tags
• TTL
• expiration timestamp

Registry mutations use an exclusive lock around the complete read-modify-write cycle, reducing lost updates when multiple processes modify the same registry concurrently.

Atomic File Writes

File-based drivers write cache data through a temporary file and replace the final target only after the write is complete.

This avoids exposing partially written cache files during normal writes.

The registry uses a separate stable lock file so the registry file itself can still be replaced atomically.

Lazy Directory Iteration

Recursive cache-directory traversal is performed lazily using PHP iterators and generators.

Entries are yielded progressively instead of first collecting the entire directory tree into an in-memory array.

This keeps directory operations more memory-efficient when working with a large number of cache files.

Clearing Cache

Clear caches for the default driver:

Clear a specific driver:

Clear a specific scope:

Supported Drivers

PSR

• Added PSR-16 Simple Cache support
• Added PSR-6 Cache Item Pool support
• Added PSR-6 expiration management
• Added PSR-6 deferred persistence with saveDeferred() and commit()
• Added dedicated PSR-6 and PSR-16 documentation

Cache API

• Added callable support for cache values
• Added callable support to append()
• Added callable-based signatures and signature validation
• Added cache tags
• Added global lazy tag invalidation
• Improved profile-aware cache key isolation

Storage

• Added the ARRAY_PHP cache driver
• Added OPcache-friendly PHP array cache files
• Improved lazy recursive directory iteration

Quality

• PHPStan level 9
• PHPUnit coverage for native, PSR-6, and PSR-16 APIs
• PHP-CS-Fixer validation
• GitHub Actions CI across PHP 8.1–8.5

NCache is developed and tested with:

• PHPUnit
• PHPStan level 9
• PHP-CS-Fixer
• GitHub Actions

Continuous integration validates NCache on:

• PHP 8.1
• PHP 8.2
• PHP 8.3
• PHP 8.4
• PHP 8.5

The CI suite also validates Redis and Memcached integration.

License

NCache is released under the MIT License.