Signatur
Beschreibung
memcache_add() speichert einen Wert unter dem angegebenen Schlüssel im Memcache-Server, jedoch nur dann, wenn unter diesem Schlüssel noch kein Eintrag vorhanden ist. Existiert der Schlüssel bereits, gibt die Funktion false zurück, ohne den bestehenden Wert zu überschreiben. Diese Eigenschaft macht sie ideal für atomare Operationen wie das Erstlegen von Locks oder das einmalige Initialisieren von Werten.
Die Funktion ist die prozedurale Variante der objektorientierten Methode Memcache::add(). Beide Varianten verhalten sich identisch. Der Parameter $flag ermöglicht die Aktivierung von Kompression über die Konstante MEMCACHE_COMPRESSED, was bei großen Datenmengen den Speicherverbrauch reduziert.
Mit dem Parameter $expire kann eine Ablaufzeit (TTL) in Sekunden angegeben werden. Werte bis 2.592.000 (30 Tage) werden als relative Sekunden interpretiert, größere Werte als absoluter Unix-Timestamp. Ein Wert von 0 bedeutet, dass der Eintrag nicht automatisch abläuft.
Die Funktion eignet sich besonders für Caching-Strategien, bei denen verhindert werden soll, dass ein bereits gesetzter Cache-Eintrag versehentlich überschrieben wird — zum Beispiel beim konkurrierenden Zugriff mehrerer Prozesse.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $memcache Pflicht | Memcache | Eine gültige Memcache-Verbindungsressource, die zuvor mit memcache_connect() oder memcache_pconnect() erstellt wurde. |
|
| $key Pflicht | string | Der eindeutige Schlüssel, unter dem der Wert gespeichert werden soll. Schlüssel sollten kurz und ohne Leerzeichen sein (max. 250 Zeichen). | |
| $value Pflicht | mixed | Der zu speichernde Wert. Skalare Typen sowie serialisierbare PHP-Objekte und Arrays werden unterstützt. Ressourcen können nicht gespeichert werden. | |
| $flag | int | 0 | Bitwert für zusätzliche Optionen. MEMCACHE_COMPRESSED aktiviert zlib-Kompression des gespeicherten Wertes. |
| $expire | int | 0 | Ablaufzeit in Sekunden (bis 2.592.000) oder als absoluter Unix-Timestamp. 0 bedeutet kein automatisches Ablaufen des Eintrags. |
Rückgabewert
true zurück, wenn der Eintrag erfolgreich gespeichert wurde. Gibt false zurück, wenn der Schlüssel bereits existiert oder ein Fehler aufgetreten ist.Beispiele
Einfaches Hinzufügen eines Cache-Eintrags
<?php
$memcache = memcache_connect('localhost', 11211);
$key = 'user_profile_42';
$value = ['name' => 'Max Mustermann', 'email' => 'max@example.com'];
// Eintrag nur hinzufügen, wenn noch nicht vorhanden
$result = memcache_add($memcache, $key, $value, 0, 3600);
if ($result) {
echo "Eintrag erfolgreich gespeichert.";
} else {
echo "Eintrag existiert bereits oder ein Fehler ist aufgetreten.";
}
memcache_close($memcache);
Einfaches Mutex-Lock mit memcache_add
<?php
$memcache = memcache_connect('localhost', 11211);
$lockKey = 'job_lock_newsletter';
$ttl = 60; // Lock gilt maximal 60 Sekunden
// Atomares Setzen: Nur einer bekommt den Lock
if (memcache_add($memcache, $lockKey, 1, 0, $ttl)) {
echo "Lock erworben, starte Job...";
// ... zeitaufwändige Verarbeitung ...
// Lock nach Abschluss freigeben
memcache_delete($memcache, $lockKey);
echo "Job abgeschlossen, Lock freigegeben.";
} else {
echo "Ein anderer Prozess verarbeitet diesen Job gerade bereits.";
}
memcache_close($memcache);
Komprimierter Eintrag mit MEMCACHE_COMPRESSED
<?php
$memcache = memcache_connect('localhost', 11211);
$bigData = str_repeat('Beispieldaten ', 10000);
// Wert mit zlib-Kompression speichern, nur wenn nicht vorhanden
$added = memcache_add($memcache, 'big_data_key', $bigData, MEMCACHE_COMPRESSED, 1800);
echo $added ? "Komprimierter Eintrag gespeichert." : "Eintrag bereits vorhanden.";
memcache_close($memcache);
// Wichtig · Fallstricke
Achtung: Die prozedurale Erweiterung memcache (PECL) ist nicht identisch mit der neueren memcached-Erweiterung. Für neue Projekte wird die Verwendung von Memcached::add() aus der memcached-Erweiterung empfohlen, da diese aktiver gepflegt wird und mehr Funktionen bietet.
Atomarität: memcache_add() ist auf Server-Ebene atomar — der Check ob der Schlüssel existiert und das Speichern geschehen in einer einzigen Operation. Dies macht es zuverlässiger als eine manuelle Prüfung mit memcache_get() gefolgt von memcache_set().
Race Conditions: Auch wenn memcache_add() für einfache Locks geeignet ist, sollten für kritische verteilte Sperrmechanismen spezialisierte Lösungen wie RedLock in Betracht gezogen werden.