PHPLIB-208: Remind users about BSON comparison behavior

docs/includes/extracts-note.yaml

+ref: note-bson-comparison
+content: |
+  When evaluating query criteria, MongoDB compares types and values according to
+  its own :manual:`comparison rules for BSON types
+  </reference/bson-type-comparison-order>`, which differs from PHP's
+  :php:`comparison <manual/en/types.comparisons.php>` and :php:`type juggling
+  <manual/en/language.types.type-juggling.php>` rules. When matching a special
+  BSON type the query criteria should use the respective :php:`BSON class
+  <manual/en/book.bson.php>` in the driver (e.g. use
+  :php:`MongoDB\\BSON\\ObjectID <class.mongodb-bson-objectid>` to match an
+  :manual:`ObjectId </reference/object-id/>`).
+...

docs/reference/method/MongoDBCollection-count.txt

@@ -42,6 +42,11 @@ Errors/Exceptions
 .. include:: /includes/extracts/error-invalidargumentexception.rst
 .. include:: /includes/extracts/error-driver-runtimeexception.rst
 
+Behavior
+--------
+
+.. include:: /includes/extracts/note-bson-comparison.rst
+
 .. todo: add output and examples
 
 See Also

docs/reference/method/MongoDBCollection-deleteMany.txt

@@ -42,6 +42,11 @@ Errors/Exceptions
 .. include:: /includes/extracts/error-invalidargumentexception.rst
 .. include:: /includes/extracts/error-driver-runtimeexception.rst
 
+Behavior
+--------
+
+.. include:: /includes/extracts/note-bson-comparison.rst
+
 Example
 -------
 

docs/reference/method/MongoDBCollection-deleteOne.txt

@@ -44,6 +44,11 @@ Errors/Exceptions
 .. include:: /includes/extracts/error-invalidargumentexception.rst
 .. include:: /includes/extracts/error-driver-runtimeexception.rst
 
+Behavior
+--------
+
+.. include:: /includes/extracts/note-bson-comparison.rst
+
 Example
 -------
 

docs/reference/method/MongoDBCollection-distinct.txt

@@ -42,6 +42,11 @@ Errors/Exceptions
 .. include:: /includes/extracts/error-invalidargumentexception.rst
 .. include:: /includes/extracts/error-driver-runtimeexception.rst
 
+Behavior
+--------
+
+.. include:: /includes/extracts/note-bson-comparison.rst
+
 Examples
 --------
 

docs/reference/method/MongoDBCollection-find.txt

@@ -41,6 +41,11 @@ Errors/Exceptions
 .. include:: /includes/extracts/error-invalidargumentexception.rst
 .. include:: /includes/extracts/error-driver-runtimeexception.rst
 
+Behavior
+--------
+
+.. include:: /includes/extracts/note-bson-comparison.rst
+
 Examples
 --------
 

docs/reference/method/MongoDBCollection-findOne.txt

@@ -43,6 +43,11 @@ Errors/Exceptions
 .. include:: /includes/extracts/error-invalidargumentexception.rst
 .. include:: /includes/extracts/error-driver-runtimeexception.rst
 
+Behavior
+--------
+
+.. include:: /includes/extracts/note-bson-comparison.rst
+
 Examples
 --------
 

docs/reference/method/MongoDBCollection-findOneAndDelete.txt

@@ -43,6 +43,11 @@ Errors/Exceptions
 .. include:: /includes/extracts/error-invalidargumentexception.rst
 .. include:: /includes/extracts/error-driver-runtimeexception.rst
 
+Behavior
+--------
+
+.. include:: /includes/extracts/note-bson-comparison.rst
+
 Examples
 --------
 

docs/reference/method/MongoDBCollection-findOneAndReplace.txt

@@ -45,6 +45,11 @@ Errors/Exceptions
 .. include:: /includes/extracts/error-invalidargumentexception.rst
 .. include:: /includes/extracts/error-driver-runtimeexception.rst
 
