apcu_fetch — Funktion · PHP-Referenz

Signatur

apcu_fetch(mixed $key, bool &$success = null): mixed

Beschreibung

apcu_fetch() liest eine zwischengespeicherte Variable aus dem APCu-Benutzer-Cache (User Cache) und gibt deren Wert zurück. APCu (Alternative PHP Cache – User) ist ein In-Memory-Cache, der innerhalb eines PHP-Prozesses (bzw. Apache-Workers) zwischen Anfragen persistiert. Er eignet sich hervorragend, um teure Datenbankabfragen, berechnete Werte oder API-Ergebnisse kurzfristig zu cachen.

Wird ein Array von Schlüsseln als $key übergeben, liefert die Funktion ein assoziatives Array mit allen Schlüssel-Wert-Paaren, die im Cache gefunden wurden. Nicht vorhandene Schlüssel werden dabei einfach weggelassen.

Der optionale Parameter $success wird per Referenz übergeben und nach dem Aufruf auf true gesetzt, wenn der Schlüssel im Cache gefunden wurde, andernfalls auf false. So kann man zuverlässig zwischen einem nicht vorhandenen Eintrag und einem gecachten false unterscheiden – eine Situation, die beim reinen Überprüfen des Rückgabewerts sonst zu Fehlinterpretationen führen kann.

Ist der angeforderte Schlüssel nicht im Cache vorhanden (z. B. weil er abgelaufen ist oder nie gesetzt wurde), gibt apcu_fetch() false zurück. APCu ist nur für CLI- und Server-API-Umgebungen mit apc.enable_cli=1 bzw. Web-Umgebungen verfügbar; in anderen Kontexten schlägt der Aufruf stillschweigend fehl.

Parameter

Name	Typ	Default	Beschreibung
$key Pflicht	string\|array		Der Schlüssel (String) oder ein Array von Schlüsseln, unter denen die Variablen im Cache gespeichert wurden. Bei einem Array werden alle gefundenen Schlüssel als assoziatives Array zurückgegeben.
$success	bool	null	Wird per Referenz übergeben. Nach dem Aufruf ist der Wert `true`, wenn der Schlüssel gefunden wurde, sonst `false`. Damit lässt sich ein gecachtes `false` von einem Cache-Miss unterscheiden.

Rückgabewert

Typ

mixed

Beschreibung

Gibt den gespeicherten Wert zurück, wenn der Schlüssel im Cache vorhanden ist. Bei einem Array als $key wird ein assoziatives Array mit den gefundenen Einträgen zurückgegeben. Ist der Schlüssel nicht vorhanden, wird false zurückgegeben.

Beispiele

Einfaches Lesen und Schreiben eines Cache-Eintrags

<?php
// Wert im Cache speichern (TTL: 60 Sekunden)
apcu_store('begruessung', 'Hallo, Welt!', 60);

// Wert aus dem Cache lesen
$wert = apcu_fetch('begruessung', $erfolg);

if ($erfolg) {
    echo 'Aus dem Cache: ' . $wert;
} else {
    echo 'Schlüssel nicht im Cache gefunden.';
}

Aus dem Cache: Hallo, Welt!

Cache-Aside-Pattern: teure Berechnung cachen

<?php
function getTeureBerechnung(): int
{
    $cacheKey = 'teure_berechnung_v1';
    $ergebnis = apcu_fetch($cacheKey, $treffer);

    if (!$treffer) {
        // Simuliert eine aufwändige Operation
        $ergebnis = array_sum(range(1, 1_000_000));
        apcu_store($cacheKey, $ergebnis, 300); // 5 Minuten cachen
    }

    return $ergebnis;
}

echo getTeureBerechnung(); // Erstes Mal: berechnet und gecacht
echo getTeureBerechnung(); // Zweites Mal: direkt aus dem Cache

500000500000 500000500000

Mehrere Schlüssel gleichzeitig abrufen

<?php
apcu_store('user_1', ['name' => 'Alice', 'alter' => 30]);
apcu_store('user_2', ['name' => 'Bob',   'alter' => 25]);

$users = apcu_fetch(['user_1', 'user_2', 'user_3']);

foreach ($users as $key => $user) {
    echo $key . ': ' . $user['name'] . PHP_EOL;
}
// 'user_3' fehlt, da nicht gecacht

user_1: Alice user_2: Bob

// Wichtig · Fallstricke

Unterschied zu einem Cache-Miss vs. gespeichertem false: Da apcu_fetch() bei einem nicht gefundenen Schlüssel false zurückgibt, muss der $success-Parameter verwendet werden, wenn man explizit den booleschen Wert false cacht – andernfalls ist nicht unterscheidbar, ob der Schlüssel fehlt oder ob false der gespeicherte Wert ist.

Verfügbarkeit: APCu ist nur in PHP-Webserver-Umgebungen standardmäßig aktiv. In der CLI muss apc.enable_cli = 1 in der php.ini gesetzt sein, da der Cache sonst deaktiviert ist und alle Aufrufe fehlschlagen.

Keine Persistenz: Der APCu-Cache lebt im Arbeitsspeicher des jeweiligen PHP-Prozesses und wird beim Neustart des Webservers, bei einem Deploy oder bei Erreichen der Speicherlimitierung (gemäß apc.shm_size) geleert. Er ist nicht für persistente Datenspeicherung geeignet.

Thread-Safety: APCu nutzt Shared Memory und Lock-Mechanismen, um gleichzeitige Zugriffe abzusichern, jedoch können unter hoher Last Race Conditions beim Cache-Befüllen auftreten (sog. Cache Stampede). Hier sollten Mechanismen wie Mutex-Locking oder probabilistisches Early Expiry in Betracht gezogen werden.

Siehe auch

apcu_store apcu_delete apcu_exists apcu_add apcu_clear_cache apcu_cache_info