PHPLIB-601: Document upcoming typing changes

UPGRADE-1.15.md

@@ -0,0 +1,66 @@
+# UPGRADE FROM 1.x to 1.15
+
+## Method signature changes
+
+### Parameter types
+
+Starting with 1.15, methods now declare types for their arguments. This will not
+cause BC breaks unless you've passed a type that was incompatible with the type
+previously documented in the PHPDoc comment. A list of changes can be found at
+the bottom of this document.
+
+### Return types
+
+Return types will be added in version 2.0. These types are documented in a
+PHPDoc comment and will eventually become a declared return type. You can
+prepare for this  change (which will trigger a BC break in any class you may
+extend) by adding the correct return type to your class at this time.
+
+## Internal classes
+
+Internal classes (i.e. annotated with `@internal`) will become final where
+possible in a future release. At the same time, we will add return types to
+these internal classes. Note that internal classes are not covered by our
+backward compatibility promise, and you should not instantiate such classes
+directly.
+
+## Method signature changes by class
+
+### MongoDB\Client
+
+|                                                                                           1.13 | 1.15                                                                                  |
+|-----------------------------------------------------------------------------------------------:|:--------------------------------------------------------------------------------------|
+| `__construct($uri = 'mongodb://127.0.0.1', array $uriOptions = [], array $driverOptions = [])` | `__construct(?string $uri = null, array $uriOptions = [], array $driverOptions = [])` |
+|                                                                         `__get($databaseName)` | `__get(string $databaseName)`                                                         |
+|                                             `dropDatabase($databaseName, array $options = [])` | `dropDatabase(string $databaseName, array $options = [])`                             |
+|                        `selectCollection($databaseName, $collectionName, array $options = [])` | `selectCollection(string $databaseName, string $collectionName, array $options = [])` |
+|                                           `selectDatabase($databaseName, array $options = [])` | `selectDatabase(string $databaseName, array $options = [])`                           |
+
+### MongoDB\Database
+
+|                                                                               1.13 | 1.15                                                                                      |
+|-----------------------------------------------------------------------------------:|:------------------------------------------------------------------------------------------|
+| `__construct(MongoDB\Driver\Manager $manager, $databaseName, array $options = [])` | `__construct(MongoDB\Driver\Manager $manager, string $databaseName, array $options = [])` |
+|                                                           `__get($collectionName)` | `__get(string $collectionName)`                                                           |
+|                           `createCollection($collectionName, array $options = [])` | `createCollection(string $collectionName, array $options = [])`                           |
+|                             `dropCollection($collectionName, array $options = [])` | `dropCollection(string $collectionName, array $options = [])`                             |
+| `modifyCollection($collectionName, array $collectionOptions, array $options = [])` | `modifyCollection(string $collectionName, array $collectionOptions, array $options = [])` |
+|                           `selectCollection($collectionName, array $options = [])` | `selectCollection(string $collectionName, array $options = [])`                           |
+
+### MongoDB\Collection
+
+|                                                                                                1.13 | 1.15                                                                                                              |
+|----------------------------------------------------------------------------------------------------:|:------------------------------------------------------------------------------------------------------------------|
+| `__construct(MongoDB\Driver\Manager $manager, $databaseName, $collectionName, array $options = [])` | `__construct(MongoDB\Driver\Manager $manager, string $databaseName, string $collectionName, array $options = [])` |
+|                                           `distinct($fieldName, $filter = [], array $options = [])` | `distinct(string $fieldName, $filter = [], array $options = [])`                                                  |
+
+### MongoDB\GridFS\Bucket
+
+|                                                                               1.13 | 1.15                                                                                      |
+|-----------------------------------------------------------------------------------:|:------------------------------------------------------------------------------------------|
+| `__construct(MongoDB\Driver\Manager $manager, $databaseName, array $options = [])` | `__construct(MongoDB\Driver\Manager $manager, string $databaseName, array $options = [])` |
+|             `downloadToStreamByName($filename, $destination, array $options = [])` | `downloadToStreamByName(string $filename, $destination, array $options = [])`             |
+|                         `openDownloadStreamByName($filename, array $options = [])` | `openDownloadStreamByName(string $filename, array $options = [])`                         |
+|                                 `openUploadStream($filename, array $options = [])` | `openUploadStream(string $filename, array $options = [])`                                 |
+|                        `uploadFromStream($filename, $source, array $options = [])` | `uploadFromStream(string $filename, $source, array $options = [])`                        |
+|                                                        `rename($id, $newFilename)` | `rename($id, string $newFilename)`                                                        |

docs/reference/method/MongoDBClient-dropDatabase.txt

@@ -19,7 +19,7 @@ Definition
 
    .. code-block:: php
 
