simdjson_key_value — Funktion · PHP-Referenz

Signatur

simdjson_key_value(string $json, string $key, bool $associative = false, int $depth = 512): mixed

Beschreibung

simdjson_key_value() extrahiert und dekodiert den Wert eines bestimmten Schlüssels (oder Pfades) aus einem JSON-String, indem ein JSON-Pointer (RFC 6901) verwendet wird. Im Gegensatz zu json_decode() gefolgt von einem manuellen Zugriff muss nicht das gesamte JSON-Dokument vollständig in eine PHP-Datenstruktur überführt werden – der Parser kann direkt zum gewünschten Wert navigieren, was bei großen JSON-Dokumenten erhebliche Vorteile in Bezug auf Geschwindigkeit und Speicherverbrauch bietet.

Die Funktion ist Teil der PHP-Erweiterung simdjson, die auf der SIMD-optimierten C++-Bibliothek simdjson basiert und auf modernen Prozessoren durch Nutzung von SIMD-Instruktionen (z. B. AVX2, SSE4.2, NEON) deutlich schneller als der eingebaute PHP-JSON-Parser arbeitet. Sie eignet sich besonders dann, wenn aus großen JSON-Payloads (z. B. API-Antworten, Log-Dateien) nur einzelne Felder benötigt werden.

Der JSON-Pointer wird als Zeichenkette übergeben, die mit / getrennte Schlüssel enthält, z. B. /user/address/city. Für Array-Elemente wird der nullbasierte Index angegeben, z. B. /items/0/name. Ein leerer String "" referenziert das Wurzelelement.

Mit dem Parameter $associative kann gesteuert werden, ob JSON-Objekte als assoziative Arrays (true) oder als stdClass-Instanzen (false) zurückgegeben werden, analog zum gleichnamigen Parameter von json_decode().

Parameter

Name	Typ	Default	Beschreibung
$json Pflicht	string		Der zu parsende JSON-String. Er muss UTF-8-kodiert und gültiges JSON sein.
$key Pflicht	string		Ein JSON-Pointer (RFC 6901) als Zeichenkette, der den Pfad zum gewünschten Wert innerhalb des JSON-Dokuments angibt. Beispiel: `/user/name` oder `/items/2/price`. Ein leerer String verweist auf das gesamte Wurzelelement.
$associative	bool	false	Legt fest, ob JSON-Objekte als assoziative Arrays (`true`) oder als `stdClass`-Objekte (`false`) zurückgegeben werden.
$depth	int	512	Maximale Verschachtelungstiefe des zu parsenden JSON-Dokuments. Wird diese Tiefe überschritten, schlägt das Parsen fehl.

Rückgabewert

Typ

mixed

Beschreibung

Gibt den dekodierten Wert am angegebenen JSON-Pointer zurück. Dies kann ein Skalar (string, int, float, bool, null), ein array oder ein stdClass-Objekt sein, je nach dem Wert im JSON und dem $associative-Parameter. Wird der Schlüssel nicht gefunden oder ist das JSON ungültig, wird eine RuntimeException geworfen.

Beispiele

Einzelnen Wert aus einem JSON-String extrahieren

<?php
$json = '{"user":{"name":"Maria","age":30,"address":{"city":"Berlin","zip":"10115"}}}';

// Nur den Stadtnamen extrahieren – kein vollständiges Dekodieren nötig
$city = simdjson_key_value($json, '/user/address/city');

echo $city; // Berlin

Berlin

Element aus einem JSON-Array extrahieren

<?php
$json = '{"products":[{"id":1,"name":"Tisch"},{"id":2,"name":"Stuhl"},{"id":3,"name":"Lampe"}]}';

// Zweites Produkt (Index 1) als assoziatives Array holen
$product = simdjson_key_value($json, '/products/1', true);

print_r($product);

Array ( [id] => 2 [name] => Stuhl )

Fehlerbehandlung bei ungültigem Pfad

<?php
$json = '{"status":"ok","data":{"value":42}}';

try {
    $result = simdjson_key_value($json, '/data/nonexistent');
} catch (\RuntimeException $e) {
    echo 'Fehler: ' . $e->getMessage();
}

Fehler: The JSON pointer was invalid or could not be found in the document

// Wichtig · Fallstricke

Erweiterung erforderlich: simdjson_key_value() ist nicht Teil der PHP-Standardinstallation. Die PECL-Erweiterung simdjson muss installiert und aktiviert sein (pecl install simdjson).

Prozessor-Voraussetzungen: Die maximale Leistung wird auf Prozessoren mit SIMD-Unterstützung (AVX2, SSE4.2 oder ARM NEON) erzielt. Auf älteren CPUs ohne diese Instruktionen fällt die Bibliothek auf einen kompatiblen, aber langsameren Fallback zurück.

Fehlerbehandlung: Im Gegensatz zu json_decode(), das bei Fehlern null zurückgibt, wirft simdjson_key_value() eine RuntimeException, wenn der JSON-Pointer nicht gefunden wurde oder das JSON ungültig ist. Stets mit try/catch absichern.

JSON-Pointer-Escaping: Schlüssel, die / oder ~ enthalten, müssen gemäß RFC 6901 escaped werden: ~ wird zu ~0, / wird zu ~1.

Siehe auch

simdjson_decode simdjson_key_exists simdjson_is_valid json_decode json_encode