wincache_ucache_add — Funktion · PHP-Referenz

Signatur

wincache_ucache_add(string $key, mixed $value, int $ttl = 0): bool

Beschreibung

wincache_ucache_add() ist Teil der WinCache-Erweiterung für PHP unter Windows und dient dazu, einen Wert atomar in den gemeinsam genutzten User-Cache zu schreiben – jedoch nur dann, wenn der entsprechende Schlüssel dort noch nicht existiert. Existiert der Schlüssel bereits, wird der vorhandene Eintrag nicht überschrieben und die Funktion gibt false zurück.

Diese Eigenschaft macht die Funktion ideal für Sperr- und Initialisierungsszenarien, bei denen sichergestellt werden soll, dass ein Wert nur einmalig gesetzt wird – beispielsweise bei der Implementierung einfacher verteilter Locks oder beim einmaligen Befüllen eines Cache-Eintrags durch den ersten Prozess einer Anfrage.

Im Gegensatz zu wincache_ucache_set(), das einen bestehenden Eintrag immer überschreibt, bietet wincache_ucache_add() eine Race-Condition-sichere Möglichkeit, den Cache zu befüllen. Der Cache ist prozessübergreifend gültig und bleibt über mehrere PHP-Requests hinweg bestehen, solange der IIS-Arbeitsprozess läuft oder der TTL nicht abläuft.

Alternativ kann statt eines einzelnen Schlüssel-Wert-Paares auch ein Array übergeben werden, um mehrere Einträge auf einmal hinzuzufügen. In diesem Fall ist der Rückgabewert ein Array mit den Schlüsseln, die nicht hinzugefügt werden konnten.

Parameter

Name	Typ	Default	Beschreibung
$key Pflicht	string\|array		Der eindeutige Schlüssel, unter dem der Wert im Cache gespeichert wird. Alternativ kann ein assoziatives Array mit mehreren Schlüssel-Wert-Paaren übergeben werden.
$value	mixed		Der zu speichernde Wert. Kann ein beliebiger PHP-Typ sein (Skalare, Arrays, Objekte). Wird ignoriert, wenn `key` bereits ein Array ist.
$ttl	int	0	Time-to-Live in Sekunden. Nach Ablauf dieser Zeit wird der Cache-Eintrag automatisch ungültig. Der Wert `0` bedeutet, dass der Eintrag unbegrenzt gültig bleibt (bis der Prozess neu startet oder der Eintrag manuell gelöscht wird).

Rückgabewert

Typ

bool|array

Beschreibung

Gibt true zurück, wenn der Wert erfolgreich hinzugefügt wurde. Gibt false zurück, wenn der Schlüssel bereits existiert oder ein Fehler aufgetreten ist. Wird ein Array übergeben, enthält der Rückgabewert ein Array mit allen Schlüsseln, die nicht hinzugefügt werden konnten (leeres Array bei vollständigem Erfolg).

Beispiele

Einfachen Cache-Eintrag nur einmalig setzen

<?php
// Ersten Aufruf: Eintrag existiert noch nicht
$result = wincache_ucache_add('config_loaded', true, 300);
if ($result) {
    echo "Eintrag erfolgreich hinzugefügt.\n";
} else {
    echo "Eintrag existierte bereits – nichts geändert.\n";
}

// Zweiter Aufruf: Eintrag existiert jetzt bereits
$result2 = wincache_ucache_add('config_loaded', true, 300);
if (!$result2) {
    echo "Konnte nicht hinzugefügt werden – Schlüssel bereits vorhanden.\n";
}

Eintrag erfolgreich hinzugefügt. Konnte nicht hinzugefügt werden – Schlüssel bereits vorhanden.

Einfaches verteiltes Lock mit wincache_ucache_add

<?php
$lockKey  = 'job_lock_newsletter';
$acquired = wincache_ucache_add($lockKey, 1, 60); // Lock für max. 60 Sekunden

if ($acquired) {
    try {
        // Kritischer Abschnitt: wird nur von einem Prozess ausgeführt
        echo "Lock erworben – starte Newsletter-Versand...\n";
        // ... Aufgabe ausführen ...
    } finally {
        wincache_ucache_delete($lockKey);
        echo "Lock freigegeben.\n";
    }
} else {
    echo "Ein anderer Prozess führt die Aufgabe bereits aus.\n";
}

Lock erworben – starte Newsletter-Versand... Lock freigegeben.

Mehrere Einträge auf einmal hinzufügen

<?php
$data = [
    'lang'    => 'de',
    'version' => '2.0',
    'debug'   => false,
];

$failed = wincache_ucache_add($data);

if (empty($failed)) {
    echo "Alle Einträge erfolgreich hinzugefügt.\n";
} else {
    echo "Folgende Schlüssel konnten nicht hinzugefügt werden: " . implode(', ', $failed) . "\n";
}

Alle Einträge erfolgreich hinzugefügt.

// Wichtig · Fallstricke

Plattformbeschränkung: WinCache ist ausschließlich unter Windows in Verbindung mit dem IIS-Webserver verfügbar. Die Funktion existiert auf Linux/macOS nicht und führt dort zu einem fatalen Fehler. Für plattformübergreifende Projekte sollten Alternativen wie APCu (apcu_add()) oder Memcached/Redis in Betracht gezogen werden.

Atomarität: Die Prüfung, ob ein Schlüssel existiert, und das anschließende Schreiben erfolgen intern atomar. Dies verhindert Race Conditions zwischen konkurrierenden Prozessen – ein wesentlicher Vorteil gegenüber einer manuellen Kombination aus wincache_ucache_exists() und wincache_ucache_set().

TTL-Hinweis: Der TTL-Wert beginnt ab dem Zeitpunkt des Einfügens zu laufen. Bei einem bereits vorhandenen Schlüssel wird der TTL des bestehenden Eintrags durch einen fehlgeschlagenen wincache_ucache_add()-Aufruf nicht verändert.

Siehe auch

wincache_ucache_set wincache_ucache_get wincache_ucache_delete wincache_ucache_exists wincache_ucache_clear apcu_add