apcu_inc — Funktion · PHP-Referenz

Signatur

apcu_inc(string $key, int $step = 1, bool &$success = null, int $ttl = 0): int|false

Beschreibung

apcu_inc inkrementiert den numerischen Wert, der unter dem angegebenen Schlüssel im APCu-Benutzer-Cache gespeichert ist, um den angegebenen Schrittwert. Die Operation wird atomar ausgeführt, was sie für nebenläufige Zugriffe in Hochlast-Szenarien (z. B. Zähler für Seitenaufrufe, Rate-Limiting) geeignet macht.

Existiert der Schlüssel noch nicht im Cache, wird er mit dem Wert 0 + $step neu angelegt, sofern ein $ttl angegeben wird. Ist der gespeicherte Wert kein Integer, schlägt die Operation fehl und gibt false zurück. Über den optionalen Referenz-Parameter $success lässt sich nach dem Aufruf prüfen, ob die Operation erfolgreich war.

Typische Anwendungsfälle sind Zugriffsstatistiken, das Begrenzen von API-Anfragen (Rate-Limiting) oder einfache verteilte Zähler innerhalb eines einzelnen Servers.

Zu beachten ist, dass APCu nur innerhalb eines einzelnen Server-Prozesses (bzw. PHP-FPM-Pools) gültig ist und bei einem Neustart des Webservers oder PHP-Prozesses verloren geht.

Parameter

Name	Typ	Default	Beschreibung
$key Pflicht	string		Der Schlüssel des Cache-Eintrags, dessen Wert erhöht werden soll.
$step	int	1	Der Betrag, um den der gespeicherte Wert erhöht wird. Standardmäßig `1`. Negative Werte sind möglich, wirken jedoch wie ein Dekrement.
$success	bool	null	Wird per Referenz übergeben und nach dem Aufruf auf `true` gesetzt, wenn die Operation erfolgreich war, andernfalls auf `false`.
$ttl	int	0	Time-to-Live in Sekunden. Wird nur verwendet, wenn der Schlüssel noch nicht existiert und neu angelegt wird. `0` bedeutet, der Eintrag läuft nicht ab.

Rückgabewert

Typ

int|false

Beschreibung

Gibt den neuen (inkrementieren) Wert als int zurück. Schlägt die Operation fehl (z. B. weil der Schlüssel nicht existiert oder keinen numerischen Wert enthält), wird false zurückgegeben.

Beispiele

Einfacher Seitenaufruf-Zähler

<?php
// Initialisierung des Zählers, falls er noch nicht existiert
if (!apcu_exists('page_views')) {
    apcu_store('page_views', 0);
}

// Zähler bei jedem Aufruf um 1 erhöhen
$views = apcu_inc('page_views');

echo "Diese Seite wurde {$views} mal aufgerufen.";

Diese Seite wurde 1 mal aufgerufen.

Rate-Limiting: Anfragen pro Minute begrenzen

<?php
$userId = 42;
$key = 'rate_limit_user_' . $userId;
$maxRequests = 60;
$windowSeconds = 60;

// Schlüssel anlegen falls nicht vorhanden, TTL = 60 Sekunden
if (!apcu_exists($key)) {
    apcu_store($key, 0, $windowSeconds);
}

$requests = apcu_inc($key, 1, $success);

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

if ($requests > $maxRequests) {
    http_response_code(429);
    echo "Zu viele Anfragen. Bitte warte eine Minute.";
    exit;
}

echo "Anfrage {$requests}/{$maxRequests} verarbeitet.";

Anfrage 1/60 verarbeitet.

Erfolgscheck mit Referenz-Parameter

<?php
apcu_store('counter', 10);

$newValue = apcu_inc('counter', 5, $success);

if ($success) {
    echo "Neuer Wert: {$newValue}"; // Ausgabe: Neuer Wert: 15
} else {
    echo "Inkrementierung fehlgeschlagen.";
}

Neuer Wert: 15

// Wichtig · Fallstricke

Atomarität: Die Inkrementierung ist atomar, d. h. bei gleichzeitigen Anfragen (Race Conditions) wird kein Zählschritt verloren. Dies ist besonders wichtig bei stark frequentierten Zählern.

Nicht-numerische Werte: Ist der gespeicherte Wert kein Integer (z. B. ein String oder Array), gibt apcu_inc false zurück. Der Wert im Cache bleibt dabei unverändert.

Nur lokaler Cache: APCu ist kein verteilter Cache. Bei mehreren Servern oder Prozessen sind die Zähler nicht synchronisiert. Für verteilte Umgebungen eignen sich Redis (z. B. INCR) oder Memcached besser.

CLI vs. Web: APCu verhält sich in der CLI anders als im Web-SAPI-Kontext. Im CLI-Modus ist APCu standardmäßig deaktiviert, sofern apc.enable_cli=1 nicht gesetzt ist.

Siehe auch

apcu_dec apcu_store apcu_fetch apcu_exists apcu_delete apcu_cas