json_encode

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL json >= 1.2.0)

json_encode — Liefert die JSON-Darstellung eines Wertes

Beschreibung

json_encode(mixed $value, int $flags = 0, int $depth = 512): string|false

Gibt eine Zeichenkette zurück, die die JSON-Darstellung des übergebenen value beinhaltet. Wenn der Parameter ein Array oder Objekt ist, wird er rekursiv serialisiert.

Wenn ein Wert, der serialisiert werden soll, ein Objekt ist, dann werden standardmäßig nur die öffentlich sichtbaren Eigenschaften einbezogen. Alternativ dazu kann eine Klasse JsonSerializable implementieren, um zu steuern, wie ihre Werte zu JSON serialisiert werden.

Die Kodierung wird von den übergebenen flags beeinflusst und zusätzlich hängt die Kodierung von Float-Werten vom Wert von serialize_precision ab.

Parameter-Liste

value

Der zu kodierende value. Kann von jedem Typ außer Ressource sein.

Alle Zeichenketten müssen in UTF-8 kodiert sein.

Hinweis:
PHP implementiert eine Obermenge von JSON wie im Original » RFC 7159 beschrieben.

flags

Eine Bitmaske bestehend aus JSON_FORCE_OBJECT, JSON_HEX_QUOT, JSON_HEX_TAG, JSON_HEX_AMP, JSON_HEX_APOS, JSON_INVALID_UTF8_IGNORE, JSON_INVALID_UTF8_SUBSTITUTE, JSON_NUMERIC_CHECK, JSON_PARTIAL_OUTPUT_ON_ERROR, JSON_PRESERVE_ZERO_FRACTION, JSON_PRETTY_PRINT, JSON_UNESCAPED_LINE_TERMINATORS, JSON_UNESCAPED_SLASHES, JSON_UNESCAPED_UNICODE, JSON_THROW_ON_ERROR. Das Verhalten dieser Konstanten ist auf der Seite über die JSON-Konstanten beschrieben.

depth

Setzt die maximale Verschachtelungstiefe. Muss größer als Null sein.

Rückgabewerte

Gibt einen JSON-kodierten String zurück. Bei einem Fehler wird false zurückgegeben.

Changelog

Version Beschreibung

7.3.0 Die flags-Konstante JSON_THROW_ON_ERROR wurde hinzugefügt.

7.2.0 Die flags-Konstanten JSON_INVALID_UTF8_IGNORE und JSON_INVALID_UTF8_SUBSTITUTE wurden hinzugefügt.

7.1.0 Die flags-Konstante JSON_UNESCAPED_LINE_TERMINATORS wurde hinzugefügt.

7.1.0 serialize_precision wird nun anstatt precision verwendet, wenn Werte vom Typ float (Gleitkommazahlen) kodiert werden.

Version	Beschreibung
7.3.0	Die `flags`-Konstante `JSON_THROW_ON_ERROR` wurde hinzugefügt.
7.2.0	Die `flags`-Konstanten `JSON_INVALID_UTF8_IGNORE` und `JSON_INVALID_UTF8_SUBSTITUTE` wurden hinzugefügt.
7.1.0	Die `flags`-Konstante `JSON_UNESCAPED_LINE_TERMINATORS` wurde hinzugefügt.
7.1.0	serialize_precision wird nun anstatt precision verwendet, wenn Werte vom Typ float (Gleitkommazahlen) kodiert werden.

Beispiele

Beispiel #1 Ein json_encode()-Beispiel

<?php
$arr = array('a' => 1, 'b' => 2, 'c' => 3, 'd' => 4, 'e' => 5);

echo json_encode($arr);
?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

{"a":1,"b":2,"c":3,"d":4,"e":5}

Beispiel #2 Ein json_encode()-Beispiel, das den Einsatz einiger Optionen zeigt

<?php
$a = array('<foo>',"'bar'",'"baz"','&blong&', "\xc3\xa9");

echo "Normal: ",  json_encode($a), "\n";
echo "Tags: ",    json_encode($a, JSON_HEX_TAG), "\n";
echo "Apos: ",    json_encode($a, JSON_HEX_APOS), "\n";
echo "Quot: ",    json_encode($a, JSON_HEX_QUOT), "\n";
echo "Amp: ",     json_encode($a, JSON_HEX_AMP), "\n";
echo "Unicode: ", json_encode($a, JSON_UNESCAPED_UNICODE), "\n";
echo "All: ",     json_encode($a, JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_HEX_AMP | JSON_UNESCAPED_UNICODE), "\n\n";

$b = array();

echo "Ausgabe eines leeren Arrays als Array: ", json_encode($b), "\n";
echo "Ausgabe eines leeren Arrays als Objekt: ", json_encode($b, JSON_FORCE_OBJECT), "\n\n";

$c = array(array(1,2,3));

echo "Ausgabe eines nichtassoziativen Arrays als Array: ", json_encode($c), "\n";
echo "Ausgabe eines nichtassoziativen Arrays als Objekt: ", json_encode($c, JSON_FORCE_OBJECT), "\n\n";

$d = array('foo' => 'bar', 'baz' => 'long');

echo "Assoziative Arrays werden immer als Objekt ausgegeben: ", json_encode($d), "\n";
echo "Assoziative Arrays werden immer als Objekt ausgegeben: ", json_encode($d, JSON_FORCE_OBJECT), "\n\n";
?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

