Create a new ReadPreference

- « MongoDB\Driver\ReadPreference::bsonSerialize

- MongoDB\Driver\ReadPreference::getHedge »

- PHP Manual
- MongoDB\Driver\ReadPreference
- Create a new ReadPreference

# MongoDB\Driver\ReadPreference::__construct

(mongodb >=1.0.0)

MongoDB\Driver\ReadPreference::__construct — Create a new ReadPreference

### Description

final public MongoDB\Driver\ReadPreference::__construct(string|int `$mode`, ?array `$tagSets` = `null`, ?array `$options` = `null`)

Constructs a new MongoDB\Driver\ReadPreference, which is an immutable value object.

### Parameters

`mode`

  Read preference mode
  Value | Description
  --- | ---
  `MongoDB\Driver\ReadPreference::RP_PRIMARY` or `"primary"` | All operations read from the current replica set primary. This is the default read preference for MongoDB.
  `MongoDB\Driver\ReadPreference::RP_PRIMARY_PREFERRED` or `"primaryPreferred"` | In most situations, operations read from the primary but if it is unavailable, operations read from secondary members.
  `MongoDB\Driver\ReadPreference::RP_SECONDARY` or `"secondary"` | All operations read from the secondary members of the replica set.
  `MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED` or `"secondaryPreferred"` | In most situations, operations read from secondary members but if no secondary members are available, operations read from the primary.
  `MongoDB\Driver\ReadPreference::RP_NEAREST` or `"nearest"` | Operations read from member of the replica set with the least network latency, irrespective of the member's type.

`tagSets`

  Tag sets allow you to target read operations to specific members of a replica set. This parameter should be an array of associative arrays, each of which contain zero or more key/value pairs. When selecting a server for a read operation, the driver attempt to select a node having all tags in a set (i.e. the associative array of key/value pairs). If selection fails, the driver will attempt subsequent sets. An empty tag set (`array()`) will match any node and may be used as a fallback.

  Tags are not compatible with the `MongoDB\Driver\ReadPreference::RP_PRIMARY` mode and, in general, only apply when selecting a secondary member of a set for a read operation. However, the `MongoDB\Driver\ReadPreference::RP_NEAREST` mode, when combined with a tag set, selects the matching member with the lowest network latency. This member may be a primary or secondary.

`options`

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

  hedge

  object|array

  Specifies whether to use » hedged reads, which are supported by MongoDB 4.4+ for sharded queries.

  Server hedged reads are available for all non-primary read preferences and are enabled by default when using the `"nearest"` mode. This option allows explicitly enabling server hedged reads for non-primary read preferences by specifying `['enabled' => true]`, or explicitly disabling server hedged reads for the `"nearest"` read preference by specifying `['enabled' => false]`.

  maxStalenessSeconds

  int

  Specifies a maximum replication lag, or "staleness", for reads from secondaries. When a secondary's estimated staleness exceeds this value, the driver stops using it for read operations.

  If specified, the max staleness must be a signed 32-bit integer greater than or equal to `MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS`.

  Defaults to `MongoDB\Driver\ReadPreference::NO_MAX_STALENESS`, which means that the driver will not consider a secondary's lag when choosing where to direct a read operation.

  This option is not compatible with the `MongoDB\Driver\ReadPreference::RP_PRIMARY` mode. Specifying a max staleness also requires all MongoDB instances in the deployment to be using MongoDB 3.4+. An exception will be thrown at execution time if any MongoDB instances in the deployment are of an older server version.

### Errors/Exceptions

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if `mode` is invalid.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if `tagSets` is provided for a primary read preference or is malformed (i.e. not an array of zero or more documents).
- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"maxStalenessSeconds"` option is provided for a primary read preference or is out of range.

### Changelog

Version | Description
--- | ---
PECL mongodb 1.8.0 | Added the `"hedge"` option.
PECL mongodb 1.3.0 | The `mode` argument now accepts a string value, which is consistent with the `"readPreference"` URI option for MongoDB\Driver\Manager::__construct().
PECL mongodb 1.2.0 | Added a third `options` argument, which supports the `"maxStalenessSeconds"` option.

### Examples

Example #1 MongoDB\Driver\ReadPreference::__construct() example

    <?php/* Prefer a secondary node but fall back to a primary. */var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED));/* Prefer a node in the New York data center with lowest latency. */var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_NEAREST, [['dc' => 'ny']]));/* Require a secondary node whose replication lag is within two minutes of the primary */var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY, null, ['maxStalenessSeconds' => 120]));/* Explicitly enable server hedged reads */var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY, null, ['hedge' => ['enabled' => true]]));?>

The above example will output:

    object(MongoDB\Driver\ReadPreference)#1 (1) {
      ["mode"]=>
      string(18) "secondaryPreferred"
    }
    object(MongoDB\Driver\ReadPreference)#1 (2) {
      ["mode"]=>
      string(7) "nearest"
      ["tags"]=>
      array(1) {
        [0]=>
        object(stdClass)#2 (1) {
          ["dc"]=>
          string(2) "ny"
        }
      }
    }
    object(MongoDB\Driver\ReadPreference)#1 (2) {
      ["mode"]=>
      string(9) "secondary"
      ["maxStalenessSeconds"]=>
      int(120)
    }
    object(MongoDB\Driver\ReadPreference)#1 (2) {
      ["mode"]=>
      string(9) "secondary"
      ["hedge"]=>
      object(stdClass)#1 (1) {
        ["enabled"]=>
        bool(true)
      }
    }

### See Also

- » Read Preference reference