Skip to content

Commit 61cfe98

Browse files
jmikolajmikola
committed
Docs for Database::createEncryptedCollection()
1 parent 2c79aee commit 61cfe98

5 files changed

+277
-0
lines changed

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

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
source:
2+
file: apiargs-MongoDBDatabase-method-createCollection-option.yaml
3+
ref: autoIndexId
4+
---
5+
source:
6+
file: apiargs-MongoDBDatabase-method-createCollection-option.yaml
7+
ref: capped
8+
---
9+
source:
10+
file: apiargs-MongoDBDatabase-method-createCollection-option.yaml
11+
ref: changeStreamPreAndPostImages
12+
---
13+
source:
14+
file: apiargs-MongoDBDatabase-method-createCollection-option.yaml
15+
ref: clusteredIndex
16+
---
17+
source:
18+
file: apiargs-MongoDBDatabase-method-createCollection-option.yaml
19+
ref: collation
20+
---
21+
source:
22+
file: apiargs-MongoDBDatabase-method-createCollection-option.yaml
23+
ref: comment
24+
---
25+
source:
26+
file: apiargs-MongoDBDatabase-method-createCollection-option.yaml
27+
ref: encryptedFields
28+
optional: false
29+
---
30+
source:
31+
file: apiargs-MongoDBDatabase-method-createCollection-option.yaml
32+
ref: expireAfterSeconds
33+
---
34+
source:
35+
file: apiargs-MongoDBDatabase-method-createCollection-option.yaml
36+
ref: flags
37+
---
38+
source:
39+
file: apiargs-MongoDBDatabase-method-createCollection-option.yaml
40+
ref: indexOptionDefaults
41+
---
42+
source:
43+
file: apiargs-MongoDBDatabase-method-createCollection-option.yaml
44+
ref: max
45+
---
46+
source:
47+
file: apiargs-MongoDBDatabase-method-createCollection-option.yaml
48+
ref: maxTimeMS
49+
---
50+
source:
51+
file: apiargs-MongoDBDatabase-method-createCollection-option.yaml
52+
ref: pipeline
53+
---
54+
source:
55+
file: apiargs-MongoDBDatabase-method-createCollection-option.yaml
56+
ref: session
57+
---
58+
source:
59+
file: apiargs-MongoDBDatabase-method-createCollection-option.yaml
60+
ref: size
61+
---
62+
source:
63+
file: apiargs-MongoDBDatabase-method-createCollection-option.yaml
64+
ref: storageEngine
65+
---
66+
source:
67+
file: apiargs-MongoDBDatabase-method-createCollection-option.yaml
68+
ref: timeseries
69+
---
70+
source:
71+
file: apiargs-MongoDBDatabase-method-createCollection-option.yaml
72+
ref: typeMap
73+
---
74+
source:
75+
file: apiargs-MongoDBDatabase-method-createCollection-option.yaml
76+
ref: validator
77+
---
78+
source:
79+
file: apiargs-MongoDBDatabase-method-createCollection-option.yaml
80+
ref: validationAction
81+
---
82+
source:
83+
file: apiargs-MongoDBDatabase-method-createCollection-option.yaml
84+
ref: validationLevel
85+
---
86+
source:
87+
file: apiargs-MongoDBDatabase-method-createCollection-option.yaml
88+
ref: viewOn
89+
---
90+
source:
91+
file: apiargs-MongoDBDatabase-method-createCollection-option.yaml
92+
ref: writeConcern
93+
...

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

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
source:
2+
file: apiargs-common-param.yaml
3+
ref: $collectionName
4+
replacement:
5+
subject: "encrypted collection"
6+
action: " to create"
7+
---
8+
arg_name: param
9+
name: $clientEncryption
10+
type: :php:`MongoDB\\Driver\\ClientEncryption <mongodb-driver-clientencryption>`
11+
description: |
12+
The ClientEncryption object used to create data keys.
13+
interface: phpmethod
14+
operation: ~
15+
optional: false
16+
---
17+
arg_name: param
18+
name: $kmsProvider
19+
type: string
20+
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
23+
:php:`MongoDB\\Driver\\ClientEncryption::createDataKey() <mongodb-driver-clientencryption.createdatakey>`.
24+
interface: phpmethod
25+
operation: ~
26+
optional: false
27+
---
28+
arg_name: param
29+
name: $masterKey
30+
type: array|null
31+
description: |
32+
KMS-specific key options that will be used to encrypt new encryption keys.
33+
This corresponds to the ``$masterKey`` parameter for
34+
:php:`MongoDB\\Driver\\ClientEncryption::createDataKey() <mongodb-driver-clientencryption.createdatakey>`.
35+
36+
If ``$kmsProvider`` is "local", this parameter should be ``null``.
37+
interface: phpmethod
38+
operation: ~
39+
optional: false
40+
---
41+
source:
42+
file: apiargs-common-param.yaml
43+
ref: $options
44+
post: |
45+
The ``encryptedFields`` option is required.
46+
...

