simdjson_key_count — Funktion · PHP-Referenz

Signatur

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

Beschreibung

simdjson_key_count() ist Teil der simdjson-PHP-Erweiterung, die auf dem SIMD-beschleunigten JSON-Parser von Daniel Lemire basiert. Die Funktion navigiert mittels eines JSON-Pointer (RFC 6901) zu einem bestimmten Knoten innerhalb eines JSON-Dokuments und gibt zurück, wie viele direkte Kinder (Schlüssel bei Objekten, Elemente bei Arrays) dieser Knoten besitzt.

Der Einsatz ist besonders dann sinnvoll, wenn man die Anzahl von Eigenschaften oder Array-Elementen kennen möchte, ohne das gesamte JSON-Dokument zu dekodieren – was bei sehr großen JSON-Dokumenten erhebliche Performance-Vorteile bringt. Im Vergleich zu json_decode() gefolgt von count() arbeitet simdjson_key_count() deutlich schneller und speicherschonender.

Der JSON-Pointer-Pfad wird als String übergeben, wobei / als Trennzeichen zwischen den Pfadsegmenten dient. Ein leerer String ("") verweist auf das Wurzelelement. Sonderzeichen im Schlüsselnamen werden gemäß RFC 6901 kodiert: ~1 steht für / und ~0 für ~.

Wenn der angegebene Pfad nicht existiert oder der gefundene Knoten kein Objekt und kein Array ist, wird eine Ausnahme geworfen. Die Funktion steht nur zur Verfügung, wenn die simdjson-Erweiterung installiert ist.

Parameter

Name	Typ	Default	Beschreibung
$json Pflicht	string		Der zu parsende JSON-String. Muss gültiges JSON sein, andernfalls wird eine Ausnahme geworfen.
$key Pflicht	string		Ein JSON-Pointer gemäß RFC 6901, der auf den gewünschten Knoten im JSON-Dokument zeigt. Ein leerer String (`""`) verweist auf das Wurzelelement. Pfadsegmente werden durch `/` getrennt.
$depth	int	512	Maximale erlaubte Verschachtelungstiefe des JSON-Dokuments. Wird diese Tiefe überschritten, wirft die Funktion eine Ausnahme.

Rückgabewert

Typ

int

Beschreibung

Gibt die Anzahl der direkten Kinder des am JSON-Pointer gefundenen Knotens zurück – also die Anzahl der Schlüssel bei einem JSON-Objekt bzw. die Anzahl der Elemente bei einem JSON-Array.

Beispiele

Anzahl der Schlüssel eines JSON-Objekts ermitteln

<?php
$json = '{"name": "Alice", "age": 30, "city": "Berlin"}';

// Schlüsselanzahl des Wurzelobjekts ermitteln
$count = simdjson_key_count($json, '');
echo "Anzahl der Schlüssel: " . $count . PHP_EOL;
// Ausgabe: Anzahl der Schlüssel: 3

Anzahl der Schlüssel: 3

Anzahl von Elementen in einem verschachtelten JSON-Array

<?php
$json = '{
    "users": [
        {"id": 1, "name": "Alice"},
        {"id": 2, "name": "Bob"},
        {"id": 3, "name": "Charlie"}
    ],
    "meta": {
        "total": 3,
        "page": 1
    }
}';

// Anzahl der Elemente im "users"-Array
$userCount = simdjson_key_count($json, '/users');
echo "Anzahl Benutzer: " . $userCount . PHP_EOL;

// Anzahl der Schlüssel im "meta"-Objekt
$metaCount = simdjson_key_count($json, '/meta');
echo "Anzahl Meta-Felder: " . $metaCount . PHP_EOL;

Anzahl Benutzer: 3 Anzahl Meta-Felder: 2

Fehlerbehandlung bei ungültigem Pfad

<?php
$json = '{"data": {"items": [1, 2, 3]}}';

try {
    // Dieser Pfad existiert nicht im JSON
    $count = simdjson_key_count($json, '/nonexistent');
    echo "Anzahl: " . $count . PHP_EOL;
} catch (\SimdJsonException $e) {
    echo "Fehler: " . $e->getMessage() . PHP_EOL;
}

// Korrekte Verwendung
$count = simdjson_key_count($json, '/data/items');
echo "Anzahl Elemente in items: " . $count . PHP_EOL;

Fehler: JSON pointer references a non-existing element Anzahl Elemente in items: 3

// Wichtig · Fallstricke

Erweiterung erforderlich: simdjson_key_count() ist keine eingebaute PHP-Funktion, sondern Teil der simdjson-PECL-Erweiterung. Diese muss separat installiert werden (pecl install simdjson). Vor dem Einsatz sollte mit extension_loaded('simdjson') geprüft werden, ob die Erweiterung verfügbar ist.

Ausnahmen statt Fehlercodes: Im Gegensatz zu json_decode(), das bei Fehlern null zurückgibt, wirft simdjson_key_count() eine \SimdJsonException, wenn das JSON ungültig ist, der Pfad nicht existiert oder der Knoten kein Objekt/Array ist. Immer in einem try/catch-Block verwenden.

Versionshinweis: Die genaue API der simdjson-Erweiterung kann je nach installierter Version variieren. Es empfiehlt sich, stets die Dokumentation der installierten Version zu konsultieren.

Siehe auch

simdjson_decode simdjson_key_exists simdjson_key_value json_decode count