Skip to content

Commit b0a608a

Browse files
norareidynorareidy
committed
DOCSP-47071: Extended JSON
1 parent 99f0974 commit b0a608a

File tree

3 files changed

+249
-1
lines changed

3 files changed

+249
-1
lines changed

‎source/data-formats.txt

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ Specialized Data Formats
2525
Decimal128 </data-formats/decimal128>
2626
BSON </data-formats/modeling-bson-data>
2727
Time Series </data-formats/time-series>
28+
Extended JSON </data-formats/extended-json>
2829

2930
Overview
3031
--------
@@ -36,4 +37,5 @@ guides:
3637
- :ref:`php-custom-types`
3738
- :ref:`php-decimal128`
3839
- :ref:`php-bson`
39-
- :ref:`php-time-series`
40+
- :ref:`php-time-series`
41+
- :ref:`php-extended-json`

‎source/data-formats/extended-json.txt

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
.. _php-extended-json:
2+
3+
============================
4+
Work with Extended JSON Data
5+
============================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: code examples, bson, relaxed, canonical, legacy
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the **Extended JSON** data format
24+
when interacting with MongoDB documents.
25+
26+
JSON is a human-readable data format that represents the values of objects,
27+
arrays, numbers, strings, booleans, and nulls. This format supports only a
28+
subset of BSON data types, which is the format that MongoDB uses to store data. The
29+
Extended JSON format provides additional BSON support, defining a reserved
30+
set of keys prefixed with "``$``" to represent field type information that
31+
directly corresponds to each type in BSON.
32+
33+
Extended JSON Formats
34+
---------------------
35+
36+
MongoDB Extended JSON features two string formats to represent BSON data.
37+
Each format conforms to the `JSON RFC <https://www.rfc-editor.org/rfc/rfc8259>`__
38+
and meets specific use cases.
39+
40+
The following table describes each Extended JSON format:
41+
42+
.. list-table::
43+
:header-rows: 1
44+
:stub-columns: 1
45+
:widths: 10 40
46+
47+
* - Name
48+
- Description
49+
50+
* - **Canonical** or **Extended**
51+
- | A string format that avoids loss of BSON type information during data conversions.
52+
| This format prioritizes type preservation at the loss of human-readability and
53+
interoperability with older formats.
54+
55+
* - **Relaxed Mode**
56+
- | A string format that describes BSON documents with some type information loss.
57+
| This format prioritizes human-readability and interoperability at the loss of
58+
certain type information.
59+
60+
To learn more about JSON, BSON, and Extended JSON, see the
61+
`JSON and BSON <https://www.mongodb.com/resources/basics/json-and-bson>`__ resource
62+
and :manual:`Extended JSON </reference/mongodb-extended-json/>` {+mdb-server+} manual
63+
entry.
64+
65+
.. _php-extended_json_example:
66+
67+
Extended JSON Examples
68+
~~~~~~~~~~~~~~~~~~~~~~
69+
70+
The following example shows a document containing an ObjectId, date, and long
71+
number field represented in the Extended JSON format. Select the :guilabel:`Canonical`
72+
or the :guilabel:`Relaxed Mode` tab to view the sample document in each Extended
73+
JSON format:
74+
75+
.. tabs::
76+
77+
.. tab:: Canonical
78+
:tabid: canonical-format
79+
80+
.. code-block:: json
81+
82+
{
83+
"_id": { "$oid": "573a1391f29313caabcd9637" },
84+
"createdAt": { "$date": { "$numberLong": "1601499609" }},
85+
"numViews": { "$numberLong": "36520312" }
86+
}
87+
88+
.. tab:: Relaxed Mode
89+
:tabid: relaxed-mode-format
90+
91+
.. code-block:: json
92+
93+
{
94+
"_id": { "$oid": "573a1391f29313caabcd9637" },
95+
"createdAt": { "$date": "2020-09-30T18:22:51.648Z" },
96+
"numViews": 36520312
97+
}
98+
99+
Write Extended JSON
100+
-------------------
101+
102+
You can write an Extended JSON string from a BSON document object by using the
103+
``toRelaxedExtendedJSON()`` and ``toCanonicalExtendedJSON()`` methods.
104+
105+
The following example outputs a BSON document in both Relaxed and Canonical
106+
Extended JSON formats:
107+
108+
.. io-code-block::
109+
:copyable:
110+
111+
.. input:: /includes/extended-json.php
112+
:start-after: start-write-extended
113+
:end-before: end-write-extended
114+
:language: php
115+
:dedent:
116+
117+
.. output::
118+
:visible: false
119+
120+
Relaxed format: { "foo" : [ 1, 2 ], "bar" : { "hello" : "world" }, "code" :
121+
{ "$code" : "function x() { return 1; }", "$scope" : { } }, "date" : { } }
122+
Canonical format: { "foo" : [ { "$numberInt" : "1" }, { "$numberInt" : "2" } ],
123+
"bar" : { "hello" : "world" }, "code" : { "$code" : "function x() { return 1; }",
124+
"$scope" : { } }, "date" : { } }
125+
126+
Read Extended JSON
127+
------------------
128+
129+
You can read an Extended JSON string into a PHP value by calling
130+
the ``json_decode()`` method, which converts Extended JSON to a
131+
PHP array or object. Pass the following arguments to ``json_decode()``:
132+
133+
- Extended JSON string to read.
134+
- Boolean value that indicates whether you want to return
135+
an array value. If set to ``false``, the method returns an
136+
object value.
137+
138+
The following example converts an Extended JSON string value
139+
to a PHP array:
140+
141+
.. io-code-block::
142+
:copyable:
143+
144+
.. input:: /includes/extended-json.php
145+
:start-after: start-read-extended
146+
:end-before: end-read-extended
147+
:language: php
148+
:dedent:
149+
150+
.. output::
151+
:visible: false
152+
153+
Array
154+
(
155+
[foo] => Array
156+
(
157+
[0] => Array
158+
(
159+
[$numberInt] => 1
160+
)
161+
162+
[1] => Array
163+
(
164+
[$numberInt] => 2
165+
)
166+
167+
)
168+
169+
[bar] => Array
170+
(
171+
[hello] => world
172+
)
173+
174+
[code] => Array
175+
(
176+
[$code] => function x() { return 1; }
177+
[$scope] => Array
178+
(
179+
)
180+
181+
)
182+
183+
[bin] => Array
184+
(
185+
[$binary] => Array
186+
(
187+
[base64] => AQIDBA==
188+
[subType] => 00
189+
)
190+
191+
)
192+
193+
)
194+
195+
Additional Information
196+
----------------------
197+
198+
To learn more about the Extended JSON format, see :manual:`Extended JSON </reference/mongodb-extended-json/>`
199+
in the {+mdb-server+} manual.
200+
201+
API Documentation
202+
~~~~~~~~~~~~~~~~~
203+
204+
To learn more about the methods discussed on this page, see
205+
the following {+extension-short+} API documentation:
206+
207+
- :php:`MongoDB\BSON\Document::toRelaxedExtendedJSON() <mongodb-bson-document.torelaxedextendedjson>`
208+
- :php:`MongoDB\BSON\Document::toCanonicalExtendedJSON() <mongodb-bson-document.tocanonicalextendedjson>`
209+
- :php:`json_decode() <function.json-decode>`

