From b0a608ab7d319b61fbbe8971ba39af17dee5a350 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 11 Jun 2025 09:49:44 -0400 Subject: [PATCH 1/4] DOCSP-47071: Extended JSON --- source/data-formats.txt | 4 +- source/data-formats/extended-json.txt | 209 ++++++++++++++++++++++++++ source/includes/extended-json.php | 37 +++++ 3 files changed, 249 insertions(+), 1 deletion(-) create mode 100644 source/data-formats/extended-json.txt create mode 100644 source/includes/extended-json.php diff --git a/source/data-formats.txt b/source/data-formats.txt index 99c495af..aa019178 100644 --- a/source/data-formats.txt +++ b/source/data-formats.txt @@ -25,6 +25,7 @@ Specialized Data Formats Decimal128 BSON Time Series + Extended JSON Overview -------- @@ -36,4 +37,5 @@ guides: - :ref:`php-custom-types` - :ref:`php-decimal128` - :ref:`php-bson` -- :ref:`php-time-series` \ No newline at end of file +- :ref:`php-time-series` +- :ref:`php-extended-json` \ No newline at end of file diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt new file mode 100644 index 00000000..3bbb5a47 --- /dev/null +++ b/source/data-formats/extended-json.txt @@ -0,0 +1,209 @@ +.. _php-extended-json: + +============================ +Work with Extended JSON Data +============================ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code examples, bson, relaxed, canonical, legacy + +Overview +-------- + +In this guide, you can learn how to use the **Extended JSON** data format +when interacting with MongoDB documents. + +JSON is a human-readable data format that represents the values of objects, +arrays, numbers, strings, booleans, and nulls. This format supports only a +subset of BSON data types, which is the format that MongoDB uses to store data. The +Extended JSON format provides additional BSON support, defining a reserved +set of keys prefixed with "``$``" to represent field type information that +directly corresponds to each type in BSON. + +Extended JSON Formats +--------------------- + +MongoDB Extended JSON features two string formats to represent BSON data. +Each format conforms to the `JSON RFC `__ +and meets specific use cases. + +The following table describes each Extended JSON format: + +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :widths: 10 40 + + * - Name + - Description + + * - **Canonical** or **Extended** + - | A string format that avoids loss of BSON type information during data conversions. + | This format prioritizes type preservation at the loss of human-readability and + interoperability with older formats. + + * - **Relaxed Mode** + - | A string format that describes BSON documents with some type information loss. + | This format prioritizes human-readability and interoperability at the loss of + certain type information. + +To learn more about JSON, BSON, and Extended JSON, see the +`JSON and BSON `__ resource +and :manual:`Extended JSON ` {+mdb-server+} manual +entry. + +.. _php-extended_json_example: + +Extended JSON Examples +~~~~~~~~~~~~~~~~~~~~~~ + +The following example shows a document containing an ObjectId, date, and long +number field represented in the Extended JSON format. Select the :guilabel:`Canonical` +or the :guilabel:`Relaxed Mode` tab to view the sample document in each Extended +JSON format: + +.. tabs:: + + .. tab:: Canonical + :tabid: canonical-format + + .. code-block:: json + + { + "_id": { "$oid": "573a1391f29313caabcd9637" }, + "createdAt": { "$date": { "$numberLong": "1601499609" }}, + "numViews": { "$numberLong": "36520312" } + } + + .. tab:: Relaxed Mode + :tabid: relaxed-mode-format + + .. code-block:: json + + { + "_id": { "$oid": "573a1391f29313caabcd9637" }, + "createdAt": { "$date": "2020-09-30T18:22:51.648Z" }, + "numViews": 36520312 + } + +Write Extended JSON +------------------- + +You can write an Extended JSON string from a BSON document object by using the +``toRelaxedExtendedJSON()`` and ``toCanonicalExtendedJSON()`` methods. + +The following example outputs a BSON document in both Relaxed and Canonical +Extended JSON formats: + +.. io-code-block:: + :copyable: + + .. input:: /includes/extended-json.php + :start-after: start-write-extended + :end-before: end-write-extended + :language: php + :dedent: + + .. output:: + :visible: false + + Relaxed format: { "foo" : [ 1, 2 ], "bar" : { "hello" : "world" }, "code" : + { "$code" : "function x() { return 1; }", "$scope" : { } }, "date" : { } } + Canonical format: { "foo" : [ { "$numberInt" : "1" }, { "$numberInt" : "2" } ], + "bar" : { "hello" : "world" }, "code" : { "$code" : "function x() { return 1; }", + "$scope" : { } }, "date" : { } } + +Read Extended JSON +------------------ + +You can read an Extended JSON string into a PHP value by calling +the ``json_decode()`` method, which converts Extended JSON to a +PHP array or object. Pass the following arguments to ``json_decode()``: + +- Extended JSON string to read. +- Boolean value that indicates whether you want to return + an array value. If set to ``false``, the method returns an + object value. + +The following example converts an Extended JSON string value +to a PHP array: + +.. io-code-block:: + :copyable: + + .. input:: /includes/extended-json.php + :start-after: start-read-extended + :end-before: end-read-extended + :language: php + :dedent: + + .. output:: + :visible: false + + Array + ( + [foo] => Array + ( + [0] => Array + ( + [$numberInt] => 1 + ) + + [1] => Array + ( + [$numberInt] => 2 + ) + + ) + + [bar] => Array + ( + [hello] => world + ) + + [code] => Array + ( + [$code] => function x() { return 1; } + [$scope] => Array + ( + ) + + ) + + [bin] => Array + ( + [$binary] => Array + ( + [base64] => AQIDBA== + [subType] => 00 + ) + + ) + + ) + +Additional Information +---------------------- + +To learn more about the Extended JSON format, see :manual:`Extended JSON ` +in the {+mdb-server+} manual. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about the methods discussed on this page, see +the following {+extension-short+} API documentation: + +- :php:`MongoDB\BSON\Document::toRelaxedExtendedJSON() ` +- :php:`MongoDB\BSON\Document::toCanonicalExtendedJSON() ` +- :php:`json_decode() ` \ No newline at end of file diff --git a/source/includes/extended-json.php b/source/includes/extended-json.php new file mode 100644 index 00000000..ff8e6412 --- /dev/null +++ b/source/includes/extended-json.php @@ -0,0 +1,37 @@ +test; + +// start-write-extended +$doc = [ + 'foo' => [1, 2], + 'bar' => ['hello' => 'world'], + 'code' => new MongoDB\BSON\Javascript('function x() { return 1; }', []), + 'date' => new DateTime('2024-07-20 10:30:00') +]; + +echo 'Relaxed format: ' , MongoDB\BSON\Document::fromPHP($doc)->toRelaxedExtendedJSON(), PHP_EOL; +echo 'Canonical format: ' , MongoDB\BSON\Document::fromPHP($doc)->toCanonicalExtendedJSON(), PHP_EOL; +// end-write-extended + +// start-read-extended +$ejsonStr = '{ + "foo": [ + { "$numberInt": "1" }, + { "$numberInt": "2" } + ], + "bar": { "hello": "world" }, + "code": { + "$code": "function x() { return 1; }", + "$scope": {} + }, + "bin": { "$binary": { "base64": "AQIDBA==", "subType": "00" } } +}'; + +$decodedJson = json_decode($ejsonStr, true); +print_r($decodedJson); +// end-read-extended \ No newline at end of file From ffec5ff46ff10cb617081e3eb9d91ba48a1bfbc1 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 11 Jun 2025 10:36:47 -0400 Subject: [PATCH 2/4] edits --- source/includes/extended-json.php | 4 ---- 1 file changed, 4 deletions(-) diff --git a/source/includes/extended-json.php b/source/includes/extended-json.php index ff8e6412..f1ad0e9c 100644 --- a/source/includes/extended-json.php +++ b/source/includes/extended-json.php @@ -2,10 +2,6 @@ require 'vendor/autoload.php'; -$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset'); -$client = new MongoDB\Client($uri); -$db = $client->test; - // start-write-extended $doc = [ 'foo' => [1, 2], From 7d499ede5df4be50c5a5c32c3ac89d0619309bd7 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 11 Jun 2025 10:39:21 -0400 Subject: [PATCH 3/4] vale --- source/data-formats/extended-json.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt index 3bbb5a47..63e320e9 100644 --- a/source/data-formats/extended-json.txt +++ b/source/data-formats/extended-json.txt @@ -15,7 +15,7 @@ Work with Extended JSON Data :values: reference .. meta:: - :keywords: code examples, bson, relaxed, canonical, legacy + :keywords: code examples, bson, relaxed, canonical Overview -------- @@ -26,7 +26,7 @@ when interacting with MongoDB documents. JSON is a human-readable data format that represents the values of objects, arrays, numbers, strings, booleans, and nulls. This format supports only a subset of BSON data types, which is the format that MongoDB uses to store data. The -Extended JSON format provides additional BSON support, defining a reserved +Extended JSON format supports more BSON types, defining a reserved set of keys prefixed with "``$``" to represent field type information that directly corresponds to each type in BSON. From f815dc4439cc6a1c601b2dd60c2525daece0c301 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 16 Jun 2025 10:37:26 -0400 Subject: [PATCH 4/4] feedback --- source/data-formats/extended-json.txt | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt index 63e320e9..8227f467 100644 --- a/source/data-formats/extended-json.txt +++ b/source/data-formats/extended-json.txt @@ -67,7 +67,7 @@ entry. Extended JSON Examples ~~~~~~~~~~~~~~~~~~~~~~ -The following example shows a document containing an ObjectId, date, and long +The following example shows a document containing an ``ObjectId``, date, and long number field represented in the Extended JSON format. Select the :guilabel:`Canonical` or the :guilabel:`Relaxed Mode` tab to view the sample document in each Extended JSON format: @@ -192,14 +192,8 @@ to a PHP array: ) -Additional Information ----------------------- - -To learn more about the Extended JSON format, see :manual:`Extended JSON ` -in the {+mdb-server+} manual. - API Documentation -~~~~~~~~~~~~~~~~~ +----------------- To learn more about the methods discussed on this page, see the following {+extension-short+} API documentation: