Encrypts a match or aggregate expression

- « MongoDB\Driver\ClientEncryption::encrypt

- MongoDB\Driver\ClientEncryption::getKey »

- PHP Manual
- MongoDB\Driver\ClientEncryption
- Encrypts a match or aggregate expression

# MongoDB\Driver\ClientEncryption::encryptExpression

(mongodb >=1.16.0)

MongoDB\Driver\ClientEncryption::encryptExpression — Encrypts a match or aggregate expression

### Description

final public MongoDB\Driver\ClientEncryption::encryptExpression(array|object `$expr`, ?array `$options` = `null`): object

Encrypts a match or aggregate expression to query a range index.

To query with a range encrypted payload, the MongoDB\Driver\Manager must be configured with the `"autoEncryption"` driver option. The `"bypassQueryAnalysis"` auto encryption option may be `true`. The `"bypassAutoEncryption"` auto encryption option must be `false`.

> Note:

> The range algorithm is experimental only. It is not intended for public use.

> The PHP driver does not yet support range queries for decimal128 BSON field types.

### Parameters

`expr`

  The match or aggregate expression to be encrypted. Expressions must use at least one of the `$gt`, `$gte`, `$lt`, or `$lte` operators. A top-level `$and` operator is required, even if only a single comparison operator is used.

  An example of a supported match expression (applies to queries and the `$match` aggregation stage) is as follows:

      [
          '$and' => [
              [ '<field>' => [ '$gt'  => '<value1>' ] ],
              [ '<field>' => [ '$lte' => '<value2>' ] ],
          ],
      ]

  An example of a supported aggregate expression is as follows:

      [
          '$and' => [
              [ '$gte' => [ '<fieldPath>', '<value1>' ] ],
              [ '$lt'  => [ '<fieldPath>', '<value2>' ] ],
          ],
      ]

`options`

  Encryption options
  Option | Type | Description
  --- | --- | ---

  algorithm

  string

  The encryption algorithm to be used. This option is required. Specify one of the following ClientEncryption constants:
  - `MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC`
  - `MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM`
  - `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED`
  - `MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED`
  - `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW`

  contentionFactor | int | The contention factor for evaluating queries with indexed, encrypted payloads. This option only applies and may only be specified when `algorithm` is `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` or `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW`.
  keyAltName | string | Identifies a key vault collection document by `keyAltName`. This option is mutually exclusive with `keyId` and exactly one is required.
  keyId | MongoDB\BSON\Binary | Identifies a data key by `_id`. The value is a UUID (binary subtype 4). This option is mutually exclusive with `keyAltName` and exactly one is required.

  queryType

  int

  The query type for evaluating queries with indexed, encrypted payloads. Specify one of the following ClientEncryption constants:
  - `MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY`
  - `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE_PREVIEW`

  This option only applies and may only be specified when `algorithm` is `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` or `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW`.

  rangeOpts

  array

  Index options for a queryable encryption field supporting "rangePreview" queries. The options below must match the values set in the `encryptedFields` of the target collection. For double and decimal128 BSON field types, `min`, `max`, and `precision` must all be set, or all be unset.

  Range index options
  Option | Type | Description
  --- | --- | ---
  min | mixed | Required if `precision` is set.
  max | mixed | Required if `precision` is set.
  sparsity | int | Required.
  precision | int | Optional. May only be set for double or decimal128 BSON field types.

### Return Values

Returns the encrypted expression as an object.

### Errors/Exceptions

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\EncryptionException if an error occurs while encrypting the expression

### See Also

- MongoDB\Driver\Manager::__construct() - Create new MongoDB Manager