simdjson_key_exists — Funktion · PHP-Referenz

Signatur

simdjson_key_exists(string $json, string $key, int $depth = 512): bool

Beschreibung

simdjson_key_exists() ist Teil der simdjson_php-Erweiterung und nutzt die hochperformante simdjson-Bibliothek, um blitzschnell zu prüfen, ob ein bestimmter Pfad innerhalb eines JSON-Strings vorhanden ist. Der Pfad wird als JSON-Pointer gemäß RFC 6901 angegeben (z. B. /user/name oder /items/0).

Im Gegensatz zu json_decode() + isset() dekodiert simdjson_key_exists() den JSON-String nicht vollständig in eine PHP-Datenstruktur. Stattdessen wird der String nur so weit geparst, bis der gesuchte Schlüssel gefunden oder sicher ausgeschlossen werden kann. Das macht die Funktion besonders effizient bei großen JSON-Dokumenten.

Die Funktion ist ideal für Validierungsszenarien, bei denen man lediglich die Existenz eines Pfades sicherstellen möchte, bevor man auf den Wert zugreift — etwa in API-Middleware oder beim Verarbeiten von Webhooks. Für den tatsächlichen Abruf des Wertes steht simdjson_key_value() zur Verfügung.

Der $key-Parameter folgt der JSON-Pointer-Syntax: Ein führender / trennt die Pfadsegmente. Array-Indizes werden als Zahlen angegeben. Sonderzeichen wie ~ und / innerhalb von Schlüsselnamen müssen als ~0 bzw. ~1 kodiert werden.

Parameter

Name	Typ	Default	Beschreibung
$json Pflicht	string		Der zu durchsuchende JSON-String. Muss gültiges JSON sein.
$key Pflicht	string		Der JSON-Pointer-Pfad (RFC 6901) zum gesuchten Schlüssel, z. B. `/user/address/city` oder `/items/0/id`. Ein leerer String `""` verweist auf das Wurzeldokument.
$depth	int	512	Maximale Verschachtelungstiefe des JSON-Dokuments. Bei Überschreitung wird `false` zurückgegeben bzw. ein Fehler ausgelöst.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn der angegebene JSON-Pointer im JSON-Dokument existiert, andernfalls false. Bei ungültigem JSON oder zu großer Verschachtelungstiefe kann eine RuntimeException geworfen werden.

Beispiele

Einfache Schlüsselprüfung in einem JSON-Objekt

<?php
$json = '{"user": {"name": "Anna", "age": 30}, "active": true}';

if (simdjson_key_exists($json, '/user/name')) {
    echo "Schlüssel 'name' existiert.\n";
} else {
    echo "Schlüssel 'name' nicht gefunden.\n";
}

var_dump(simdjson_key_exists($json, '/user/email'));
var_dump(simdjson_key_exists($json, '/active'));

Schlüssel 'name' existiert. bool(false) bool(true)

Prüfung eines Array-Elements per JSON-Pointer

<?php
$json = '{"items": [{"id": 1, "label": "Apfel"}, {"id": 2, "label": "Birne"}]}';

// Auf das erste Element zugreifen (Index 0)
var_dump(simdjson_key_exists($json, '/items/0/label'));

// Nicht vorhandener Index
var_dump(simdjson_key_exists($json, '/items/5/label'));

// Nur Array-Wurzel prüfen
var_dump(simdjson_key_exists($json, '/items'));

bool(true) bool(false) bool(true)

Einsatz in einer Webhook-Validierung

<?php
function validateWebhookPayload(string $payload): bool {
    $requiredKeys = ['/event', '/data/user_id', '/data/timestamp'];
    foreach ($requiredKeys as $key) {
        if (!simdjson_key_exists($payload, $key)) {
            error_log("Fehlender Pflichtschlüssel im Webhook: $key");
            return false;
        }
    }
    return true;
}

$payload = '{"event": "login", "data": {"user_id": 42, "timestamp": 1700000000}}';
var_dump(validateWebhookPayload($payload));

$incomplete = '{"event": "login", "data": {"user_id": 42}}';
var_dump(validateWebhookPayload($incomplete));

bool(true) bool(false)

// Wichtig · Fallstricke

Erweiterung erforderlich: simdjson_key_exists() ist keine native PHP-Funktion, sondern Teil der PECL-Erweiterung simdjson. Diese muss separat installiert werden (pecl install simdjson).

Fehlerbehandlung: Bei syntaktisch ungültigem JSON wirft die Funktion eine RuntimeException. Es empfiehlt sich daher, Aufrufe in einem try/catch-Block zu kapseln, insbesondere wenn die JSON-Quelle nicht vertrauenswürdig ist.

JSON-Pointer-Sonderzeichen: Enthält ein Schlüsselname die Zeichen / oder ~, müssen diese als ~1 bzw. ~0 kodiert werden (RFC 6901). Beispiel: Der Schlüssel a/b wird als /a~1b referenziert.

Performance: Der Vorteil gegenüber json_decode() ist besonders bei großen JSON-Dokumenten (mehrere MB) spürbar, da kein vollständiges PHP-Objekt/Array im Speicher aufgebaut wird.

Siehe auch

simdjson_decode simdjson_key_value simdjson_is_valid json_decode array_key_exists