-      function dropDatabase($databaseName, array $options []): array|object
+      function dropDatabase(string $databaseName, array $options = []): array|object
 
    This method has the following parameters:
 

docs/reference/method/MongoDBClient-selectCollection.txt

@@ -19,7 +19,7 @@ Definition
 
    .. code-block:: php
 
-      function selectCollection($databaseName, $collectionName, array $options = []): MongoDB\Collection
+      function selectCollection(string $databaseName, string $collectionName, array $options = []): MongoDB\Collection
 
    This method has the following parameters:
 

docs/reference/method/MongoDBClient-selectDatabase.txt

@@ -19,7 +19,7 @@ Definition
 
    .. code-block:: php
 
-      function selectDatabase($databaseName, array $options = []): MongoDB\Database
+      function selectDatabase(string $databaseName, array $options = []): MongoDB\Database
 
    This method has the following parameters:
 

docs/reference/method/MongoDBClient__get.txt

@@ -21,7 +21,7 @@ Definition
 
    .. code-block:: php
 
-      function __get($databaseName): MongoDB\Database
+      function __get(string $databaseName): MongoDB\Database
 
    This method has the following parameters:
 

docs/reference/method/MongoDBCollection-distinct.txt

@@ -19,7 +19,7 @@ Definition
 
    .. code-block:: php
 
-      function distinct($fieldName, $filter = [], array $options = []): mixed[]
+      function distinct(string $fieldName, $filter = [], array $options = []): mixed[]
 
    This method has the following parameters:
 

docs/reference/method/MongoDBCollection__construct.txt

@@ -19,7 +19,7 @@ Definition
 
    .. code-block:: php
 
-      function __construct(MongoDB\Driver\Manager $manager, $databaseName, $collectionName, array $options = [])
+      function __construct(MongoDB\Driver\Manager $manager, string $databaseName, string $collectionName, array $options = [])
 
    This constructor has the following parameters:
 

docs/reference/method/MongoDBGridFSBucket-downloadToStreamByName.txt

@@ -20,7 +20,7 @@ Definition
 
    .. code-block:: php
 
-      function downloadToStreamByName($filename, $destination, array $options = []): void
+      function downloadToStreamByName(string $filename, $destination, array $options = []): void
 
    This method has the following parameters:
 

docs/reference/method/MongoDBGridFSBucket-openDownloadStreamByName.txt

@@ -19,7 +19,7 @@ Definition
 
    .. code-block:: php
 
-      function openDownloadStreamByName($filename, array $options = []): resource
+      function openDownloadStreamByName(string $filename, array $options = []): resource
 
    This method has the following parameters:
 

docs/reference/method/MongoDBGridFSBucket-openUploadStream.txt

@@ -19,7 +19,7 @@ Definition
 
    .. code-block:: php
 
-      function openUploadStream($filename, array $options = []): resource
+      function openUploadStream(string $filename, array $options = []): resource
 
    This method has the following parameters:
 

docs/reference/method/MongoDBGridFSBucket-rename.txt

@@ -19,7 +19,7 @@ Definition
 
    .. code-block:: php
 
-      function rename($id, $newFilename): void
+      function rename($id, string $newFilename): void
 
    This method has the following parameters:
 

docs/reference/method/MongoDBGridFSBucket-uploadFromStream.txt

@@ -19,7 +19,7 @@ Definition
 
    .. code-block:: php
 
-      function uploadFromStream($filename, $source, array $options = []): mixed
+      function uploadFromStream(string $filename, $source, array $options = []): mixed
 
    This method has the following parameters:
 

docs/reference/method/MongoDBGridFSBucket__construct.txt

@@ -19,7 +19,7 @@ Definition
 
    .. code-block:: php
 
-      function __construct(MongoDB\Driver\Manager $manager, $databaseName, array $options = [])
+      function __construct(MongoDB\Driver\Manager $manager, string $databaseName, array $options = [])
 
    This constructor has the following parameters:
 

docs/upgrade.txt

@@ -1,6 +1,6 @@
-=============
-Upgrade Guide
-=============
+===========================
+Legacy Driver Upgrade Guide
+===========================
 
 .. default-domain:: mongodb
 
@@ -281,7 +281,7 @@ inadvertent and potentially dangerous :manual:`full-document replacements
 Group Command Helper
 ~~~~~~~~~~~~~~~~~~~~
 
-:phpclass:`MongoDB\\Collection` does have a helper method for the
+:phpclass:`MongoDB\\Collection` does not have a helper method for the
 :manual:`group </reference/command/group>` command. The following example
 demonstrates how to execute a group command using the
 :phpmethod:`MongoDB\\Database::command()` method: