Skip to content

Commit 7656c7b

Browse files
committed
Revise docs and require $options since encryptedFields is required
1 parent 98112f0 commit 7656c7b

4 files changed

+22
-124
lines changed

docs/includes/apiargs-MongoDBDatabase-method-createEncryptedCollection-option.yaml

Lines changed: 0 additions & 93 deletions
This file was deleted.

docs/includes/apiargs-MongoDBDatabase-method-createEncryptedCollection-param.yaml

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,8 @@ arg_name: param
1818
name: $kmsProvider
1919
type: string
2020
description: |
21-
KMS provider (e.g. "local", "aws") that will be used to encrypt new encryption
22-
keys. This corresponds to the ``$kmsProvider`` parameter for
21+
KMS provider (e.g. "local", "aws") that will be used to encrypt new data keys.
22+
This corresponds to the ``$kmsProvider`` parameter for
2323
:php:`MongoDB\\Driver\\ClientEncryption::createDataKey() <mongodb-driver-clientencryption.createdatakey>`.
2424
interface: phpmethod
2525
operation: ~
@@ -29,18 +29,19 @@ arg_name: param
2929
name: $masterKey
3030
type: array|null
3131
description: |
32-
KMS-specific key options that will be used to encrypt new encryption keys.
33-
This corresponds to the ``$masterKey`` parameter for
32+
KMS-specific key options that will be used to encrypt new data keys. This
33+
corresponds to the ``$masterKey`` parameter for
3434
:php:`MongoDB\\Driver\\ClientEncryption::createDataKey() <mongodb-driver-clientencryption.createdatakey>`.
3535
36-
If ``$kmsProvider`` is "local", this parameter should be ``null``.
36+
If ``$kmsProvider`` is "local", this should be ``null``.
3737
interface: phpmethod
3838
operation: ~
3939
optional: false
4040
---
4141
source:
4242
file: apiargs-common-param.yaml
4343
ref: $options
44+
optional: false
4445
post: |
4546
The ``encryptedFields`` option is required.
4647
...

docs/reference/method/MongoDBDatabase-createEncryptedCollection.txt

Lines changed: 15 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -21,14 +21,11 @@ Definition
2121

2222
.. code-block:: php
2323

24-
function createEncryptedCollection(string $collectionName, ClientEncryption $clientEncryption, string $kmsProvider, ?array $masterKey, array $options = []): array
24+
function createEncryptedCollection(string $collectionName, ClientEncryption $clientEncryption, string $kmsProvider, ?array $masterKey, array $options): array
2525

26-
This method wraps :phpmethod:`MongoDB\\Database::createCollection()` with
27-
additional functionality. Unlike ``createCollection()`, this method requires
28-
that the ``encryptedFields`` option be specified.
29-
30-
This function will automatically create data keys for any encrypted fields
31-
where the ``keyId`` option is ``null``. Data keys will be created using
26+
This method wraps :phpmethod:`MongoDB\\Database::createCollection()` and will
27+
automatically create data keys for any encrypted fields where the ``keyId``
28+
option is ``null``. Data keys will be created using
3229
:php:`MongoDB\\Driver\\ClientEncryption::createDataKey() <mongodb-driver-clientencryption.createdatakey>`
3330
and the provided ``$kmsProvider`` and ``$masterKey`` parameters.
3431

@@ -40,13 +37,9 @@ Definition
4037

4138
.. include:: /includes/apiargs/MongoDBDatabase-method-createEncryptedCollection-param.rst
4239

43-
The ``$options`` parameter supports the following options:
44-
45-
.. include:: /includes/apiargs/MongoDBDatabase-method-createEncryptedCollection-option.rst
46-
47-
Note that not all options are available on all versions of MongoDB. Refer to
48-
the :manual:`create </reference/command/create>` command reference in the
49-
MongoDB manual for compatibility considerations.
40+
The ``$options`` parameter supports the same options as
41+
:phpmethod:`MongoDB\\Database::createCollection()`. The ``encryptedFields``
42+
option is required.
5043

5144
Return Values
5245
-------------
@@ -58,11 +51,10 @@ A tuple consisting of the result from
5851
Errors/Exceptions
5952
-----------------
6053

61-
:phpclass:`MongoDB\\Driver\\Exception\\CreateEncryptedCollectionException` if
62-
any error is encountered while creating data keys or invoking
63-
``createCollection()``. The original exception and modified ``encryptedFields``
64-
option can be accessed via ``getPrevious()`` and ``getEncryptedFields()``,
65-
respectively.
54+
:phpclass:`MongoDB\\Exception\\CreateEncryptedCollectionException` if any error
55+
is encountered while creating data keys or invoking ``createCollection()``. The
56+
original exception and modified ``encryptedFields`` option can be accessed via
57+
the ``getPrevious()`` and ``getEncryptedFields()`` methods, respectively.
6658

6759
.. include:: /includes/extracts/error-invalidargumentexception.rst
6860

@@ -104,12 +96,10 @@ an encrypted string field.
10496
);
10597

10698
If the encrypted collection was successfully created, ``$result`` will contain
107-
the return value from :phpmethod:`MongoDB\\Database::createCollection()` (i.e.
108-
:manual:`create </reference/command/create>` command response) and
109-
``$encryptedFields['fields'][0]['keyId']`` will contain the return value from
110-
:php:`MongoDB\\Driver\\ClientEncryption::createDataKey() <mongodb-driver-clientencryption.createdatakey>`
111-
(i.e. a :php:`MongoDB\\BSON\\Binary <class.mongodb-bson-binary>` with subtype 4,
112-
UUID).
99+
the return value from :phpmethod:`MongoDB\\Database::createCollection()` and
100+
``$encryptedFields['fields'][0]['keyId']`` will contain a
101+
:php:`MongoDB\\BSON\\Binary <class.mongodb-bson-binary>` object with subtype 4
102+
(i.e. UUID).
113103

114104
See Also
115105
--------

src/Database.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -324,7 +324,7 @@ public function createCollection(string $collectionName, array $options = [])
324324
* @throws InvalidArgumentException for parameter/option parsing errors
325325
* @throws CreateEncryptedCollectionException for errors generating data keys or invoking createCollection
326326
*/
327-
public function createEncryptedCollection(string $collectionName, ClientEncryption $clientEncryption, string $kmsProvider, ?array $masterKey, array $options = []): array
327+
public function createEncryptedCollection(string $collectionName, ClientEncryption $clientEncryption, string $kmsProvider, ?array $masterKey, array $options): array
328328
{
329329
if (! isset($options['encryptedFields']) || ! is_array($options['encryptedFields']) && ! is_object($options['encryptedFields'])) {
330330
throw InvalidArgumentException::invalidType('"encryptedFields" option', $options['encryptedFields'] ?? null, 'array or object');

0 commit comments

Comments
 (0)