Start · Sprachen · PHP · Referenz · memcache_add

memcache_add

Funktion

Fügt einen neuen Eintrag zum Memcache-Server hinzu — schlägt fehl, wenn der Schlüssel bereits existiert.

seit PHP 2.0.0 Kategorie: db

Signatur

memcache_add(Memcache $memcache, string $key, mixed $value, int $flag = 0, int $expire = 0): bool

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

Typ
bool
Beschreibung
Gibt 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);
Eintrag erfolgreich gespeichert.

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);
Lock erworben, starte Job... Job abgeschlossen, Lock freigegeben.

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);
Komprimierter Eintrag gespeichert.

// 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.