Signatur
Beschreibung
getSession() ist die zentrale Funktion des MySQL X DevAPI (über die PHP-Erweiterung mysql_xdevapi) und stellt eine Verbindung zu einem MySQL-Server über das X Protocol her. Sie gibt ein MySQL\Session-Objekt zurück, mit dem Datenbankoperationen ausgeführt werden können.
Die Verbindung wird über einen URI-String spezifiziert, der Benutzername, Passwort, Hostname, Port und Datenbankname enthalten kann. Das X Protocol verwendet standardmäßig Port 33060 statt des klassischen MySQL-Ports 3306. Im Gegensatz zur klassischen mysqli- oder PDO-Verbindung unterstützt die X DevAPI auch dokumentenorientierte Zugriffsmuster (NoSQL-ähnlich) neben SQL.
Über das optionale options-Array können zusätzliche Verbindungsparameter wie SSL/TLS-Einstellungen oder Verbindungs-Timeouts übergeben werden. Die Session-Objekte sind zustandsbehaftet und sollten nach Verwendung ordnungsgemäß geschlossen werden.
Diese Funktion eignet sich besonders für Anwendungen, die die modernen Features von MySQL 8+ (z. B. JSON-Dokument-Stores, asynchrone Abfragen) nutzen möchten und die X DevAPI einsetzen wollen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $uri Pflicht | string | Verbindungs-URI im Format mysqlx://benutzer:passwort@host:port/datenbankname. Der Standardport für das X Protocol ist 33060. |
|
| $options | array | [] | Optionales Array mit zusätzlichen Verbindungsoptionen, z. B. SSL/TLS-Konfiguration (ssl-ca, ssl-cert, ssl-key) oder Authentifizierungsparameter. |
Rückgabewert
MySQL\Session-Objekt zurück, über das SQL-Abfragen und X DevAPI-Operationen ausgeführt werden können. Bei einem Verbindungsfehler wird eine Exception geworfen.Beispiele
Einfache Verbindung zu einem MySQL-Server
<?php
// Verbindung über X DevAPI herstellen
$uri = 'mysqlx://root:geheimesPasswort@localhost:33060/meineDatenbank';
try {
$session = getSession($uri);
echo "Verbindung erfolgreich hergestellt!\n";
// SQL-Abfrage ausführen
$result = $session->sql('SELECT VERSION() AS version')->execute();
$row = $result->fetchOne();
echo "MySQL-Version: " . $row['version'] . "\n";
// Session schließen
$session->close();
} catch (Exception $e) {
echo "Fehler: " . $e->getMessage() . "\n";
}Verbindung mit SSL und Dokumenten-Store
<?php
// Verbindung mit SSL-Optionen
$uri = 'mysqlx://dbuser:sicheresPasswort@db.example.com:33060/shopDB';
$options = [
'ssl-ca' => '/etc/ssl/certs/ca-cert.pem',
'ssl-cert' => '/etc/ssl/certs/client-cert.pem',
'ssl-key' => '/etc/ssl/private/client-key.pem',
];
try {
$session = getSession($uri, $options);
// Zugriff auf einen JSON-Dokument-Store (Collection)
$schema = $session->getSchema('shopDB');
$collection = $schema->getCollection('produkte');
// Dokument einfügen
$collection->add(['name' => 'Laptop', 'preis' => 999.99])->execute();
echo "Dokument erfolgreich hinzugefügt.\n";
// Dokumente suchen
$docs = $collection->find('preis > 500')->execute();
foreach ($docs->fetchAll() as $doc) {
echo $doc['name'] . ': ' . $doc['preis'] . ' EUR\n';
}
$session->close();
} catch (Exception $e) {
echo "Fehler: " . $e->getMessage() . "\n";
}// Wichtig · Fallstricke
Sicherheit: Vermeiden Sie es, Zugangsdaten direkt im Quellcode zu hinterlegen. Nutzen Sie Umgebungsvariablen oder Konfigurationsdateien außerhalb des Webroot-Verzeichnisses, um sensible Verbindungsdaten zu schützen.
X Protocol: Diese Funktion gehört zur Erweiterung mysql_xdevapi und kommuniziert über das MySQL X Protocol (Port 33060). Sie ist nicht Teil von mysqli oder PDO. Stellen Sie sicher, dass die Erweiterung in der php.ini geladen ist (extension=mysql_xdevapi) und MySQL 5.7.12+ bzw. MySQL 8 mit aktiviertem X Plugin läuft.
Fehlerbehandlung: Bei fehlgeschlagener Verbindung wirft getSession() eine Exception. Umschließen Sie Aufrufe stets mit einem try/catch-Block.