Skip to content

Commit ecdacff

Browse files
alcaeusalcaeus
authored
PHPLIB-601: Document upcoming typing changes (#985)
* Fix wrong information about group helper in upgrade guide * Rename upgrade guide to "Legacy Driver Upgrade Guide" * PHPLIB-601: Document upcoming typing changes * Update method signatures in documentation * Rename upgrade file to account for new version number * Document method signature changes by class * Fix wrong method signature in docs * Fix syntax and update wording
1 parent c697472 commit ecdacff

14 files changed

+82
-16
lines changed

Diff for: ‎UPGRADE-1.15.md

+66
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# UPGRADE FROM 1.x to 1.15
2+
3+
## Method signature changes
4+
5+
### Parameter types
6+
7+
Starting with 1.15, methods now declare types for their arguments. This will not
8+
cause BC breaks unless you've passed a type that was incompatible with the type
9+
previously documented in the PHPDoc comment. A list of changes can be found at
10+
the bottom of this document.
11+
12+
### Return types
13+
14+
Return types will be added in version 2.0. These types are documented in a
15+
PHPDoc comment and will eventually become a declared return type. You can
16+
prepare for this change (which will trigger a BC break in any class you may
17+
extend) by adding the correct return type to your class at this time.
18+
19+
## Internal classes
20+
21+
Internal classes (i.e. annotated with `@internal`) will become final where
22+
possible in a future release. At the same time, we will add return types to
23+
these internal classes. Note that internal classes are not covered by our
24+
backward compatibility promise, and you should not instantiate such classes
25+
directly.
26+
27+
## Method signature changes by class
28+
29+
### MongoDB\Client
30+
31+
| 1.13 | 1.15 |
32+
|-----------------------------------------------------------------------------------------------:|:--------------------------------------------------------------------------------------|
33+
| `__construct($uri = 'mongodb://127.0.0.1', array $uriOptions = [], array $driverOptions = [])` | `__construct(?string $uri = null, array $uriOptions = [], array $driverOptions = [])` |
34+
| `__get($databaseName)` | `__get(string $databaseName)` |
35+
| `dropDatabase($databaseName, array $options = [])` | `dropDatabase(string $databaseName, array $options = [])` |
36+
| `selectCollection($databaseName, $collectionName, array $options = [])` | `selectCollection(string $databaseName, string $collectionName, array $options = [])` |
37+
| `selectDatabase($databaseName, array $options = [])` | `selectDatabase(string $databaseName, array $options = [])` |
38+
39+
### MongoDB\Database
40+
41+
| 1.13 | 1.15 |
42+
|-----------------------------------------------------------------------------------:|:------------------------------------------------------------------------------------------|
43+
| `__construct(MongoDB\Driver\Manager $manager, $databaseName, array $options = [])` | `__construct(MongoDB\Driver\Manager $manager, string $databaseName, array $options = [])` |
44+
| `__get($collectionName)` | `__get(string $collectionName)` |
45+
| `createCollection($collectionName, array $options = [])` | `createCollection(string $collectionName, array $options = [])` |
46+
| `dropCollection($collectionName, array $options = [])` | `dropCollection(string $collectionName, array $options = [])` |
47+
| `modifyCollection($collectionName, array $collectionOptions, array $options = [])` | `modifyCollection(string $collectionName, array $collectionOptions, array $options = [])` |
48+
| `selectCollection($collectionName, array $options = [])` | `selectCollection(string $collectionName, array $options = [])` |
49+
50+
### MongoDB\Collection
51+
52+
| 1.13 | 1.15 |
53+
|----------------------------------------------------------------------------------------------------:|:------------------------------------------------------------------------------------------------------------------|
54+
| `__construct(MongoDB\Driver\Manager $manager, $databaseName, $collectionName, array $options = [])` | `__construct(MongoDB\Driver\Manager $manager, string $databaseName, string $collectionName, array $options = [])` |
55+
| `distinct($fieldName, $filter = [], array $options = [])` | `distinct(string $fieldName, $filter = [], array $options = [])` |
56+
57+
### MongoDB\GridFS\Bucket
58+
59+
| 1.13 | 1.15 |
60+
|-----------------------------------------------------------------------------------:|:------------------------------------------------------------------------------------------|
61+
| `__construct(MongoDB\Driver\Manager $manager, $databaseName, array $options = [])` | `__construct(MongoDB\Driver\Manager $manager, string $databaseName, array $options = [])` |
62+
| `downloadToStreamByName($filename, $destination, array $options = [])` | `downloadToStreamByName(string $filename, $destination, array $options = [])` |
63+
| `openDownloadStreamByName($filename, array $options = [])` | `openDownloadStreamByName(string $filename, array $options = [])` |
64+
| `openUploadStream($filename, array $options = [])` | `openUploadStream(string $filename, array $options = [])` |
65+
| `uploadFromStream($filename, $source, array $options = [])` | `uploadFromStream(string $filename, $source, array $options = [])` |
66+
| `rename($id, $newFilename)` | `rename($id, string $newFilename)` |

Diff for: ‎docs/reference/method/MongoDBClient-dropDatabase.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Definition
1919

2020
.. code-block:: php
2121

22-
function dropDatabase($databaseName, array $options []): array|object
22+
function dropDatabase(string $databaseName, array $options = []): array|object
2323

2424
This method has the following parameters:
2525

Diff for: ‎docs/reference/method/MongoDBClient-selectCollection.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Definition
1919

2020
.. code-block:: php
2121

22-
function selectCollection($databaseName, $collectionName, array $options = []): MongoDB\Collection
22+
function selectCollection(string $databaseName, string $collectionName, array $options = []): MongoDB\Collection
2323

2424
This method has the following parameters:
2525

Diff for: ‎docs/reference/method/MongoDBClient-selectDatabase.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Definition
1919

2020
.. code-block:: php
2121

22-
function selectDatabase($databaseName, array $options = []): MongoDB\Database
22+
function selectDatabase(string $databaseName, array $options = []): MongoDB\Database
2323

2424
This method has the following parameters:
2525

Diff for: ‎docs/reference/method/MongoDBClient__get.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ Definition
2121

2222
.. code-block:: php
2323

24-
function __get($databaseName): MongoDB\Database
24+
function __get(string $databaseName): MongoDB\Database
2525

2626
This method has the following parameters:
2727

Diff for: ‎docs/reference/method/MongoDBCollection-distinct.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Definition
1919

2020
.. code-block:: php
2121

22-
function distinct($fieldName, $filter = [], array $options = []): mixed[]
22+
function distinct(string $fieldName, $filter = [], array $options = []): mixed[]
2323

2424
This method has the following parameters:
2525

Diff for: ‎docs/reference/method/MongoDBCollection__construct.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Definition
1919

2020
.. code-block:: php
2121

22-
function __construct(MongoDB\Driver\Manager $manager, $databaseName, $collectionName, array $options = [])
22+
function __construct(MongoDB\Driver\Manager $manager, string $databaseName, string $collectionName, array $options = [])
2323

2424
This constructor has the following parameters:
2525

Diff for: ‎docs/reference/method/MongoDBGridFSBucket-downloadToStreamByName.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ Definition
2020

2121
.. code-block:: php
2222

23-
function downloadToStreamByName($filename, $destination, array $options = []): void
23+
function downloadToStreamByName(string $filename, $destination, array $options = []): void
2424

2525
This method has the following parameters:
2626

Diff for: ‎docs/reference/method/MongoDBGridFSBucket-openDownloadStreamByName.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Definition
1919

2020
.. code-block:: php
2121

22-
function openDownloadStreamByName($filename, array $options = []): resource
22+
function openDownloadStreamByName(string $filename, array $options = []): resource
2323

2424
This method has the following parameters:
2525

Diff for: ‎docs/reference/method/MongoDBGridFSBucket-openUploadStream.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Definition
1919

2020
.. code-block:: php
2121

22-
function openUploadStream($filename, array $options = []): resource
22+
function openUploadStream(string $filename, array $options = []): resource
2323

2424
This method has the following parameters:
2525

Diff for: ‎docs/reference/method/MongoDBGridFSBucket-rename.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Definition
1919

2020
.. code-block:: php
2121

22-
function rename($id, $newFilename): void
22+
function rename($id, string $newFilename): void
2323

2424
This method has the following parameters:
2525

Diff for: ‎docs/reference/method/MongoDBGridFSBucket-uploadFromStream.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Definition
1919

2020
.. code-block:: php
2121

22-
function uploadFromStream($filename, $source, array $options = []): mixed
22+
function uploadFromStream(string $filename, $source, array $options = []): mixed
2323

2424
This method has the following parameters:
2525

Diff for: ‎docs/reference/method/MongoDBGridFSBucket__construct.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Definition
1919

2020
.. code-block:: php
2121

22-
function __construct(MongoDB\Driver\Manager $manager, $databaseName, array $options = [])
22+
function __construct(MongoDB\Driver\Manager $manager, string $databaseName, array $options = [])
2323

2424
This constructor has the following parameters:
2525

Diff for: ‎docs/upgrade.txt

+4-4
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
=============
2-
Upgrade Guide
3-
=============
1+
===========================
2+
Legacy Driver Upgrade Guide
3+
===========================
44

55
.. default-domain:: mongodb
66

@@ -281,7 +281,7 @@ inadvertent and potentially dangerous :manual:`full-document replacements
281281
Group Command Helper
282282
~~~~~~~~~~~~~~~~~~~~
283283

284-
:phpclass:`MongoDB\\Collection` does have a helper method for the
284+
:phpclass:`MongoDB\\Collection` does not have a helper method for the
285285
:manual:`group </reference/command/group>` command. The following example
286286
demonstrates how to execute a group command using the
287287
:phpmethod:`MongoDB\\Database::command()` method:

0 commit comments

Comments
 (0)