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()

public static function 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.
• Throws CacheException 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

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

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

public function 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.

public function delete(string $key): bool;

Remove one item. Deleting a missing key still succeeds.

public function 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.

public function has(string $key): bool;

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

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

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

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

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

public function deleteMultiple(iterable $keys): bool;

Delete many keys. true only if all succeed.

InitPHP extensions

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

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

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

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

public function isSupported(): bool;

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

increment() / decrement()

public function increment(string $key, int $offset = 1): int;
public function 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

public const RESERVED_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

protected function name(string $key): string;

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

protected function validateKey(string $key): string;

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

protected function 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").

protected function optionInt(string $key, int $default = 0): int;
protected function optionFloat(string $key, float $default = 0.0): float;
protected function 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.