Merge branch 'v1.19' into merge-v1.18-into-v1.19-1716278245432

* v1.19:
  DOCSP-37027: Fix build errors (#1289)
  PHPLIB-1415 Add tests for PHP 8.4 (#1287)
  PHPLIB-1163 Create tutorial for using MongoDB with Bref (#1273)
  Relax branch-alias on dev-master to avoid update on each release (#1277)
  PHPLIB-1424: Fix potentially racy w:0 unified tests (#1276)
  Leverage PHP 8.0 string functions (#1274)
  Master is now 1.19-dev

Author: alcaeus

.github/actions/setup/action.yml

@@ -46,4 +46,6 @@ runs:
     - name: Install dependencies with Composer
       uses: ramsey/[email protected]
       with:
-        composer-options: "--no-suggest"
+        # Revert when psalm supports PHP 8.4
+        # composer-options: "--no-suggest"
+        composer-options: "--no-suggest ${{ inputs.php-version == '8.4' && '--ignore-platform-req=php+' || '' }}"

.github/workflows/tests.yml

@@ -36,6 +36,7 @@ jobs:
           - "8.1"
           - "8.2"
           - "8.3"
+          - "8.4"
         mongodb-version:
           - "4.4"
         topology:

RELEASING.md

@@ -41,14 +41,14 @@ changes in this maintenance branch. This is important because we will later
 merge the ensuing release commits up to master with `--strategy=ours`, which
 will ignore changes from the merged commits.
 
-## Update composer.json and CI matrices
+## Update extension requirement
 
-This is especially important before releasing a new minor version.
+In `composer.json`, ensure that the version of `ext-mongodb` is correct for
+the library version being released.
+
+## Update CI matrices
 
-Ensure that the extension requirement and branch alias in `composer.json` are
-correct for the library version being released. For example, the 1.15.0 release
-of the library should depend on version `^1.15.0` of the extension and master
-branch alias should be `1.15.x-dev`.
+This is especially important before releasing a new minor version.
 
 If this is the first release of a minor version for the library, it is likely
 following an extension release. The `vars` for calling `compile extension` from
@@ -90,21 +90,22 @@ After releasing a new major or minor version (e.g. 1.9.0), a maintenance branch
 1.9.1) would then be done within that branch and any development for the next
 major or minor release can continue in master.
 
-After creating a maintenance branch, the `extra.branch-alias.dev-master` field
-in the master branch's `composer.json` file should be updated. For example,
-after branching v1.9, `composer.json` in the master branch may still read:
+When work begins on a major new version, create a maintenance branch for the
+last minor version and update the `extra.branch-alias.dev-master` field
+in the master branch's `composer.json` file. For example, after branching v1.99,
+`composer.json` in the master branch may still read:
 
 ```
 "branch-alias": {
-    "dev-master": "1.9.x-dev"
+    "dev-master": "1.x-dev"
 }
 ```
 
 The above would be changed to:
 
 ```
 "branch-alias": {
-    "dev-master": "1.10.x-dev"
+    "dev-master": "2.x-dev"
 }
 ```
 
@@ -124,24 +125,6 @@ $ git checkout -b vX.Y
 $ git push mongodb vX.Y
 ```
 
-Update the master branch alias in `composer.json`:
-
-```diff
- "extra": {
-   "branch-alias": {
--    "dev-master": "1.15.x-dev"
-+    "dev-master": "1.16.x-dev"
-   }
- },
-```
-
-Commit and push this change:
-
-```console
-$ git commit -m "Master is now X.Y-dev" composer.json
-$ git push mongodb
-```
-
 ### After releasing a patch version
 
 If this was a patch release, the maintenance branch must be merged up to master:

composer.json

@@ -53,7 +53,7 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-master": "1.18.x-dev"
+            "dev-master": "1.x-dev"
         }
     },
     "config": {

docs/includes/extracts-option-requires.yaml

@@ -45,3 +45,4 @@ source:
 replacement:
   version: "7.0"
 ...
+

docs/reference/method/MongoDBClient-addSubscriber.txt

@@ -50,9 +50,8 @@ notified once of each event for this Client.
 Example
 -------
 
-Create a :php:`MongoDB\Driver\Monitoring\CommandSubscriber
-<manual/en/class.mongodb-driver-monitoring-commandsubscriber>` that
-logs all events:
+Create a :php:`MongoDB\Driver\Monitoring\CommandSubscriber <manual/en/class.mongodb-driver-monitoring-commandsubscriber>`
+that logs all events:
 
 .. code-block:: php
 

docs/reference/method/MongoDBCollection-dropIndexes.txt

@@ -27,8 +27,7 @@ Parameters
 
 ``$indexName`` : string| :phpclass:`MongoDB\Model\IndexInfo`
   The name or model object of the index to drop. View the existing indexes on
-  the collection using the :phpmethod:`listIndexes()
-  <MongoDB\Collection::listIndexes()>` method.
+  the collection by using the :phpmethod:`MongoDB\Collection::listIndexes()` method.
 
 ``$options`` : array
   An array specifying the desired options.

docs/reference/method/MongoDBCollection-updateMany.txt

@@ -33,9 +33,9 @@ Parameters
 
 ``$update`` : array|object
   Specifies the field and value combinations to update and any relevant update
-  operators. ``$update`` uses MongoDB's :manual:`update operators
-  </reference/operator/update>`. Starting with MongoDB 4.2, an `aggregation
-  pipeline <https://mongodb.com/docs/master/reference/command/update/#update-with-an-aggregation-pipeline>`_
+  operators. ``$update`` uses MongoDB's :manual:`update operators </reference/operator/update>`.
+  Starting with MongoDB 4.2, an `aggregation pipeline
+  <https://mongodb.com/docs/master/reference/command/update/#update-with-an-aggregation-pipeline>`_
   can be passed as this parameter.
 
 ``$options`` : array

docs/tutorial/encryption.txt

@@ -23,7 +23,6 @@ Additionally, either ``crypt_shared`` or ``mongocryptd`` are required in order t
 use *automatic* client-side encryption. Neither is required for *explicit*
 encryption.
 
-
 ``crypt_shared``
 ~~~~~~~~~~~~~~~~
 
@@ -43,7 +42,6 @@ fail if it cannot be loaded.
 For detailed installation instructions see the MongoDB documentation for the
 :manual:`Automatic Encryption Shared Library </core/queryable-encryption/reference/shared-library/>`.
 
-
 ``mongocryptd``
 ~~~~~~~~~~~~~~~
 
@@ -74,7 +72,6 @@ the spawning behavior via various auto encryption
 ``mongocryptd`` is only responsible for supporting automatic client-side encryption
 and does not itself perform any encryption or decryption.
 
-
 Managing Encryption Keys
 ------------------------
 
@@ -105,7 +102,6 @@ encryption key (e.g. user-specific encryption keys) or create them dynamically.
 .. literalinclude:: /examples/encryption/create_data_key.php
    :language: php
 
-
 .. _alt_name:
 
 Referencing Encryption Keys by an Alternative Name

src/functions.php

@@ -45,6 +45,7 @@
 use function is_string;
 use function MongoDB\BSON\fromPHP;
 use function MongoDB\BSON\toPHP;
+use function str_ends_with;
 use function substr;
 
 /**
@@ -497,7 +498,7 @@ function create_field_path_type_map(array $typeMap, string $fieldPath): array
     /* Special case if we want to convert an array, in which case we need to
      * ensure that the field containing the array is exposed as an array,
      * instead of the type given in the type map's array key. */
-    if (substr($fieldPath, -2, 2) === '.$') {
+    if (str_ends_with($fieldPath, '.$')) {
         $typeMap['fieldPaths'][substr($fieldPath, 0, -2)] = 'array';
     }
 

tests/UnifiedSpecTests/Constraint/Matches.php

@@ -37,7 +37,7 @@
 use function PHPUnit\Framework\logicalOr;
 use function range;
 use function sprintf;
-use function strpos;
+use function str_starts_with;
 use function strrchr;
 
 /**
@@ -373,7 +373,7 @@ private static function getOperatorName(BSONDocument $document): string
     {
         // phpcs:ignore Squiz.NamingConventions.ValidVariableName.NotCamelCaps
         foreach ($document as $key => $_) {
-            if (strpos((string) $key, '$$') === 0) {
+            if (str_starts_with((string) $key, '$$')) {
                 return $key;
             }
         }
@@ -394,7 +394,7 @@ private static function isOperator(BSONDocument $document): bool
 
         // phpcs:ignore Squiz.NamingConventions.ValidVariableName.NotCamelCaps
         foreach ($document as $key => $_) {
-            return strpos((string) $key, '$$') === 0;
+            return str_starts_with((string) $key, '$$');
         }
 
         throw new LogicException('should not reach this point');

tests/UnifiedSpecTests/UnifiedTestRunner.php

@@ -35,6 +35,7 @@
 use function PHPUnit\Framework\assertNotFalse;
 use function preg_replace;
 use function sprintf;
+use function str_starts_with;
 use function strlen;
 use function strpos;
 use function substr_replace;
@@ -528,7 +529,7 @@ private function createContext(): Context
             // We assume the internal client URI has multiple mongos hosts
             $multiMongosUri = $this->internalClientUri;
 
-            if (strpos($multiMongosUri, 'mongodb+srv://') === 0) {
+            if (str_starts_with($multiMongosUri, 'mongodb+srv://')) {
                 /* TODO: If an SRV URI is provided, we can consider connecting and
                  * checking the topology for multiple mongoses and then selecting a
                  * single mongos to reconstruct a single mongos URI; however, that

tests/UnifiedSpecTests/command-monitoring/unacknowledgedBulkWrite.json

@@ -1,6 +1,6 @@
 {
   "description": "unacknowledgedBulkWrite",
-  "schemaVersion": "1.0",
+  "schemaVersion": "1.7",
   "createEntities": [
     {
       "client": {
@@ -64,11 +64,29 @@
             ],
             "ordered": false
           }
+        },
+        {
+          "name": "find",
+          "object": "collection",
+          "arguments": {
+            "filter": {}
+          },
+          "expectResult": [
+            {
+              "_id": 1,
+              "x": 11
+            },
+            {
+              "_id": "unorderedBulkWriteInsertW0",
+              "x": 44
+            }
+          ]
         }
       ],
       "expectEvents": [
         {
           "client": "client",
+          "ignoreExtraEvents": true,
           "events": [
             {
               "commandStartedEvent": {