API Reference

API Reference

Every public member of initphp/cache. For narrative explanations, follow the links into the concept pages.

---

Cache (factory)

InitPHP\Cache\Cache — see The Cache Factory.

create()

publicstaticfunction create(
string|CacheInterface$handler,
array$options = []
): CacheInterface

Builds (or accepts) a handler, applies $options, and returns it.

• $handler — a handler class name to instantiate, or an already-built handler instance.
• $options — handler options, keys matched case-insensitively.
• ThrowsCacheException if the class does not exist, does not implement CacheInterface, or the runtime does not support it.

---

CacheInterface

InitPHP\Cache\CacheInterface extends Psr\SimpleCache\CacheInterface.

The eight PSR-16 methods plus five InitPHP extensions. Every handler implements this interface.

PSR-16 methods

publicfunction get(string$key, mixed$default = null): mixed;

Return the value for $key, or $default (returned as-is) on a miss. ThrowsInvalidArgumentException for an invalid key. See Keys, TTL & Values.

publicfunction set(string$key, mixed$value, null|int|DateInterval$ttl = null): bool;

Store $value. $ttl: null = forever, seconds, or a DateInterval; 0/ negative deletes the item. Returns true on success. See TTL.

publicfunction delete(string$key): bool;

Remove one item. Deleting a missing key still succeeds.

publicfunction clear(): bool;

Remove every item this handler owns. Scope differs per handler — File/PDO honour the prefix; Redis/Memcache/WinCache flush the whole store. See each handler page.

publicfunction has(string$key): bool;

Whether a live (non-expired) item exists. Use this to distinguish a stored null from a miss.

publicfunction getMultiple(iterable$keys, mixed$default = null): iterable;

Map of key => value, with $default for misses. See Bulk Operations.

publicfunction setMultiple(iterable$values, null|int|DateInterval$ttl = null): bool;

Store many key => value pairs with one TTL. true only if all succeed.

publicfunction deleteMultiple(iterable$keys): bool;

Delete many keys. true only if all succeed.

InitPHP extensions

publicfunction setOptions(array$options = []): static;

Merge options (case-insensitively) into the handler; returns $this.

publicfunction getOption(string$key, mixed$default = null): mixed;

Read one option (case-insensitive lookup), or $default when unset.

publicfunction isSupported(): bool;

Whether the current runtime can use this handler (e.g. the extension is loaded).

increment() / decrement()

publicfunction increment(string$key, int$offset = 1): int;
publicfunction decrement(string$key, int$offset = 1): int;

Adjust an integer counter and return the new value. A missing/non-numeric item counts as 0; the result is stored without an expiry. Identical on every handler, not atomic across processes. See Counters.

---

BaseHandler

InitPHP\Cache\BaseHandler implements CacheInterface — the abstract base every built-in handler extends. Relevant when writing your own handler.

Constant

publicconstRESERVED_CHARACTERS = '{}()/\@:';

The PSR-16 characters a key may not contain.

Methods a subclass must implement

get(), set(), delete(), clear(), has(), isSupported() — the storage-specific primitives. (increment(), decrement(), the *Multiple() methods, options handling and key/TTL helpers are provided.)

Protected helpers for subclasses

protectedfunction name(string$key): string;

Validate $key and return it prefixed with the prefix option — the physical storage key. Throws InvalidArgumentException for an invalid key.

protectedfunction validateKey(string$key): string;

Validate a key without prefixing it (returns it unchanged, or throws).

protectedfunction ttlToSeconds(null|int|DateInterval$ttl): ?int;

Normalise a PSR-16 TTL to seconds (null = no expiry). A DateInterval is resolved from now; the result may be zero/negative ("already expired").

protectedfunction optionInt(string$key, int$default = 0): int;
protectedfunction optionFloat(string$key, float$default = 0.0): float;
protectedfunction optionString(string$key, string$default = ''): string;

Read an option coerced to a scalar type, falling back to $default when the stored value is not coercible.

---

Exceptions

InitPHP\Cache\Exception\* — see Error Handling.

CacheException

class CacheException
extends \Exception
implements \Psr\SimpleCache\CacheException

Configuration and backend errors (missing extension, connection failure, missing File path, invalid PDO table, bad factory class).

InvalidArgumentException

class InvalidArgumentException
extends \InvalidArgumentException
implements \Psr\SimpleCache\InvalidArgumentException

An invalid cache key (empty, or containing a reserved character). Because the PSR interface extends Psr\SimpleCache\CacheException, this is also catchable as a CacheException.

Next steps

• Error Handling — the exception model in depth.
• Custom Handlers — using the BaseHandler helpers above.