‎docs/reference/class/MongoDBDatabase.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ Methods
4848
/reference/method/MongoDBDatabase-aggregate
4949
/reference/method/MongoDBDatabase-command
5050
/reference/method/MongoDBDatabase-createCollection
51+
/reference/method/MongoDBDatabase-createEncryptedCollection
5152
/reference/method/MongoDBDatabase-drop
5253
/reference/method/MongoDBDatabase-dropCollection
5354
/reference/method/MongoDBDatabase-getDatabaseName

‎docs/reference/exception-classes.txt

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,22 @@ MongoDB\\Exception\\BadMethodCallException
3030

3131
----
3232

33+
MongoDB\\Exception\\CreateEncryptedCollectionException
34+
------------------------------------------------------
35+
36+
.. phpclass:: MongoDB\\Exception\\CreateEncryptedCollectionException
37+
38+
Thrown by :phpmethod:`MongoDB\\Database::createEncryptedCollection()` if any
39+
error is encountered while creating data keys or invoking
40+
``createCollection()``. The original exception and modified
41+
``encryptedFields`` option can be accessed via ``getPrevious()`` and
42+
``getEncryptedFields()``, respectively.
43+
44+
This class extends the library's :phpclass:`RuntimeException
45+
<MongoDB\\Exception\\RuntimeException>` class.
46+
47+
----
48+
3349
MongoDB\\Exception\\InvalidArgumentException
3450
--------------------------------------------
3551

‎docs/reference/method/MongoDBDatabase-createEncryptedCollection.txt

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
==============================================
2+
MongoDB\\Database::createEncryptedCollection()
3+
==============================================
4+
5+
.. versionadded:: 1.16
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
Definition
16+
----------
17+
18+
.. phpmethod:: MongoDB\\Database::createEncryptedCollection()
19+
20+
Explicitly creates an encrypted collection.
21+
22+
.. code-block:: php
23+
24+
function createEncryptedCollection(string $collectionName, ClientEncryption $clientEncryption, string $kmsProvider, ?array $masterKey, array $options = []): array
25+
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
32+
:php:`MongoDB\\Driver\\ClientEncryption::createDataKey() <mongodb-driver-clientencryption.createdatakey>`
33+
and the provided ``$kmsProvider`` and ``$masterKey`` parameters.
34+
35+
This method does not affect any auto encryption settings on existing
36+
:phpclass:`MongoDB\\Client` objects. Users must configure auto encryption
37+
after creating the encrypted collection with ``createEncryptedCollection()``.
38+
39+
This method has the following parameters:
40+
41+
.. include:: /includes/apiargs/MongoDBDatabase-method-createEncryptedCollection-param.rst
42+
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.
50+
51+
Return Values
52+
-------------
53+
54+
A tuple consisting of the result from
55+
:phpmethod:`MongoDB\\Database::createCollection()` and the modified
56+
``encryptedFields`` option.
57+
58+
Errors/Exceptions
59+
-----------------
60+
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.
66+
67+
.. include:: /includes/extracts/error-invalidargumentexception.rst
68+
69+
Example
70+
-------
71+
72+
The following example creates an encrypted ``users`` collection in the ``test``
73+
database. The ``ssn`` field within the ``users`` collection will be defined as
74+
an encrypted string field.
75+
76+
.. code-block:: php
77+
78+
<?php
79+
80+
// 96-byte master key used to encrypt/decrypt data keys
81+
define('LOCAL_MASTERKEY', '...');
82+
83+
$client = new MongoDB\Client;
84+
85+
$clientEncryption = $client->createClientEncryption([
86+
'keyVaultNamespace' => 'keyvault.datakeys',
87+
'kmsProviders' => [
88+
'local' => ['key' => new MongoDB\BSON\Binary(base64_decode(LOCAL_MASTERKEY), 0)],
89+
],
90+
);
91+
92+
[$result, $encryptedFields] = $client->test->createEncryptedCollection(
93+
'users',
94+
$clientEncryption,
95+
'local',
96+
null,
97+
[
98+
'encryptedFields' => [
99+
'fields' => [
100+
['path' => 'ssn', 'bsonType' => 'string', 'keyId' => null],
101+
],
102+
],
103+
]
104+
);
105+
106+
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).
113+
114+
See Also
115+
--------
116+
117+
- :phpmethod:`MongoDB\\Database::createCollection()`
118+
- :phpmethod:`MongoDB\\Client::createClientEncryption()`
119+
- :php:`MongoDB\\Driver\\ClientEncryption::createDataKey() <mongodb-driver-clientencryption.createdatakey>`
120+
- :manual:`create </reference/command/create>` command reference in the MongoDB
121+
manual

0 commit comments

Comments
 (0)