From 2acea9fa59a5b14821386b651d5f31f930abdbc5 Mon Sep 17 00:00:00 2001
From: Jeremy Mikola <jmikola@gmail.com>
Date: Wed, 26 Feb 2025 15:09:05 -0500
Subject: [PATCH 1/3] KMIP masterKey "delegated" option

This was introduced in libmongocrypt with ext-mongodb 1.20 but was never documented.

https://jira.mongodb.org/browse/PHPLIB-1375
---
 language-snippets.ent                         |  5 ++++
 .../driver/clientencryption/createdatakey.xml |  6 +++++
 .../clientencryption/rewrapmanydatakey.xml    | 24 +++++++++++++++++++
 3 files changed, 35 insertions(+)

diff --git a/language-snippets.ent b/language-snippets.ent
index 0f005a0692ad..e9666bda90a0 100644
--- a/language-snippets.ent
+++ b/language-snippets.ent
@@ -3235,6 +3235,11 @@ local: {
        <entry>string</entry>
        <entry>Optional. Host with optional port.</entry>
       </row>
+      <row>
+       <entry>delegated</entry>
+       <entry>bool</entry>
+       <entry>Optional. If true, this key should be decrypted by the KMIP server.</entry>
+      </row>
      </tbody>
     </tgroup>
    </table>
diff --git a/reference/mongodb/mongodb/driver/clientencryption/createdatakey.xml b/reference/mongodb/mongodb/driver/clientencryption/createdatakey.xml
index 50d1f6583ee6..36d7772286dd 100644
--- a/reference/mongodb/mongodb/driver/clientencryption/createdatakey.xml
+++ b/reference/mongodb/mongodb/driver/clientencryption/createdatakey.xml
@@ -121,6 +121,12 @@
       </row>
      </thead>
      <tbody>
+      <row>
+       <entry>PECL mongodb 1.20.0</entry>
+       <entry>
+        Added <literal>"delegated"</literal> to the KMIP provider masterKey options.
+       </entry>
+      </row>
       <row>
        <entry>PECL mongodb 1.15.0</entry>
        <entry>
diff --git a/reference/mongodb/mongodb/driver/clientencryption/rewrapmanydatakey.xml b/reference/mongodb/mongodb/driver/clientencryption/rewrapmanydatakey.xml
index d144c0ffed1b..9b624ec94aa7 100644
--- a/reference/mongodb/mongodb/driver/clientencryption/rewrapmanydatakey.xml
+++ b/reference/mongodb/mongodb/driver/clientencryption/rewrapmanydatakey.xml
@@ -102,6 +102,30 @@
    <member>Throws <classname>MongoDB\Driver\Exception\RuntimeException</classname> on other errors.</member>
   </simplelist>
  </refsect1>
+
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <para>
+   <informaltable>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>PECL mongodb 1.20.0</entry>
+       <entry>
+        Added <literal>"delegated"</literal> to the KMIP provider masterKey options.
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file

From f013a0cb09ade8ede2dfd6e2254244e1b5f4f736 Mon Sep 17 00:00:00 2001
From: Jeremy Mikola <jmikola@gmail.com>
Date: Wed, 26 Feb 2025 15:24:10 -0500
Subject: [PATCH 2/3] MongoDB\Driver\BulkWrite::update() "sort" option

https://jira.mongodb.org/browse/PHPC-2518
---
 .../mongodb/driver/bulkwrite/update.xml       | 25 +++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/reference/mongodb/mongodb/driver/bulkwrite/update.xml b/reference/mongodb/mongodb/driver/bulkwrite/update.xml
index 2a202f1bb0a8..be34e3184b62 100644
--- a/reference/mongodb/mongodb/driver/bulkwrite/update.xml
+++ b/reference/mongodb/mongodb/driver/bulkwrite/update.xml
@@ -97,6 +97,25 @@
           </entry>
           <entry>&false;</entry>
          </row>
+         <row>
+          <entry>sort</entry>
+          <entry><type class="union"><type>array</type><type>object</type></type></entry>
+          <entry>
+           <para>
+            Specify which document the operation updates if the query matches
+            multiple documents. The first document matched by the sort order
+            will be updated.
+           </para>
+           <para>
+            This option cannot be used if <literal>"multi"</literal> is &true;.
+           </para>
+           <para>
+            This option is available in MongoDB 8.0+ and will result in an
+            exception at execution time if specified for an older server
+            version.
+           </para>
+          </entry>
+         </row>
          <row>
           <entry>upsert</entry>
           <entry><type>bool</type></entry>
@@ -145,6 +164,12 @@
       </row>
      </thead>
      <tbody>
+      <row>
+       <entry>PECL mongodb 1.21.0</entry>
+       <entry>
+        Added the <literal>"sort"</literal> option.
+       </entry>
+      </row>
       <row>
        <entry>PECL mongodb 1.7.0</entry>
        <entry>

From 629a526132588f2f7afba4b512eec39851682dce Mon Sep 17 00:00:00 2001
From: Jeremy Mikola <jmikola@gmail.com>
Date: Wed, 26 Feb 2025 15:46:09 -0500
Subject: [PATCH 3/3] Deprecate passing WriteConcern and ReadPreference
 directly to execute methods

https://jira.mongodb.org/browse/PHPC-2489
---
 .../mongodb/mongodb/driver/manager/executebulkwrite.xml  | 9 ++++++++-
 .../mongodb/mongodb/driver/manager/executecommand.xml    | 9 ++++++++-
 .../mongodb/mongodb/driver/manager/executequery.xml      | 9 ++++++++-
 .../mongodb/mongodb/driver/server/executebulkwrite.xml   | 9 ++++++++-
 .../mongodb/mongodb/driver/server/executecommand.xml     | 9 ++++++++-
 reference/mongodb/mongodb/driver/server/executequery.xml | 9 ++++++++-
 6 files changed, 48 insertions(+), 6 deletions(-)

diff --git a/reference/mongodb/mongodb/driver/manager/executebulkwrite.xml b/reference/mongodb/mongodb/driver/manager/executebulkwrite.xml
index 85bcf9650ce2..5896c2d287a2 100644
--- a/reference/mongodb/mongodb/driver/manager/executebulkwrite.xml
+++ b/reference/mongodb/mongodb/driver/manager/executebulkwrite.xml
@@ -13,7 +13,7 @@
    <modifier>final</modifier> <modifier>public</modifier> <type>MongoDB\Driver\WriteResult</type><methodname>MongoDB\Driver\Manager::executeBulkWrite</methodname>
    <methodparam><type>string</type><parameter>namespace</parameter></methodparam>
    <methodparam><type>MongoDB\Driver\BulkWrite</type><parameter>bulk</parameter></methodparam>
-   <methodparam choice="opt"><type class="union"><type>array</type><type>MongoDB\Driver\WriteConcern</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam>
+   <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam>
   </methodsynopsis>
   <para>
    Executes one or more write operations on the primary server.
@@ -92,6 +92,13 @@
       </row>
      </thead>
      <tbody>
+      <row>
+       <entry>PECL mongodb 1.21.0</entry>
+       <entry>
+        Passing a <classname>MongoDB\Driver\WriteConcern</classname> object as
+        <parameter>options</parameter> is deprecated and will be removed in 2.0.
+       </entry>
+      </row>
       <row>
        <entry>PECL mongodb 1.4.4</entry>
        <entry>
diff --git a/reference/mongodb/mongodb/driver/manager/executecommand.xml b/reference/mongodb/mongodb/driver/manager/executecommand.xml
index 71817327bd07..656720363561 100644
--- a/reference/mongodb/mongodb/driver/manager/executecommand.xml
+++ b/reference/mongodb/mongodb/driver/manager/executecommand.xml
@@ -13,7 +13,7 @@
    <modifier>final</modifier> <modifier>public</modifier> <type>MongoDB\Driver\Cursor</type><methodname>MongoDB\Driver\Manager::executeCommand</methodname>
    <methodparam><type>string</type><parameter>db</parameter></methodparam>
    <methodparam><type>MongoDB\Driver\Command</type><parameter>command</parameter></methodparam>
-   <methodparam choice="opt"><type class="union"><type>array</type><type>MongoDB\Driver\ReadPreference</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam>
+   <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam>
   </methodsynopsis>
   <para>
    Selects a server according to the <literal>"readPreference"</literal> option
@@ -96,6 +96,13 @@
       </row>
      </thead>
      <tbody>
+      <row>
+       <entry>PECL mongodb 1.21.0</entry>
+       <entry>
+        Passing a <classname>MongoDB\Driver\ReadPreference</classname> object as
+        <parameter>options</parameter> is deprecated and will be removed in 2.0.
+       </entry>
+      </row>
       <row>
        <entry>PECL mongodb 1.4.4</entry>
        <entry>
diff --git a/reference/mongodb/mongodb/driver/manager/executequery.xml b/reference/mongodb/mongodb/driver/manager/executequery.xml
index c76ec51c386d..16fe5aa797fe 100644
--- a/reference/mongodb/mongodb/driver/manager/executequery.xml
+++ b/reference/mongodb/mongodb/driver/manager/executequery.xml
@@ -13,7 +13,7 @@
    <modifier>final</modifier> <modifier>public</modifier> <type>MongoDB\Driver\Cursor</type><methodname>MongoDB\Driver\Manager::executeQuery</methodname>
    <methodparam><type>string</type><parameter>namespace</parameter></methodparam>
    <methodparam><type>MongoDB\Driver\Query</type><parameter>query</parameter></methodparam>
-   <methodparam choice="opt"><type class="union"><type>array</type><type>MongoDB\Driver\ReadPreference</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam>
+   <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam>
   </methodsynopsis>
   <para>
    Selects a server according to the <literal>"readPreference"</literal> option
@@ -83,6 +83,13 @@
       </row>
      </thead>
      <tbody>
+      <row>
+       <entry>PECL mongodb 1.21.0</entry>
+       <entry>
+        Passing a <classname>MongoDB\Driver\ReadPreference</classname> object as
+        <parameter>options</parameter> is deprecated and will be removed in 2.0.
+       </entry>
+      </row>
       <row>
        <entry>PECL mongodb 1.4.0</entry>
        <entry>
diff --git a/reference/mongodb/mongodb/driver/server/executebulkwrite.xml b/reference/mongodb/mongodb/driver/server/executebulkwrite.xml
index f33a86a15530..10a45616b4db 100644
--- a/reference/mongodb/mongodb/driver/server/executebulkwrite.xml
+++ b/reference/mongodb/mongodb/driver/server/executebulkwrite.xml
@@ -13,7 +13,7 @@
    <modifier>final</modifier> <modifier>public</modifier> <type>MongoDB\Driver\WriteResult</type><methodname>MongoDB\Driver\Server::executeBulkWrite</methodname>
    <methodparam><type>string</type><parameter>namespace</parameter></methodparam>
    <methodparam><type>MongoDB\Driver\BulkWrite</type><parameter>bulk</parameter></methodparam>
-   <methodparam choice="opt"><type class="union"><type>array</type><type>MongoDB\Driver\WriteConcern</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam>
+   <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam>
   </methodsynopsis>
   <para>
    Executes one or more write operations on this server.
@@ -92,6 +92,13 @@
       </row>
      </thead>
      <tbody>
+      <row>
+       <entry>PECL mongodb 1.21.0</entry>
+       <entry>
+        Passing a <classname>MongoDB\Driver\WriteConcern</classname> object as
+        <parameter>options</parameter> is deprecated and will be removed in 2.0.
+       </entry>
+      </row>
       <row>
        <entry>PECL mongodb 1.4.4</entry>
        <entry>
diff --git a/reference/mongodb/mongodb/driver/server/executecommand.xml b/reference/mongodb/mongodb/driver/server/executecommand.xml
index 66aac8f8bd59..a50c612db6c7 100644
--- a/reference/mongodb/mongodb/driver/server/executecommand.xml
+++ b/reference/mongodb/mongodb/driver/server/executecommand.xml
@@ -13,7 +13,7 @@
    <modifier>final</modifier> <modifier>public</modifier> <type>MongoDB\Driver\Cursor</type><methodname>MongoDB\Driver\Server::executeCommand</methodname>
    <methodparam><type>string</type><parameter>db</parameter></methodparam>
    <methodparam><type>MongoDB\Driver\Command</type><parameter>command</parameter></methodparam>
-   <methodparam choice="opt"><type class="union"><type>array</type><type>MongoDB\Driver\ReadPreference</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam>
+   <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam>
   </methodsynopsis>
   <para>
    Executes the command on this server.
@@ -96,6 +96,13 @@
       </row>
      </thead>
      <tbody>
+      <row>
+       <entry>PECL mongodb 1.21.0</entry>
+       <entry>
+        Passing a <classname>MongoDB\Driver\ReadPreference</classname> object as
+        <parameter>options</parameter> is deprecated and will be removed in 2.0.
+       </entry>
+      </row>
       <row>
        <entry>PECL mongodb 1.4.4</entry>
        <entry>
diff --git a/reference/mongodb/mongodb/driver/server/executequery.xml b/reference/mongodb/mongodb/driver/server/executequery.xml
index 7f87246544bf..4efe6f883055 100644
--- a/reference/mongodb/mongodb/driver/server/executequery.xml
+++ b/reference/mongodb/mongodb/driver/server/executequery.xml
@@ -13,7 +13,7 @@
    <modifier>final</modifier> <modifier>public</modifier> <type>MongoDB\Driver\Cursor</type><methodname>MongoDB\Driver\Server::executeQuery</methodname>
    <methodparam><type>string</type><parameter>namespace</parameter></methodparam>
    <methodparam><type>MongoDB\Driver\Query</type><parameter>query</parameter></methodparam>
-   <methodparam choice="opt"><type class="union"><type>array</type><type>MongoDB\Driver\ReadPreference</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam>
+   <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam>
   </methodsynopsis>
   <para>
    Executes the query on this server.
@@ -83,6 +83,13 @@
       </row>
      </thead>
      <tbody>
+      <row>
+       <entry>PECL mongodb 1.21.0</entry>
+       <entry>
+        Passing a <classname>MongoDB\Driver\ReadPreference</classname> object as
+        <parameter>options</parameter> is deprecated and will be removed in 2.0.
+       </entry>
+      </row>
       <row>
        <entry>PECL mongodb 1.4.0</entry>
        <entry>