From dd0bcc782208ae72281f93d9cbb5fc66e32993b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Fri, 23 Oct 2026 19:16:57 +0200 Subject: [PATCH] Document duplicate keys behavior in BSON documents --- language-snippets.ent | 31 ++++++++++++++++--- reference/mongodb/bson/document/fromjson.xml | 1 + reference/mongodb/bson/document/get.xml | 6 ++++ .../mongodb/bson/document/getiterator.xml | 6 ++++ reference/mongodb/bson/document/offsetget.xml | 6 ++++ .../bson/document/tocanonicalextendedjson.xml | 1 + .../bson/document/torelaxedextendedjson.xml | 1 + reference/mongodb/functions/bson/fromjson.xml | 1 + .../bson/tocanonicalextendedjson.xml | 1 + reference/mongodb/functions/bson/tojson.xml | 1 + .../functions/bson/torelaxedextendedjson.xml | 1 + 11 files changed, 52 insertions(+), 4 deletions(-) diff --git a/language-snippets.ent b/language-snippets.ent index a721f1edb553..2c5297819c53 100644 --- a/language-snippets.ent +++ b/language-snippets.ent @@ -3448,6 +3448,21 @@ local: { '> + + + If the BSON document contains duplicate keys, all of them are preserved in + the JSON output. + + +'> + + + Duplicate keys in the JSON string are preserved in the order they appear. + + +'> @@ -3511,10 +3526,18 @@ local: { BSON documents can technically contain duplicate keys because documents are - stored as a list of key-value pairs; however, applications should refrain - from generating documents with duplicate keys as server and driver behavior - may be undefined. Since PHP objects and arrays cannot have duplicate keys, - data could also be lost when decoding a BSON document with duplicate keys. + stored as a list of key-value pairs; however, applications should avoid + creating documents with duplicate keys. The server and other drivers may + handle them differently, and PHP objects and arrays cannot have duplicate + keys, so data is lost when decoding a BSON document with duplicate keys. + + + The driver does not validate duplicate keys and its current behavior is + covered by tests, but it is not a supported feature. When decoding to PHP, + the last value for a duplicate key is used. A + MongoDB\BSON\Document keeps all duplicate keys in + their original order, and its MongoDB\BSON\Document::get + method returns the first value. '> diff --git a/reference/mongodb/bson/document/fromjson.xml b/reference/mongodb/bson/document/fromjson.xml index 23e460fb9eb8..aa38b9a77753 100644 --- a/reference/mongodb/bson/document/fromjson.xml +++ b/reference/mongodb/bson/document/fromjson.xml @@ -39,6 +39,7 @@ Returns a new MongoDB\BSON\Document instance. + &mongodb.note.duplicate-keys.fromjson; diff --git a/reference/mongodb/bson/document/get.xml b/reference/mongodb/bson/document/get.xml index c9f4186e1f1c..2f53901f29e6 100644 --- a/reference/mongodb/bson/document/get.xml +++ b/reference/mongodb/bson/document/get.xml @@ -42,6 +42,12 @@ MongoDB\BSON\Int64 instance. + + + If the document contains duplicate keys, the value of the first matching key + is returned. + + diff --git a/reference/mongodb/bson/document/getiterator.xml b/reference/mongodb/bson/document/getiterator.xml index 1992625f6daa..f574c80df95d 100644 --- a/reference/mongodb/bson/document/getiterator.xml +++ b/reference/mongodb/bson/document/getiterator.xml @@ -26,6 +26,12 @@ Returns a MongoDB\BSON\Iterator instance that can be used to iterate over all keys in the document. + + + If the document contains duplicate keys, the iterator returns every + element in the original order. + + diff --git a/reference/mongodb/bson/document/offsetget.xml b/reference/mongodb/bson/document/offsetget.xml index 8463b5aef5cc..31e87eac6b07 100644 --- a/reference/mongodb/bson/document/offsetget.xml +++ b/reference/mongodb/bson/document/offsetget.xml @@ -42,6 +42,12 @@ MongoDB\BSON\Int64 instance. + + + If the document contains duplicate keys, the value of the first matching key + is returned. + + diff --git a/reference/mongodb/bson/document/tocanonicalextendedjson.xml b/reference/mongodb/bson/document/tocanonicalextendedjson.xml index 55413c48df96..30815e5c19a2 100644 --- a/reference/mongodb/bson/document/tocanonicalextendedjson.xml +++ b/reference/mongodb/bson/document/tocanonicalextendedjson.xml @@ -35,6 +35,7 @@ Canonical Extended JSON representation of the BSON document. + &mongodb.note.duplicate-keys.tojson; diff --git a/reference/mongodb/bson/document/torelaxedextendedjson.xml b/reference/mongodb/bson/document/torelaxedextendedjson.xml index 569f7a0d5754..8682b84e6856 100644 --- a/reference/mongodb/bson/document/torelaxedextendedjson.xml +++ b/reference/mongodb/bson/document/torelaxedextendedjson.xml @@ -34,6 +34,7 @@ Relaxed Extended JSON representation of the BSON document. + &mongodb.note.duplicate-keys.tojson; diff --git a/reference/mongodb/functions/bson/fromjson.xml b/reference/mongodb/functions/bson/fromjson.xml index a91e0e0b2df1..d673f85a6b7d 100644 --- a/reference/mongodb/functions/bson/fromjson.xml +++ b/reference/mongodb/functions/bson/fromjson.xml @@ -49,6 +49,7 @@ The serialized BSON document as a binary string. + &mongodb.note.duplicate-keys.fromjson; diff --git a/reference/mongodb/functions/bson/tocanonicalextendedjson.xml b/reference/mongodb/functions/bson/tocanonicalextendedjson.xml index 63f8cde31402..23d4a56e57af 100644 --- a/reference/mongodb/functions/bson/tocanonicalextendedjson.xml +++ b/reference/mongodb/functions/bson/tocanonicalextendedjson.xml @@ -53,6 +53,7 @@ The converted JSON value. + &mongodb.note.duplicate-keys.tojson; diff --git a/reference/mongodb/functions/bson/tojson.xml b/reference/mongodb/functions/bson/tojson.xml index 44d1aff0d19b..3e5e4254911c 100644 --- a/reference/mongodb/functions/bson/tojson.xml +++ b/reference/mongodb/functions/bson/tojson.xml @@ -78,6 +78,7 @@ The converted JSON value. + &mongodb.note.duplicate-keys.tojson; diff --git a/reference/mongodb/functions/bson/torelaxedextendedjson.xml b/reference/mongodb/functions/bson/torelaxedextendedjson.xml index e767d51aedfe..a4fe3135b3b3 100644 --- a/reference/mongodb/functions/bson/torelaxedextendedjson.xml +++ b/reference/mongodb/functions/bson/torelaxedextendedjson.xml @@ -52,6 +52,7 @@ The converted JSON value. + &mongodb.note.duplicate-keys.tojson;