Docs Menu
Docs Home
/ / /
PHP Library Manual
/ /


On this page

  • Definition
  • Parameters
  • Return Values
  • Errors/Exceptions
  • Example
  • See Also

New in version 1.16.


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().

$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 $options parameter supports the same options as MongoDB\Database::createCollection(). The encryptedFields option is required.

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.

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.

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.

// 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(
'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.

$encryptedClient = new MongoDB\Client(
null, // Connection string
[], // Additional connection string options
'autoEncryption' => [
'keyVaultNamespace' => 'keyvault.datakeys',
'kmsProviders' => [
'local' => ['key' => new MongoDB\BSON\Binary(base64_decode(LOCAL_MASTERKEY), 0)],
'encryptedFieldsMap' => [
'test.users' => $encryptedFields,