Reference >
MongoDB\Database Class >
MongoDB\Database::createEncryptedCollection()

MongoDB\Database::createEncryptedCollection()

New in version 1.16.

On this page

Definition
Return Values
Errors/Exceptions
Example
See Also

Definition

MongoDB\Database::createEncryptedCollection

Explicitly creates an encrypted collection.

function createEncryptedCollection(string $collectionName, MongoDB\Driver\ClientEncryption $clientEncryption, string $kmsProvider, ?array $masterKey, array $options): array

This method will automatically create data keys for any encrypted fields where keyId is null. Data keys will be created using MongoDB\Driver\ClientEncryption::createDataKey() and the provided $kmsProvider and $masterKey parameters. A copy of the modified encryptedFields option will be returned in addition to the result from creating the collection.

This method does not affect any auto encryption settings on existing MongoDB\Client objects. Users must configure auto encryption after creating the encrypted collection with createEncryptedCollection().

This method has the following parameters:

Parameter	Type	Description
`$collectionName`	string	The name of the encrypted collection to create.
`$clientEncryption`	MongoDB\Driver\ClientEncryption	The ClientEncryption object used to create data keys.
`$kmsProvider`	string	KMS provider (e.g. “local”, “aws”) that will be used to encrypt new data keys. This corresponds to the `$kmsProvider` parameter for MongoDB\Driver\ClientEncryption::createDataKey().
`$masterKey`	array\|null	KMS-specific key options that will be used to encrypt new data keys. This corresponds to the `masterKey` option for MongoDB\Driver\ClientEncryption::createDataKey(). If `$kmsProvider` is “local”, this should be `null`.
`$options`	array	An array specifying the desired options. The `encryptedFields` option is required.

The $options parameter supports the same options as MongoDB\Database::createCollection(). The encryptedFields option is required.

Return Values

A tuple (i.e. two-element array) containing the result document from the create command (an array or object according to the typeMap option) and the modified encryptedFields option.

Errors/Exceptions

MongoDB\Exception\CreateEncryptedCollectionException if any error is encountered creating data keys or the collection. The original exception and modified encryptedFields option can be accessed via the getPrevious() and getEncryptedFields() methods, respectively.

MongoDB\Exception\InvalidArgumentException for errors related to the parsing of parameters or options.

Example

The following example creates an encrypted users collection in the test database. The ssn field within the users collection will be defined as an encrypted string field.

copy

<?php

// 96-byte master key used to encrypt/decrypt data keys
define('LOCAL_MASTERKEY', '...');

$client = new MongoDB\Client;

$clientEncryption = $client->createClientEncryption([
    'keyVaultNamespace' => 'keyvault.datakeys',
    'kmsProviders' => [
        'local' => ['key' => new MongoDB\BSON\Binary(base64_decode(LOCAL_MASTERKEY), 0)],
     ],
);

[$result, $encryptedFields] = $client->test->createEncryptedCollection(
    'users',
    $clientEncryption,
    'local',
    null,
    [
        'encryptedFields' => [
            'fields' => [
                ['path' => 'ssn', 'bsonType' => 'string', 'keyId' => null],
            ],
        ],
    ]
);

If the encrypted collection was successfully created, $result will contain the response document from the create command and $encryptedFields['fields'][0]['keyId'] will contain a MongoDB\BSON\Binary object with subtype 4 (i.e. UUID).

The modified encryptedFields option can then be used to construct a new MongoDB\Client with auto encryption enabled.