Create a new ReadPreference

# MongoDB\Driver\ReadPreference::__construct

(mongodb >=1.0.0)

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

### 説明

final public MongoDB\Driver\ReadPreference::__construct ( string|integer `$mode` [, array `$tagSets` = `NULL` [, array `$options` = array() ]] )

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

### パラメータ

`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
  --- | --- | ---
  maxStalenessSeconds | integer | 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.

### エラー / 例外

- 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
- 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.

### 変更履歴

バージョン | 説明
--- | ---
1.3.0 | The `mode` argument now accepts a string value, which is consistent with the "readPreference" URI option for MongoDB\Driver\Manager::__construct().
1.2.0 | Added a third `options` argument, which supports the "maxStalenessSeconds" option.

### 例

例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]));
?>`

上の例の出力は以下となります。

    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)
    }

### 参考

- » Read Preference reference