Normal: ["<foo>","'bar'","\"baz\"","&blong&","\u00e9"]
Tags: ["\u003Cfoo\u003E","'bar'","\"baz\"","&blong&","\u00e9"]
Apos: ["<foo>","\u0027bar\u0027","\"baz\"","&blong&","\u00e9"]
Quot: ["<foo>","'bar'","\u0022baz\u0022","&blong&","\u00e9"]
Amp: ["<foo>","'bar'","\"baz\"","\u0026blong\u0026","\u00e9"]
Unicode: ["<foo>","'bar'","\"baz\"","&blong&","é"]
All: ["\u003Cfoo\u003E","\u0027bar\u0027","\u0022baz\u0022","\u0026blong\u0026","é"]

Ausgabe eines leeren Arrays als Array: []
Ausgabe eines leeren Arrays als Objekt: {}

Ausgabe eines nichtassoziativen Arrays als Array: [[1,2,3]]
Ausgabe eines nichtassoziativen Arrays als Objekt: {"0":{"0":1,"1":2,"2":3}}

Assoziative Arrays werden immer als Objekt ausgegeben: {"foo":"bar","baz":"long"}
Assoziative Arrays werden immer als Objekt ausgegeben: {"foo":"bar","baz":"long"}

Beispiel #3 JSON_NUMERIC_CHECK-Option-Beispiel

<?php
echo "Zeichenketten, die Zahlen darstellen, werden automatisch in Zahlen umgewandelt".PHP_EOL;
$numbers = array('+123123', '-123123', '1.2e3', '0.00001');
var_dump(
 $numbers,
 json_encode($numbers, JSON_NUMERIC_CHECK)
);
echo "Zeichenketten, die unsachgemäß formatierte Zahlen enthalten".PHP_EOL;
$strings = array('+a33123456789', 'a123');
var_dump(
 $strings,
 json_encode($strings, JSON_NUMERIC_CHECK)
);
?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

Zeichenketten, die Zahlen darstellen, werden automatisch in Zahlen umgewandelt
array(4) {
  [0]=>
  string(7) "+123123"
  [1]=>
  string(7) "-123123"
  [2]=>
  string(5) "1.2e3"
  [3]=>
  string(7) "0.00001"
}
string(28) "[123123,-123123,1200,1.0e-5]"
Zeichenketten, die unsachgemäß formatierte Zahlen enthalten
array(2) {
  [0]=>
  string(13) "+a33123456789"
  [1]=>
  string(4) "a123"
}
string(24) "["+a33123456789","a123"]"

Beispiel #4 Beispiel für sequentielle und nicht sequentielle Arrays

<?php
echo "Sequentielles Array".PHP_EOL;
$sequential = array("foo", "bar", "baz", "blong");
var_dump(
 $sequential,
 json_encode($sequential)
);

echo PHP_EOL."Nicht-sequentielles Array".PHP_EOL;
$nonsequential = array(1=>"foo", 2=>"bar", 3=>"baz", 4=>"blong");
var_dump(
 $nonsequential,
 json_encode($nonsequential)
);

echo PHP_EOL."Sequentielles Array mit einem entfernten Schlüssel".PHP_EOL;
unset($sequential[1]);
var_dump(
 $sequential,
 json_encode($sequential)
);
?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

Sequentielles Array
array(4) {
  [0]=>
  string(3) "foo"
  [1]=>
  string(3) "bar"
  [2]=>
  string(3) "baz"
  [3]=>
  string(5) "blong"
}
string(27) "["foo","bar","baz","blong"]"

Nicht-sequentielles Array
array(4) {
  [1]=>
  string(3) "foo"
  [2]=>
  string(3) "bar"
  [3]=>
  string(3) "baz"
  [4]=>
  string(5) "blong"
}
string(43) "{"1":"foo","2":"bar","3":"baz","4":"blong"}"

Sequentielles Array mit einem entfernten Schlüssel
array(3) {
  [0]=>
  string(3) "foo"
  [2]=>
  string(3) "baz"
  [3]=>
  string(5) "blong"
}
string(33) "{"0":"foo","2":"baz","3":"blong"}"

Beispiel #5 JSON_PRESERVE_ZERO_FRACTION-Option-Beispiel

<?php
var_dump(json_encode(12.0, JSON_PRESERVE_ZERO_FRACTION));
var_dump(json_encode(12.0));
?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

string(4) "12.0"
string(2) "12"

Anmerkungen

Hinweis:
Falls ein Fehler beim kodieren auftritt, kann json_last_error() verwendet werden, um die genaue Ursache des Fehlers festzustellen.

Hinweis:
Wenn ein Array kodiert wird und die Schlüssel keine kontinuierliche numerische Folge, beginnend bei 0, sind, werden alle Schlüssel als Zeichenketten kodiert und explizit für jedes Schlüssel-Wert-Paar angegeben.

Hinweis:
Wie der Referenz JSON-Encoder gibt auch json_encode() einen einfachen Wert (also weder ein Objekt noch ein Array) aus, wenn ein String, Integer, Float oder Boolean als Eingabe für value übergeben wird. Während die meisten Decoder diese Werte als gültiges JSON akzeptieren, könnte es einige geben die dies ablehnen, da die Spezifikationen in diesem Punkt mehrdeutig sind.

Um es zusammenzufassen: Prüfen Sie immer, ob ihr JSON-Decoder die Ausgabe, die Sie mittels json_encode() erzeugen, verarbeiten kann.

Siehe auch

JsonSerializable
json_decode() - Dekodiert eine JSON-Zeichenkette
json_last_error() - Gibt den letzten aufgetretenen Fehler zurück
json_last_error_msg() - Liefert die Fehlermeldung des letzten Aufrufs von json_validate(), json_encode() oder json_decode()
serialize() - Erzeugt eine speicherbare Repräsentation eines Wertes