mysql_xdevapi\Exception — Klasse · PHP-Referenz

Signatur

class mysql_xdevapi\Exception extends RuntimeException

Beschreibung

mysql_xdevapi\Exception ist die gemeinsame Basisklasse aller Ausnahmen, die von der mysql_xdevapi-Erweiterung geworfen werden. Sie erweitert RuntimeException aus dem SPL und steht damit in der regulären PHP-Ausnahmenhierarchie. Fehler, die beim Verbindungsaufbau, bei der Ausführung von Abfragen oder beim Umgang mit Transaktionen über das X DevAPI-Protokoll auftreten, werden als Instanzen dieser Klasse (oder einer abgeleiteten Klasse) ausgelöst.

Da alle X-DevAPI-spezifischen Ausnahmen von dieser Klasse erben, reicht ein einzelner catch(mysql_xdevapi\Exception $e)-Block, um sämtliche erweiterungsspezifischen Fehler abzufangen. Darüber hinaus können diese Ausnahmen auch mit einem allgemeinen catch(\Exception $e) oder catch(\RuntimeException $e) behandelt werden.

Die Klasse stellt die üblichen Methoden von RuntimeException zur Verfügung: getMessage() liefert eine lesbare Fehlermeldung, getCode() gibt den numerischen Fehlercode zurück, und getTrace() bzw. getTraceAsString() ermöglichen die Analyse des Call-Stacks. Dies erleichtert die Fehlersuche bei datenbankbezogenen Problemen erheblich.

Die mysql_xdevapi-Erweiterung bietet eine moderne, objektorientierte Schnittstelle zu MySQL 8.0+ und nutzt das X-Protokoll. Sie ist ein Ersatz für die älteren mysql- und mysqli-Erweiterungen, wenn das X DevAPI-Protokoll benötigt wird.

Beispiele

Verbindungsfehler mit mysql_xdevapi\Exception abfangen

<?php
use mysql_xdevapi\Exception as XDevApiException;

try {
    // Verbindungsversuch zu einem nicht erreichbaren MySQL-Server
    $session = mysql_xdevapi\getSession('mysqlx://root:geheim@localhost:33060');
    $schema  = $session->getSchema('meine_datenbank');
    $table   = $schema->getTable('kunden');
    $result  = $table->select('id', 'name')->execute();

    foreach ($result->fetchAll() as $row) {
        echo $row['name'] . PHP_EOL;
    }
} catch (XDevApiException $e) {
    // Spezifische X DevAPI-Fehler behandeln
    echo 'X DevAPI-Fehler [' . $e->getCode() . ']: ' . $e->getMessage() . PHP_EOL;
} catch (\Exception $e) {
    // Alle anderen Ausnahmen auffangen
    echo 'Allgemeiner Fehler: ' . $e->getMessage() . PHP_EOL;
}

X DevAPI-Fehler [2006]: MySQL server has gone away

Transaktionsfehler sicher behandeln

<?php
use mysql_xdevapi\Exception as XDevApiException;

function bestellungSpeichern(\mysql_xdevapi\Session $session, array $daten): void {
    $session->startTransaction();
    try {
        $schema = $session->getSchema('shop');

        $schema->getTable('bestellungen')
               ->insert('kunden_id', 'betrag')
               ->values($daten['kunden_id'], $daten['betrag'])
               ->execute();

        $schema->getTable('lager')
               ->update()
               ->set('bestand', 'bestand - 1')
               ->where('artikel_id = :id')
               ->bind(['id' => $daten['artikel_id']])
               ->execute();

        $session->commit();
        echo 'Bestellung erfolgreich gespeichert.' . PHP_EOL;
    } catch (XDevApiException $e) {
        $session->rollback();
        echo 'Datenbankfehler, Transaktion zurückgerollt: ' . $e->getMessage() . PHP_EOL;
        throw $e; // Optional: Ausnahme weiterwerfen
    }
}

try {
    $session = mysql_xdevapi\getSession('mysqlx://root:geheim@localhost:33060');
    bestellungSpeichern($session, [
        'kunden_id'  => 42,
        'betrag'     => 99.95,
        'artikel_id' => 7,
    ]);
} catch (XDevApiException $e) {
    echo 'Fehlercode: ' . $e->getCode() . PHP_EOL;
    echo 'Stack Trace:' . PHP_EOL . $e->getTraceAsString() . PHP_EOL;
}

Bestellung erfolgreich gespeichert.

// Wichtig · Fallstricke

Erweiterungsverfügbarkeit: Die mysql_xdevapi-Erweiterung ist nicht in der PHP-Standardinstallation enthalten und muss separat über PECL installiert werden (pecl install mysql_xdevapi). Außerdem ist MySQL 8.0+ mit aktiviertem X-Plugin (mysqlx auf Port 33060) erforderlich.

Fehlerbehandlung: Da alle X-DevAPI-Ausnahmen von mysql_xdevapi\Exception erben, sollte dieser Typ im catch-Block bevorzugt werden, um erweiterungsspezifische Fehler von allgemeinen PHP-Ausnahmen zu trennen. Ein versehentliches Verschlucken von Ausnahmen durch zu breite catch(\Exception $e)-Blöcke sollte vermieden werden.

Sicherheit: Fehlermeldungen aus getMessage() können interne Datenbankstrukturen, Tabellennamen oder Verbindungsdetails enthalten. Diese sollten in Produktivumgebungen niemals direkt an den Endnutzer weitergegeben werden.

Siehe auch

mysql_xdevapi\getSession mysql_xdevapi\Session RuntimeException Exception