API Reference

This page details the functions and classes provided by the APCu extension.

Functions

apcu_enabled()

Checks if APCu is enabled.

bool apcu_enabled(void)
  • Description: Returns true if APCu is enabled and available in the current environment (e.g., not disabled by apc.enable_cli=0), false otherwise.
  • Return Value: A boolean indicating whether APCu is active.

apcu_store()

Caches a variable in the data store.

array|bool apcu_store(array|string $key, mixed $value = UNKNOWN, int $ttl = 0)
  • Description: Stores the $value in the cache under the specified $key. If the key already exists, its value will be overwritten.
  • Parameters:
    • $key: A string key or an array of key-value pairs to store.
    • $value: The variable to store. Ignored if $key is an array.
    • $ttl: Time To Live; the number of seconds the value should be cached. 0 means it persists forever (or until the cache is cleared).
  • Return Value: Returns true on success, false on failure. If $key is an array, it returns an array of the keys that failed to be stored.

apcu_add()

Caches a variable in the data store, but only if it does not already exist.

array|bool apcu_add(array|string $key, mixed $value = UNKNOWN, int $ttl = 0)
  • Description: This is an atomic operation. If the key already exists in the cache, the value will not be overwritten, and the function will return false.
  • Parameters: Same as apcu_store().
  • Return Value: Returns true on success, false on failure (e.g., key already exists). If $key is an array, it returns an array of the keys that failed.

apcu_fetch()

Fetches a stored variable from the cache.

mixed apcu_fetch(array|string $key, bool &$success = null)
  • Description: Retrieves a single value or an array of values from the cache.
  • Parameters:
    • $key: The string key or an array of keys to fetch.
    • $success: A reference to a boolean variable that will be set to true on success and false on failure (e.g., cache miss).
  • Return Value: The stored variable, or false on failure. Using the $success flag is the recommended way to distinguish a false return value from a cache miss.

apcu_exists()

Checks if a key exists in the cache.

array|bool apcu_exists(array|string $key)
  • Description: Checks for the existence of one or more keys.
  • Parameters:
    • $key: A string key or an array of keys to check.
  • Return Value: Returns true if the key exists, false otherwise. If $key is an array, it returns an array containing the keys that were found.

apcu_delete()

Removes a stored variable from the cache.

array|bool apcu_delete(APCUIterator|array|string $key)
  • Description: Deletes one or more entries from the cache.
  • Parameters:
    • $key: The string key, an array of keys, or an APCUIterator instance to delete.
  • Return Value: Returns true on success, false on failure. If $key is an array, it returns an array of the keys that failed to be deleted.

apcu_inc()

Increments a stored integer value.

int|false apcu_inc(string $key, int $step = 1, bool &$success = null, int $ttl = 0)
  • Description: Atomically increments the integer value associated with $key by $step. If the key does not exist, it will be created with an initial value of 0 before being incremented.
  • Parameters:
    • $key: The key of the value to increment.
    • $step: The amount to increment by.
    • $success: A reference set to true on success, false on failure.
    • $ttl: The TTL to use if the key is being created.
  • Return Value: The new integer value on success, or false on failure.

apcu_dec()

Decrements a stored integer value.

int|false apcu_dec(string $key, int $step = 1, bool &$success = null, int $ttl = 0)
  • Description: Atomically decrements the integer value associated with $key.
  • Parameters: Same as apcu_inc().
  • Return Value: The new integer value on success, or false on failure.

apcu_cas()

Compare-and-swap: updates a value if it matches a given old value.

bool apcu_cas(string $key, int $old, int $new)
  • Description: Atomically updates the value of $key to $new only if its current value is equal to $old.
  • Parameters:
    • $key: The key of the value to update.
    • $old: The expected old value.
    • $new: The new value to set.
  • Return Value: true if the swap occurred, false otherwise.

apcu_entry()

Atomically fetches a value or generates and stores it if it doesn't exist.

mixed apcu_entry(string $key, callable $callback, int $ttl = 0)
  • Description: A convenient way to implement a "cache-aside" pattern. It attempts to fetch $key. If it's a miss, it calls the $callback function, stores its return value in the cache with the given $ttl, and then returns it.
  • Parameters:
    • $key: The cache key.
    • $callback: A function that generates the value if it's not in the cache. It receives the $key as its first argument.
    • $ttl: The TTL for the new entry.
  • Return Value: The cached or newly generated value.

apcu_clear_cache()

Clears the entire user cache.

bool apcu_clear_cache(void)
  • Return Value: Returns true.

apcu_cache_info()

Retrieves detailed information about the cache.

array|false apcu_cache_info(bool $limited = false)
  • Description: Provides metadata about the cache's state, such as memory usage, hit/miss counts, and a list of all cached entries.
  • Parameters:
    • $limited: If true, the list of individual entries is excluded, which is faster and uses less memory.
  • Return Value: An array of cache data, or false on failure.

apcu_key_info()

Retrieves information about a specific cache entry.

array|null apcu_key_info(string $key)
  • Return Value: An array with metadata for a single key, or null if the key doesn't exist.

apcu_sma_info()

Retrieves information about the shared memory allocator.

array|false apcu_sma_info(bool $limited = false)
  • Description: Provides low-level details about the shared memory segment, including its total size, available memory, and a list of free blocks (fragmentation details).
  • Return Value: An array of SMA data, or false on failure.

APCUIterator Class

The APCUIterator class provides an efficient way to iterate over the items stored in the user cache. It implements PHP's Iterator interface.

__construct()

Creates a new iterator.

public function __construct(array|string|null $search = null, int $format = APC_ITER_ALL, int $chunk_size = 100, int $list = APC_LIST_ACTIVE)
  • Parameters:
    • $search: A PCRE regular expression to filter keys, or an array of keys to match.
    • $format: A bitmask of APC_ITER_* constants specifying which information to include for each entry.
    • $chunk_size: The number of entries to fetch from shared memory at a time.
    • $list: APC_LIST_ACTIVE (default) or APC_LIST_DELETED.

Format Constants (APC_ITER_*)

Constant Description
APC_ITER_KEY Key name
APC_ITER_VALUE The stored value
APC_ITER_NUM_HITS Number of hits
APC_ITER_MTIME Last modification time
APC_ITER_CTIME Creation time
APC_ITER_ATIME Last access time
APC_ITER_TTL Time-To-Live
APC_ITER_MEM_SIZE Size in bytes
APC_ITER_ALL Includes all of the above

Methods

  • public function rewind(): void: Resets the iterator to the beginning.
  • public function next(): void: Moves to the next item.
  • public function valid(): bool: Checks if the current position is valid.
  • public function key(): string|int: Returns the key of the current item.
  • public function current(): mixed: Returns the current item (an array formatted according to the constructor's $format parameter).
  • public function getTotalHits(): int: Gets the total number of hits for all matched entries.
  • public function getTotalSize(): int: Gets the total memory size for all matched entries.
  • public function getTotalCount(): int: Gets the total number of matched entries.

Example

<?php

apcu_store('user:1', ['name' => 'Alice']);
apcu_store('user:2', ['name' => 'Bob']);
apcu_store('config:1', 'some_setting');

$iterator = new APCUIterator('/^user:/', APC_ITER_KEY | APC_ITER_VALUE);

foreach ($iterator as $key => $entry) {
    printf("Key: %s, Name: %s\n", $key, $entry['value']['name']);
}

// Output:
// Key: user:1, Name: Alice
// Key: user:2, Name: Bob

?>