‎source/includes/extended-json.php

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
<?php
2+
3+
require 'vendor/autoload.php';
4+
5+
$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset');
6+
$client = new MongoDB\Client($uri);
7+
$db = $client->test;
8+
9+
// start-write-extended
10+
$doc = [
11+
'foo' => [1, 2],
12+
'bar' => ['hello' => 'world'],
13+
'code' => new MongoDB\BSON\Javascript('function x() { return 1; }', []),
14+
'date' => new DateTime('2024-07-20 10:30:00')
15+
];
16+
17+
echo 'Relaxed format: ' , MongoDB\BSON\Document::fromPHP($doc)->toRelaxedExtendedJSON(), PHP_EOL;
18+
echo 'Canonical format: ' , MongoDB\BSON\Document::fromPHP($doc)->toCanonicalExtendedJSON(), PHP_EOL;
19+
// end-write-extended
20+
21+
// start-read-extended
22+
$ejsonStr = '{
23+
"foo": [
24+
{ "$numberInt": "1" },
25+
{ "$numberInt": "2" }
26+
],
27+
"bar": { "hello": "world" },
28+
"code": {
29+
"$code": "function x() { return 1; }",
30+
"$scope": {}
31+
},
32+
"bin": { "$binary": { "base64": "AQIDBA==", "subType": "00" } }
33+
}';
34+
35+
$decodedJson = json_decode($ejsonStr, true);
36+
print_r($decodedJson);
37+
// end-read-extended

0 commit comments

Comments
 (0)