wincache_ucache_inc — Funktion · PHP-Referenz

Signatur

wincache_ucache_inc(string $key, int $inc_by = 1, bool &$success = null): int|false

Beschreibung

wincache_ucache_inc liest den aktuell unter $key im WinCache User-Cache gespeicherten Wert und erhöht ihn atomar um den mit $inc_by angegebenen Betrag. Das Ergebnis wird unmittelbar zurückgeschrieben und zurückgegeben. Da der Vorgang atomar abläuft, ist die Funktion sicher für den Einsatz in parallelen Request-Szenarien, in denen mehrere PHP-Prozesse denselben Zähler aktualisieren.

Typische Anwendungsfälle sind verteilte Zähler, beispielsweise für Rate-Limiting, Seitenaufruf-Statistiken oder das Vergeben eindeutiger, aufsteigender IDs, ohne auf eine Datenbank oder externe Locking-Mechanismen angewiesen zu sein.

Der gespeicherte Wert muss numerisch sein. Ist der Schlüssel nicht vorhanden oder enthält er einen nicht-numerischen Wert, schlägt die Operation fehl und gibt false zurück. Über den optionalen Referenzparameter $success lässt sich programmatisch prüfen, ob die Erhöhung erfolgreich war.

Die Funktion steht nur unter Windows-Systemen zur Verfügung, auf denen die WinCache-Extension installiert und aktiviert ist. Für Unix-/Linux-basierte Systeme bieten apcu_inc oder atomare Datenbankoperationen vergleichbare Funktionalität.

Parameter

Name	Typ	Default	Beschreibung
$key Pflicht	string		Der Schlüssel, unter dem der Wert im WinCache User-Cache gespeichert ist. Groß-/Kleinschreibung wird beachtet.
$inc_by	int	1	Der Betrag, um den der gespeicherte Wert erhöht wird. Standardmäßig wird der Wert um `1` erhöht. Negative Werte bewirken eine Verringerung und entsprechen damit dem Verhalten von `wincache_ucache_dec`.
$success	bool	null	Optionale Referenzvariable, die nach dem Aufruf angibt, ob die Operation erfolgreich war (`true`) oder fehlgeschlagen ist (`false`).

Rückgabewert

Typ

int|false

Beschreibung

Gibt den neuen, erhöhten Wert als int zurück, wenn die Operation erfolgreich war. Gibt false zurück, wenn der Schlüssel nicht vorhanden ist, der gespeicherte Wert nicht numerisch ist oder ein interner Fehler auftritt.

Beispiele

Einfacher Seitenaufruf-Zähler

<?php
// Zähler initialisieren, falls noch nicht vorhanden
if (!wincache_ucache_exists('page_views')) {
    wincache_ucache_set('page_views', 0);
}

// Zähler atomisch um 1 erhöhen
$newCount = wincache_ucache_inc('page_views', 1, $success);

if ($success) {
    echo "Seitenaufrufe: " . $newCount;
} else {
    echo "Fehler beim Erhöhen des Zählers.";
}

Seitenaufrufe: 1

Rate-Limiting mit WinCache

<?php
$ip = $_SERVER['REMOTE_ADDR'];
$cacheKey = 'rate_limit_' . $ip;
$maxRequests = 100;
$ttl = 60; // Sekunden

// Zähler für diese IP initialisieren, falls nicht vorhanden
if (!wincache_ucache_exists($cacheKey)) {
    wincache_ucache_set($cacheKey, 0, $ttl);
}

$requestCount = wincache_ucache_inc($cacheKey, 1, $success);

if (!$success) {
    http_response_code(500);
    exit('Cache-Fehler.');
}

if ($requestCount > $maxRequests) {
    http_response_code(429);
    exit('Zu viele Anfragen. Bitte warten.');
}

echo "Anfrage " . $requestCount . " von " . $maxRequests . " in diesem Zeitfenster verarbeitet.";

Anfrage 1 von 100 in diesem Zeitfenster verarbeitet.

// Wichtig · Fallstricke

Plattformbeschränkung: wincache_ucache_inc ist ausschließlich unter Windows mit der WinCache-Extension verfügbar. PHP-Anwendungen, die auf Linux oder macOS betrieben werden, können diese Funktion nicht nutzen.

Atomizität: Die Erhöhung erfolgt atomar, jedoch muss die Initialisierung des Schlüssels (z. B. via wincache_ucache_set) und die erste Inkrementierung nicht atomar sein. Bei sehr hoher Parallelität kann es in seltenen Fällen zu Race Conditions beim erstmaligen Anlegen des Schlüssels kommen. Verwende hier ggf. wincache_lock für kritische Abschnitte.

Nicht-numerische Werte: Ist der unter $key gespeicherte Wert kein Integer oder numerischer String, schlägt die Funktion fehl und gibt false zurück. Prüfe daher stets den Rückgabewert oder die $success-Variable.

Siehe auch

wincache_ucache_dec wincache_ucache_set wincache_ucache_get wincache_ucache_exists wincache_lock apcu_inc