Signatur
Beschreibung
apcu_add() legt einen Wert unter dem angegebenen Schlüssel im APCu-Benutzercache ab. Im Gegensatz zu apcu_store() überschreibt diese Funktion einen bereits vorhandenen Eintrag nicht, sondern gibt in diesem Fall false zurück. Sie eignet sich daher ideal für atomare "Nur-wenn-nicht-vorhanden"-Operationen, etwa um Race-Conditions beim Setzen eines Initialisierungswertes zu verhindern.
Wird ein Array als erster Parameter übergeben ($key = assoziatives Array), interpretiert APCu jeden Array-Eintrag als Key-Value-Paar und versucht alle Paare zu speichern. Als Rückgabewert erhält man dann ein Array der Schlüssel, die nicht gespeichert werden konnten (also bereits vorhanden waren).
Der optionale Parameter $ttl (Time-To-Live) gibt in Sekunden an, wie lange der Eintrag im Cache verbleiben soll. Bei 0 (Standard) bleibt der Eintrag so lange gespeichert, bis der Cache geleert wird oder der PHP-Prozess endet.
APCu (APC User Cache) ist ein Shared-Memory-Cache für PHP-Prozesse auf demselben Server. Es ist wichtig zu beachten, dass APCu-Daten nicht prozessübergreifend zwischen verschiedenen Servern geteilt werden – für verteilte Caches sind Lösungen wie Redis oder Memcached besser geeignet.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $key Pflicht | string|array | Eindeutiger Bezeichner für den Cache-Eintrag als string, oder ein assoziatives Array der Form ['schlüssel' => wert, ...] zum Speichern mehrerer Einträge auf einmal. |
|
| $var | mixed | null | Der zu speichernde Wert. Kann ein beliebiger PHP-Wert (Skalare, Arrays, Objekte) sein. Wird ignoriert, wenn $key ein Array ist. |
| $ttl | int | 0 | Time-To-Live in Sekunden. Nach Ablauf dieser Zeit wird der Eintrag automatisch aus dem Cache entfernt. 0 bedeutet, dass der Eintrag nicht automatisch abläuft. |
Rückgabewert
string): true bei Erfolg, false wenn der Schlüssel bereits existiert oder ein Fehler auftrat. Bei einem Array als $key: gibt ein Array der Schlüssel zurück, die nicht gespeichert werden konnten (leeres Array bei vollständigem Erfolg).Beispiele
Einfaches Hinzufügen eines Cache-Eintrags
<?php
// Ersten Aufruf: Wert wird gespeichert
$result1 = apcu_add('mein_schluessel', 'Hallo Welt', 60);
var_dump($result1); // bool(true)
// Zweiter Aufruf: Schlüssel existiert bereits → kein Überschreiben
$result2 = apcu_add('mein_schluessel', 'Anderer Wert', 60);
var_dump($result2); // bool(false)
// Den gespeicherten Wert abrufen
$wert = apcu_fetch('mein_schluessel');
var_dump($wert); // string(10) "Hallo Welt"Mehrere Einträge auf einmal hinzufügen
<?php
// Zuerst einen Schlüssel vorbelegen
apcu_store('vorhanden', 'bereits gesetzt');
// Mehrere Einträge per Array hinzufügen
$nicht_gespeichert = apcu_add([
'neu_a' => 'Wert A',
'neu_b' => 'Wert B',
'vorhanden' => 'Wird ignoriert', // existiert bereits
]);
// Zeigt die Schlüssel, die NICHT gespeichert werden konnten
print_r($nicht_gespeichert);
echo apcu_fetch('neu_a') . PHP_EOL; // Wert A
echo apcu_fetch('vorhanden') . PHP_EOL; // bereits gesetztAtomare Initialisierung (Race-Condition verhindern)
<?php
/**
* Beispiel: Nur ein Prozess soll eine teure Initialisierung durchführen.
* apcu_add() ist atomar – genau ein Prozess erhält true.
*/
if (apcu_add('init_lock', 1, 30)) {
// Dieser Block wird nur von EINEM Prozess ausgeführt
$daten = berechne_teure_ressource(); // hypothetische Funktion
apcu_store('init_daten', $daten, 300);
echo "Initialisierung durchgeführt." . PHP_EOL;
} else {
echo "Ein anderer Prozess initialisiert gerade." . PHP_EOL;
}// Wichtig · Fallstricke
Verfügbarkeit: APCu ist eine PHP-Extension, die separat installiert werden muss (pecl install apcu). Im CLI-Modus ist APCu standardmäßig deaktiviert; die INI-Option apc.enable_cli=1 aktiviert es für Tests.
Atomarität: apcu_add() ist atomar bezüglich des Prüfen-und-Setzen-Vorgangs auf einem einzelnen Server. Dies macht die Funktion ideal für einfache Lock-Mechanismen oder das Initialisieren geteilter Ressourcen unter konkurrierenden Prozessen.
Kein Ersatz für persistente Speicherung: APCu-Daten liegen ausschließlich im Arbeitsspeicher und gehen bei einem Serverneustart, bei PHP-FPM-Pool-Reloads oder bei Speichermangel verloren. Kritische Daten gehören in eine Datenbank oder einen persistenten Cache.
Unterschied zu apcu_store(): apcu_store() überschreibt vorhandene Einträge, apcu_add() hingegen nicht. Wähle apcu_add(), wenn du sicherstellen willst, dass kein bestehender Wert versehentlich überschrieben wird.