Signatur
Beschreibung
MongoDB\Driver\ReadPreference gehört zur offiziellen MongoDB-PHP-Extension (ext-mongodb) und kapselt die Einstellungen, die bestimmen, von welchem Server in einem Replica-Set oder Sharded-Cluster Leseanfragen beantwortet werden sollen. Sie wird beim Erstellen von Queries, Aggregationen oder beim Erstellen von MongoDB\Driver\Manager- und MongoDB\Driver\Session-Objekten verwendet.
Mögliche Modi sind: ReadPreference::PRIMARY (nur der Primary), PRIMARY_PREFERRED, SECONDARY, SECONDARY_PREFERRED und NEAREST. Mit Tag-Sets lässt sich die Serverauswahl weiter verfeinern, etwa um geografisch nahe oder spezialisierte Secondaries zu bevorzugen.
Der optionale Parameter $maxStalenessSeconds begrenzt, wie weit ein Secondary hinter dem Primary zurückliegen darf, bevor er nicht mehr für Lesevorgänge in Betracht gezogen wird. Dieser Wert muss mindestens 90 Sekunden betragen oder -1 (deaktiviert) sein.
Die Klasse ist unveränderlich (immutable): Nach dem Erstellen können keine Eigenschaften geändert werden. Sie implementiert MongoDB\BSON\Serializable und kann in eine BSON-Darstellung umgewandelt werden, was die Kompatibilität mit Treiber-internen Vorgängen sicherstellt.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $mode Pflicht | string|int | Der Lesepräferenz-Modus. Gültige Werte sind die Klassenkonstanten ReadPreference::PRIMARY, ReadPreference::PRIMARY_PREFERRED, ReadPreference::SECONDARY, ReadPreference::SECONDARY_PREFERRED und ReadPreference::NEAREST. Ab PHP-Extension-Version 1.10 können auch die entsprechenden String-Werte ('primary' etc.) übergeben werden. |
|
| $tagSets | array|null | null | Ein Array von Tag-Set-Dokumenten, das die Serverauswahl weiter einschränkt. Jedes Element ist ein assoziatives Array wie ['dc' => 'east', 'use' => 'reporting']. Ein leeres Array [] entfernt alle Tag-Einschränkungen. Nicht erlaubt im Modus PRIMARY. |
| $options | array|null | null | Assoziatives Array mit weiteren Optionen. Unterstützt wird derzeit 'maxStalenessSeconds' (int, mindestens 90 oder -1), das die maximale Replikationsverzögerung in Sekunden angibt, die ein Secondary haben darf. Nicht erlaubt im Modus PRIMARY. |
Rückgabewert
Beispiele
Lesen von einem Secondary bevorzugen
<?php
use MongoDB\Driver\ReadPreference;
use MongoDB\Driver\Manager;
use MongoDB\Driver\Query;
$readPref = new ReadPreference(ReadPreference::SECONDARY_PREFERRED);
$manager = new Manager('mongodb://rs1.example.com,rs2.example.com/?replicaSet=myRS');
$query = new Query(['status' => 'active']);
$cursor = $manager->executeQuery('mydb.users', $query, ['readPreference' => $readPref]);
foreach ($cursor as $document) {
var_dump($document->name);
}Tag-Set und maxStalenessSeconds verwenden
<?php
use MongoDB\Driver\ReadPreference;
// Nur Secondaries im Rechenzentrum 'east' wählen,
// die maximal 120 Sekunden hinter dem Primary zurückliegen
$readPref = new ReadPreference(
ReadPreference::SECONDARY,
[['dc' => 'east']],
['maxStalenessSeconds' => 120]
);
echo $readPref->getMode(); // 2 (SECONDARY)
var_dump($readPref->getTagSets()); // array(1) { ... }
echo $readPref->getMaxStalenessSeconds(); // 120ReadPreference serialisieren (BSON-Debug)
<?php
use MongoDB\Driver\ReadPreference;
$readPref = new ReadPreference(ReadPreference::NEAREST);
$bson = $readPref->bsonSerialize();
var_dump($bson->mode); // 'nearest'// Wichtig · Fallstricke
Modus PRIMARY und Tag-Sets: Wenn PRIMARY als Modus gesetzt ist, dürfen keine Tag-Sets oder maxStalenessSeconds übergeben werden – andernfalls wird eine MongoDB\Driver\Exception\InvalidArgumentException ausgelöst.
maxStalenessSeconds: Der minimale erlaubte Wert ist 90 Sekunden (da kleinere Werte die Serverauswahl unzuverlässig machen würden). Bei älteren MongoDB-Servern (vor 3.4) wird diese Option ignoriert.
Replica-Set-Anforderung: Die Modi SECONDARY, SECONDARY_PREFERRED und PRIMARY_PREFERRED sind nur in Replica-Set- und Sharded-Cluster-Topologien sinnvoll. Bei einer Standalone-Verbindung wird stets der einzelne Server verwendet, unabhängig vom Modus.
Lesekonsistenz: Das Lesen von Secondaries kann veraltete Daten liefern (eventual consistency). Für kritische Lesevorgänge (z. B. nach einem Schreibvorgang) sollte PRIMARY oder PRIMARY_PREFERRED in Kombination mit einem passenden ReadConcern verwendet werden.