+Behavior
+--------
+
+.. include:: /includes/extracts/note-bson-comparison.rst
+
 Examples
 --------
 

docs/reference/method/MongoDBCollection-findOneAndUpdate.txt

@@ -45,6 +45,11 @@ Errors/Exceptions
 .. include:: /includes/extracts/error-invalidargumentexception.rst
 .. include:: /includes/extracts/error-driver-runtimeexception.rst
 
+Behavior
+--------
+
+.. include:: /includes/extracts/note-bson-comparison.rst
+
 Examples
 --------
 

docs/reference/method/MongoDBCollection-replaceOne.txt

@@ -44,6 +44,11 @@ Errors/Exceptions
 .. include:: /includes/extracts/error-invalidargumentexception.rst
 .. include:: /includes/extracts/error-driver-runtimeexception.rst
 
+Behavior
+--------
+
+.. include:: /includes/extracts/note-bson-comparison.rst
+
 Example
 -------
 

docs/reference/method/MongoDBCollection-updateMany.txt

@@ -42,6 +42,11 @@ Errors/Exceptions
 .. include:: /includes/extracts/error-invalidargumentexception.rst
 .. include:: /includes/extracts/error-driver-runtimeexception.rst
 
+Behavior
+--------
+
+.. include:: /includes/extracts/note-bson-comparison.rst
+
 Examples
 --------
 

docs/reference/method/MongoDBCollection-updateOne.txt

@@ -44,6 +44,11 @@ Errors/Exceptions
 .. include:: /includes/extracts/error-invalidargumentexception.rst
 .. include:: /includes/extracts/error-driver-runtimeexception.rst
 
+Behavior
+--------
+
+.. include:: /includes/extracts/note-bson-comparison.rst
+
 Examples
 --------
 

docs/reference/method/MongoDBGridFSBucket-find.txt

@@ -41,6 +41,11 @@ Errors/Exceptions
 .. include:: /includes/extracts/error-invalidargumentexception.rst
 .. include:: /includes/extracts/error-driver-runtimeexception.rst
 
+Behavior
+--------
+
+.. include:: /includes/extracts/note-bson-comparison.rst
+
 .. todo: add examples
 
 See Also

docs/reference/method/MongoDBGridFSBucket-findOne.txt

@@ -44,6 +44,11 @@ Errors/Exceptions
 .. include:: /includes/extracts/error-invalidargumentexception.rst
 .. include:: /includes/extracts/error-driver-runtimeexception.rst
 
+Behavior
+--------
+
+.. include:: /includes/extracts/note-bson-comparison.rst
+
 .. todo: add examples
 
 See Also

docs/tutorial/crud.txt

@@ -92,6 +92,8 @@ The |php-library| provides the :phpmethod:`MongoDB\\Collection::findOne()` and
 :phpmethod:`MongoDB\\Collection::aggregate()` method for performing
 :manual:`aggregation operations </core/aggregation-pipeline>`.
 
+.. include:: /includes/extracts/note-bson-comparison.rst
+
 Find One Document
 ~~~~~~~~~~~~~~~~~
 
@@ -137,6 +139,16 @@ The output would then resemble::
      }
    }
 
+.. note::
+
+   The criteria in this example matched an ``_id`` with a string value of
+   ``"94301"``. The same criteria would not have matched a document with an
+   integer value of ``94301`` due to MongoDB's :manual:`comparison rules for
+   BSON types </reference/bson-type-comparison-order>`. Similarly, users should
+   use a :php:`MongoDB\\BSON\\ObjectID <class.mongodb-bson-objectid>` object
+   when matching an ``_id`` with an :manual:`ObjectId </reference/object-id/>`
+   value, as strings and ObjectIds are not directly comparable.
+
 .. seealso:: :phpmethod:`MongoDB\\Collection::findOne()`
 
 Find Many Documents