APCUIterator — Klasse · PHP-Referenz

Signatur

class APCUIterator implements Iterator

Beschreibung

APCUIterator ist ein Iterator-Objekt, das speziell für den Zugriff auf den APCu-Benutzer-Cache entwickelt wurde. Im Gegensatz zu apcu_cache_info(), das alle Cache-Einträge auf einmal lädt, liest der APCUIterator die Einträge in konfigurierbaren Blöcken (Chunks) – das reduziert den Speicherverbrauch erheblich und ist daher für große Caches mit Tausenden von Einträgen deutlich besser geeignet.

Über den optionalen regulären Ausdruck im Konstruktor lassen sich Einträge nach Schlüsselnamen filtern. So können z. B. alle Einträge eines bestimmten Namespace (/^user_/) effizient abgerufen oder gelöscht werden. Die Klasse implementiert das Standard-PHP-Interface Iterator, sodass sie direkt in einer foreach-Schleife verwendet werden kann.

Mit dem Parameter $format lässt sich steuern, welche Metadaten (TTL, Größe, Trefferanzahl usw.) zusammen mit den Schlüsseln und Werten zurückgegeben werden. Das Kombinieren mehrerer APC_ITER_*-Konstanten über bitweise ODER-Verknüpfung ermöglicht eine gezielte Auswahl der benötigten Informationen.

Typische Einsatzfälle sind das massenhafte Löschen von Cache-Einträgen eines Namespace, das Inventarisieren des Cache-Inhalts zu Debugging-Zwecken sowie das Sammeln von Nutzungsstatistiken.

Parameter

Name	Typ	Default	Beschreibung
$search	string\|array\|null	null	Ein PCRE-regulärer Ausdruck als `string`, ein `array` von Schlüsseln oder `null`, um alle Einträge zu liefern. Wird ein regulärer Ausdruck übergeben, werden nur Einträge zurückgegeben, deren Schlüssel dem Ausdruck entsprechen.
$format	int	APC_ITER_ALL	Bitmaske aus `APC_ITER_*`-Konstanten, die festlegt, welche Felder pro Eintrag zurückgegeben werden (z. B. `APC_ITER_KEY`, `APC_ITER_VALUE`, `APC_ITER_TTL`, `APC_ITER_MEM_SIZE` usw.).
$chunk_size	int	100	Anzahl der Einträge, die intern pro Lese-Schritt aus dem Cache geholt werden. Größere Werte reduzieren die Anzahl der Sperr-Operationen, erhöhen aber den Speicherbedarf pro Iteration.
$list	int	APC_LIST_ACTIVE	Gibt an, welche Eintrags-Liste durchlaufen werden soll: `APC_LIST_ACTIVE` für aktive oder `APC_LIST_DELETED` für bereits zum Löschen vorgemerkte Einträge.

Rückgabewert

Typ

Beispiele

Alle Cache-Einträge mit foreach durchlaufen

<?php
// Einige Testdaten in den APCu-Cache schreiben
apcu_store('user_42', ['name' => 'Alice', 'age' => 30], 300);
apcu_store('user_99', ['name' => 'Bob',   'age' => 25], 300);
apcu_store('config_debug', true, 0);

// Alle Einträge durchlaufen (Schlüssel + Wert)
$iterator = new APCUIterator(null, APC_ITER_KEY | APC_ITER_VALUE);

foreach ($iterator as $entry) {
    echo 'Schlüssel: ' . $entry['key'] . "\n";
    // Wert-Ausgabe abhängig vom Typ
    echo 'Wert: ' . (is_array($entry['value']) ? json_encode($entry['value']) : var_export($entry['value'], true)) . "\n\n";
}

Schlüssel: user_42 Wert: {"name":"Alice","age":30} Schlüssel: user_99 Wert: {"name":"Bob","age":25} Schlüssel: config_debug Wert: true

Namespace-Einträge per Regex filtern und massenweise löschen

<?php
// Mehrere Nutzer-Einträge cachen
for ($i = 1; $i <= 5; $i++) {
    apcu_store('user_' . $i, 'Daten von Nutzer ' . $i, 600);
}
apcu_store('system_status', 'ok', 0);

// Nur Einträge mit Präfix "user_" ermitteln und löschen
$iterator = new APCUIterator('/^user_/', APC_ITER_KEY);

$geloescht = 0;
foreach ($iterator as $entry) {
    apcu_delete($entry['key']);
    $geloescht++;
}

echo "Gelöschte Einträge: $geloescht\n";
echo 'system_status noch vorhanden: ' . (apcu_exists('system_status') ? 'ja' : 'nein') . "\n";

Gelöschte Einträge: 5 system_status noch vorhanden: ja

Speicherbedarf und TTL von Cache-Einträgen analysieren

<?php
apcu_store('session_abc', str_repeat('x', 1024), 60);
apcu_store('session_def', str_repeat('y', 2048), 120);

$iterator = new APCUIterator(
    '/^session_/',
    APC_ITER_KEY | APC_ITER_MEM_SIZE | APC_ITER_TTL,
    50
);

foreach ($iterator as $entry) {
    printf(
        "Schlüssel: %-20s | Größe: %6d Byte | TTL: %d s\n",
        $entry['key'],
        $entry['mem_size'],
        $entry['ttl']
    );
}

Schlüssel: session_abc | Größe: 1104 Byte | TTL: 60 s Schlüssel: session_def | Größe: 2128 Byte | TTL: 120 s

// Wichtig · Fallstricke

APCu muss installiert und aktiv sein: Die Klasse ist nur verfügbar, wenn die PECL-Erweiterung apcu geladen ist (extension=apcu in der php.ini). In CLI-Skripten muss zusätzlich apc.enable_cli=1 gesetzt sein.

Sperr-Verhalten: Während jedes Chunk-Lesevorgangs wird der APCu-Cache intern kurz gesperrt. Ein sehr kleiner chunk_size-Wert erhöht die Anzahl der Sperren und kann bei hoch-parallelen Anwendungen zu kurzen Verzögerungen führen. Standardwert 100 ist für die meisten Szenarien ein guter Kompromiss.

Konsistenz: Da der Iterator blockweise liest, kann sich der Cache zwischen zwei Chunks verändern (Einträge können ablaufen oder neu gesetzt werden). Der Iterator bietet daher kein Snapshot-Verhalten; für konsistente Punkt-in-Zeit-Analysen sollte apcu_cache_info() bevorzugt werden.

PHP CLI: Jeder CLI-Prozess hat seinen eigenen APCu-Shared-Memory-Bereich. Das Iterieren im CLI-Kontext liefert daher andere Daten als derselbe Code im Webserver-Kontext.

Siehe auch

apcu_store apcu_fetch apcu_delete apcu_cache_info apcu_exists apcu_clear_cache