Signatur
Beschreibung
MongoDB\Driver\ServerApi ist Teil der MongoDB PHP Extension (ext-mongodb) und erlaubt es, eine bestimmte Stable API-Version des MongoDB-Servers zu deklarieren, mit der die Anwendung kommunizieren möchte. Diese Funktion wurde mit MongoDB 5.0 und der Stable API eingeführt.
Durch Angabe einer Server-API-Version stellt MongoDB sicher, dass das Verhalten der verwendeten Datenbankbefehle über Serverversionen hinweg konsistent bleibt. So können Server-Upgrades durchgeführt werden, ohne dass sich das Verhalten von Befehlen für die Anwendung ändert – solange diese sich innerhalb der deklarierten API-Version bewegen.
Das ServerApi-Objekt wird beim Erstellen eines MongoDB\Driver\Manager über die Driver-Optionen übergeben. Optional kann per Parameter festgelegt werden, ob nicht zur API-Version gehörende Befehle strikt abgelehnt werden sollen (strict) und ob veraltete (deprecated) Befehle innerhalb der deklarierten Version Fehler erzeugen sollen (deprecationErrors).
Aktuell ist MongoDB\Driver\ServerApi::V1 die einzige unterstützte API-Version. Der Einsatz dieser Klasse empfiehlt sich vor allem in Produktionsumgebungen, in denen langfristige API-Stabilität und vorhersehbares Verhalten bei Serverupdates wichtig sind.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $version Pflicht | string | Die gewünschte Server-API-Version als String. Verwende die Klassenkonstante MongoDB\Driver\ServerApi::V1 für Version 1. |
|
| $strict | bool|null | null | Wenn true, lehnt der Server alle Befehle ab, die nicht zur deklarierten API-Version gehören. Bei null wird der Serverstandardwert verwendet. |
| $deprecationErrors | bool|null | null | Wenn true, erzeugt der Server Fehler bei Verwendung veralteter (deprecated) Befehle innerhalb der deklarierten API-Version. Bei null wird der Serverstandardwert verwendet. |
Beispiele
Manager mit versionierter Server-API erstellen
<?php
use MongoDB\Driver\Manager;
use MongoDB\Driver\ServerApi;
// Stable API Version 1 ohne strenge Einschränkungen
$serverApi = new ServerApi(ServerApi::V1);
$manager = new Manager(
'mongodb://localhost:27017',
[],
['serverApi' => $serverApi]
);
echo "Verbindung mit Stable API V1 hergestellt.\n";
Strikter Modus mit Fehler bei veralteten Befehlen
<?php
use MongoDB\Driver\Manager;
use MongoDB\Driver\ServerApi;
use MongoDB\Driver\Command;
use MongoDB\Driver\Exception\CommandException;
// Strict-Modus: Nicht-API-konforme Befehle werden abgelehnt
// deprecationErrors: Veraltete Befehle erzeugen Fehler
$serverApi = new ServerApi(ServerApi::V1, true, true);
$manager = new Manager(
'mongodb://localhost:27017',
[],
['serverApi' => $serverApi]
);
try {
// Ein Befehl, der zur Stable API gehört
$command = new Command(['ping' => 1]);
$cursor = $manager->executeCommand('admin', $command);
$result = current($cursor->toArray());
echo "Ping erfolgreich: ok={$result->ok}\n";
} catch (CommandException $e) {
echo "Fehler: " . $e->getMessage() . "\n";
}
// Wichtig · Fallstricke
Servervoraussetzung: Die Stable API (Versioned API) wird erst ab MongoDB 5.0 unterstützt. Bei älteren Serverversionen führt die Angabe einer ServerApi-Instanz zu einem Fehler. Prüfe daher vor dem Einsatz die Serverversion deiner MongoDB-Instanz.
Strict-Modus: Mit strict = true schlägt jeder Befehl fehl, der nicht explizit zur deklarierten API-Version gehört. Dies kann in bestehenden Anwendungen zu unerwarteten CommandException-Fehlern führen, wenn Befehle verwendet werden, die nicht Teil der Stable API sind.
Treiber-Version: ServerApi ist erst ab Version 1.8.0 der MongoDB PHP Extension verfügbar. Stelle sicher, dass die installierte Extension aktuell genug ist (phpinfo() oder php -m | grep mongodb).