DOCSP-47864: sort order for updateone / replaceone

source/reference/method/MongoDBCollection-bulkWrite.txt

@@ -141,16 +141,15 @@ Behavior
 .. include:: /includes/extracts/bulkwriteexception-result.rst
 .. include:: /includes/extracts/bulkwriteexception-ordered.rst
 
-.. todo: add output and examples
-
 See Also
 --------
 
+- :ref:`php-bulk-write`
+- :ref:`php-write`
 - :phpmethod:`MongoDB\Collection::deleteMany()`
 - :phpmethod:`MongoDB\Collection::deleteOne()`
 - :phpmethod:`MongoDB\Collection::insertMany()`
 - :phpmethod:`MongoDB\Collection::insertOne()`
 - :phpmethod:`MongoDB\Collection::replaceOne()`
 - :phpmethod:`MongoDB\Collection::updateMany()`
 - :phpmethod:`MongoDB\Collection::updateOne()`
-- :ref:`php-write`

source/reference/method/MongoDBCollection-replaceOne.txt

@@ -2,7 +2,6 @@
 MongoDB\\Collection::replaceOne()
 =================================
 
-
 .. contents:: On this page
    :local:
    :backlinks: none
@@ -89,6 +88,14 @@ Parameters
 
          .. versionadded:: 1.3
 
+     * - sort
+       - array|object
+       - The sort specification for the ordering of the matched
+         documents. Set this option to apply an order to matched
+         documents before the server performs the replace operation.
+
+         .. versionadded:: 1.21
+
      * - upsert
        - boolean
        - If set to ``true``, creates a new document when no document matches the

source/reference/method/MongoDBCollection-updateOne.txt

@@ -2,7 +2,6 @@
 MongoDB\\Collection::updateOne()
 ================================
 
-
 .. contents:: On this page
    :local:
    :backlinks: none
@@ -94,6 +93,14 @@ Parameters
 
          .. versionadded:: 1.3
 
+     * - sort
+       - array|object
+       - The sort specification for the ordering of the matched
+         documents. Set this option to apply an order to matched
+         documents before the server performs the update operation.
+
+         .. versionadded:: 1.21
+
      * - upsert
        - boolean
        - If set to ``true``, creates a new document when no document matches the

source/whats-new.txt

@@ -149,6 +149,11 @@ improvements, and fixes:
 - Deprecates the ``flags`` option, used for the deprecated MMAPv1 storage engine. 
   This option will be removed in {+library-short+} v2.0.
 
+- Adds a sort option to the :phpmethod:`MongoDB\Collection::updateOne()`
+  and :phpmethod:`MongoDB\Collection::replaceOne()` methods. This
+  change also allows you to set a sort order as an option when performing
+  update and replace operations in a bulk operation.
+
 For more information about the changes in this version, see the
 :github:`v1.21 release notes
 </mongodb/mongo-php-library/releases/tag/1.21.0>` on GitHub.

source/write/replace.txt

@@ -153,6 +153,10 @@ table describes some options you can set in the array:
          Server manual.
        | Defaults to ``false``.
 
+   * - ``sort``
+     - | Specifies the sort order to apply to documents before
+         performing the replace operation.
+
    * - ``collation``
      - | Specifies the kind of language collation to use when sorting
          results. For more information, see :manual:`Collation </reference/collation/#std-label-collation>`

source/write/update.txt

@@ -119,6 +119,10 @@ describes some options you can set in the array:
          Server manual.
        | Defaults to ``false``.
 
+   * - ``sort``
+     - | Applies to ``updateOne()`` only. Specifies the sort order to
+         apply to documents before performing the update operation.
+
    * - ``collation``
      - | Specifies the kind of language collation to use when sorting
          results. For more information, see :manual:`Collation </reference/collation/#std-label-collation>`
@@ -226,4 +230,4 @@ guide, see the following API documentation:
 
 - :phpmethod:`MongoDB\Collection::updateOne()`
 - :phpmethod:`MongoDB\Collection::updateMany()`
-- :phpclass:`MongoDB\UpdateResult`
+- :phpclass:`MongoDB\UpdateResult`