Signatur
Beschreibung
apcu_dec() dekrementiert einen im APCu-Cache unter dem angegebenen Schlüssel gespeicherten Integer-Wert atomar, d. h. die Operation ist thread- bzw. prozess-sicher und kann in parallelen Szenarien ohne Race-Conditions eingesetzt werden.
Typische Anwendungsfälle sind Rate-Limiting, das Verwalten von Kontingenten (z. B. verbleibende API-Calls), Sitzungs-Counter oder jede Situation, in der ein geteilter Zähler über mehrere Requests hinweg herunter gezählt werden muss, ohne eine Datenbank bemühen zu müssen.
Existiert der Schlüssel noch nicht im Cache, schlägt die Operation fehl und gibt false zurück. Der optionale Parameter $success wird als Referenz übergeben und enthält nach dem Aufruf true bei Erfolg oder false bei Misserfolg — so lässt sich das Ergebnis auch dann prüfen, wenn der neue Wert 0 oder ein anderer falsy-Wert ist.
Zu beachten ist, dass APCu nur im CLI-Modus verfügbar ist, wenn PHP mit apc.enable_cli=1 gestartet wurde, und dass der Cache prozesslokal ist — bei mehreren PHP-FPM-Workern teilen sich alle Worker desselben Prozesses denselben Cache-Speicher, nicht jedoch Worker verschiedener Prozesse.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $key Pflicht | string | Der Schlüssel des zu dekrementierenden Cache-Eintrags. | |
| $step | int | 1 | Der Betrag, um den der gespeicherte Wert verringert werden soll. Standard ist 1. |
| $success | bool | null | Wird per Referenz übergeben. Nach dem Aufruf enthält die Variable true, wenn die Operation erfolgreich war, andernfalls false. Nützlich, wenn der resultierende Wert 0 sein kann. |
| $ttl | int | 0 | Time-To-Live in Sekunden. Wenn 0, läuft der Eintrag nicht automatisch ab. Dieser Parameter wird nur beim Anlegen eines neuen Eintrags berücksichtigt, nicht beim Aktualisieren. |
Rückgabewert
int zurück, wenn die Operation erfolgreich war. Gibt false zurück, wenn der Schlüssel nicht existiert oder die Operation fehlgeschlagen ist.Beispiele
Einfaches Dekrementieren eines API-Kontingents
<?php
// Kontingent initial setzen (z. B. 100 Anfragen pro Stunde)
apcu_store('api_quota_user_42', 100, 3600);
// Bei jedem API-Aufruf das Kontingent verringern
$remaining = apcu_dec('api_quota_user_42');
if ($remaining === false) {
echo 'Kein Kontingent-Eintrag gefunden.';
} elseif ($remaining < 0) {
echo 'Kontingent erschöpft!';
} else {
echo 'Verbleibende Anfragen: ' . $remaining;
}Zuverlässige Erfolgsprüfung mit dem $success-Parameter
<?php
// Schlüssel existiert noch nicht — apcu_dec schlägt fehl
$newValue = apcu_dec('counter_nicht_vorhanden', 5, $success);
if (!$success) {
echo 'Dekrementierung fehlgeschlagen, Schlüssel existiert nicht.' . PHP_EOL;
// Eintrag anlegen und danach dekrementieren
apcu_store('counter_nicht_vorhanden', 10);
$newValue = apcu_dec('counter_nicht_vorhanden', 5, $success);
}
if ($success) {
echo 'Neuer Wert: ' . $newValue . PHP_EOL;
}Dekrementieren in größeren Schritten
<?php
apcu_store('punkte', 1000);
// 50 Punkte auf einmal abziehen
$punkte = apcu_dec('punkte', 50, $ok);
echo $ok ? 'Punkte nach Abzug: ' . $punkte : 'Fehler beim Abziehen';// Wichtig · Fallstricke
Nicht für negative Werte als Ergebnis prüfen: Wenn der Zähler durch Dekrementierung unter 0 fällt, gibt die Funktion trotzdem einen negativen int zurück und gilt als erfolgreich. Eine Untergrenze (z. B. 0) muss manuell implementiert oder mit apcu_entry() und Locking-Mechanismen abgesichert werden.
Kein persistenter Speicher: APCu-Daten gehen beim Neustart des Webservers/PHP-FPM oder beim Leeren des Caches verloren. Für persistente Zähler sollte eine Datenbank oder Redis verwendet werden.
CLI-Modus: Im CLI-Modus ist APCu standardmäßig deaktiviert. Die INI-Option apc.enable_cli=1 muss gesetzt sein, damit APCu-Funktionen in der Kommandozeile genutzt werden können.