Signatur
Beschreibung
wincache_ucache_dec dekrementiert einen bereits im WinCache-Benutzercache (User Cache) gespeicherten ganzzahligen Wert atomar um den angegebenen Betrag. Die Funktion ist damit das Gegenstück zu wincache_ucache_inc und eignet sich für Anwendungsfälle wie Zähler, Rate-Limiting oder die Verwaltung von Ressourcen-Kontingenten in Windows-basierten PHP-Umgebungen (IIS).
Der Schlüssel muss bereits im Cache vorhanden und als numerischer Wert gespeichert 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. Die Operation ist atomar, was bedeutet, dass keine Race-Conditions in Umgebungen mit mehreren parallelen Prozessen auftreten.
Über den optionalen Parameter $success (per Referenz) kann der Aufrufer gezielt prüfen, ob die Operation erfolgreich war – selbst wenn der resultierende Wert 0 oder negativ ist, was andernfalls nicht zuverlässig von einem Fehlerfall zu unterscheiden wäre.
Diese Funktion steht ausschließlich unter Windows mit der WinCache-Erweiterung zur Verfügung und ist damit ein Windows-IIS-spezifisches Caching-Werkzeug ohne Entsprechung auf Linux/macOS.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $key Pflicht | string | Der Schlüssel, unter dem der zu dekrementierende Wert im WinCache-Benutzercache gespeichert ist. | |
| $dec_by | int | 1 | Der Betrag, um den der gespeicherte Wert verringert werden soll. Standardmäßig wird um 1 dekrementiert. Negative Werte sind möglich, kehren aber de facto die Richtung um. |
| $success | bool | null | Wird per Referenz übergeben und nach dem Aufruf auf true gesetzt, wenn die Operation erfolgreich war, andernfalls auf false. Ermöglicht eine eindeutige Erfolgsprüfung, auch wenn der resultierende Wert 0 ist. |
Rückgabewert
int zurück, wenn die Operation erfolgreich war. Gibt false zurück, wenn der Schlüssel nicht existiert, der gespeicherte Wert nicht numerisch ist oder ein anderer Fehler aufgetreten ist.Beispiele
Einfaches Dekrementieren eines Zählers
<?php
// Initialen Wert speichern
wincache_ucache_set('downloads_remaining', 10);
// Wert um 1 verringern
$neu = wincache_ucache_dec('downloads_remaining');
echo "Downloads verbleibend: " . $neu; // 9
// Wert um 3 verringern
$neu = wincache_ucache_dec('downloads_remaining', 3);
echo "Downloads verbleibend: " . $neu; // 6
?>Erfolgsprüfung über den $success-Parameter
<?php
wincache_ucache_set('token_budget', 5);
$result = wincache_ucache_dec('token_budget', 1, $success);
if ($success) {
echo "Dekrementierung erfolgreich. Neuer Wert: " . $result;
} else {
echo "Fehler beim Dekrementieren.";
}
// Versuch mit nicht vorhandenem Schlüssel
$result2 = wincache_ucache_dec('nicht_vorhanden', 1, $success2);
if (!$success2) {
echo "Schlüssel nicht gefunden oder kein numerischer Wert.";
}
?>// Wichtig · Fallstricke
Plattformbeschränkung: wincache_ucache_dec ist ausschließlich unter Windows mit der WinCache-PHP-Erweiterung verfügbar (typischerweise unter IIS). Auf Linux- oder macOS-Systemen steht diese Funktion nicht zur Verfügung.
Atomarität: Die Dekrementierung erfolgt atomar, sodass die Funktion auch in Umgebungen mit mehreren gleichzeitigen Prozessen (z. B. IIS Worker Processes) sicher verwendet werden kann.
Negative Ergebnisse: Der gespeicherte Wert kann durch Dekrementierung negativ werden; die Funktion setzt hierbei keine untere Grenze. Soll ein Unterschreiten von 0 verhindert werden, muss dies in der Anwendungslogik geprüft werden.
Rückgabewert vs. Fehler: Da false und 0 nicht direkt zu unterscheiden sind, sollte im Zweifelsfall der $success-Parameter genutzt werden, um eine sichere Unterscheidung zu ermöglichen.