com_exception — Klasse · PHP-Referenz

Signatur

class com_exception extends Exception

Beschreibung

com_exception ist die spezifische Ausnahmeklasse der PHP-COM-Erweiterung (Component Object Model). Sie wird geworfen, wenn bei der Interaktion mit COM-Objekten, DCOM-Schnittstellen oder Typelibraries unter Windows ein Fehler auftritt – beispielsweise wenn ein COM-Objekt nicht instanziiert werden kann oder ein Methodenaufruf einen HRESULT-Fehlercode zurückliefert.

Da com_exception von der eingebauten Exception-Klasse erbt, stehen alle Standard-Methoden wie getMessage(), getCode() und getTrace() zur Verfügung. Besonders relevant ist der Fehlercode, der direkt dem COM-HRESULT-Wert entspricht und für die Fehlerdiagnose genutzt werden kann.

Die Klasse ist ausschließlich unter Windows verfügbar, da die COM-Erweiterung nur auf diesem Betriebssystem unterstützt wird. Sie sollte im catch-Block gezielt abgefangen werden, wenn mit new COM(...) oder new VARIANT(...) gearbeitet wird, um COM-spezifische Fehler von allgemeinen PHP-Exceptions zu unterscheiden.

Beispiele

COM-Objekt instanziieren und Ausnahme abfangen

<?php
try {
    // Versucht, Microsoft Word als COM-Objekt zu laden
    $word = new COM('Word.Application');
    $word->Visible = true;
    echo "Word wurde erfolgreich gestartet.\n";
} catch (com_exception $e) {
    // Gibt den HRESULT-Fehlercode und die Fehlermeldung aus
    echo "COM-Fehler aufgetreten!\n";
    echo "Fehlercode (HRESULT): 0x" . dechex($e->getCode()) . "\n";
    echo "Meldung: " . $e->getMessage() . "\n";
}

COM-Fehler aufgetreten! Fehlercode (HRESULT): 0x800401f3 Meldung: Invalid class string

Mehrstufige Fehlerbehandlung mit com_exception und allgemeiner Exception

<?php
function getExcelApp(): COM {
    try {
        $excel = new COM('Excel.Application');
        $excel->Visible = false;
        return $excel;
    } catch (com_exception $e) {
        // Spezifische COM-Fehler werden weitergereicht
        throw new RuntimeException(
            'Excel konnte nicht gestartet werden. HRESULT: 0x' . dechex($e->getCode()),
            0,
            $e
        );
    }
}

try {
    $app = getExcelApp();
    echo "Excel bereit.\n";
} catch (RuntimeException $e) {
    echo $e->getMessage() . "\n";
    // Ursprüngliche com_exception über getPrevious() verfügbar
    echo "Ursprung: " . $e->getPrevious()->getMessage() . "\n";
}

Excel konnte nicht gestartet werden. HRESULT: 0x800401f3 Ursprung: Invalid class string

// Wichtig · Fallstricke

Nur unter Windows verfügbar: Die COM-Erweiterung und damit com_exception ist ausschließlich auf Windows-Systemen nutzbar. Auf Linux/macOS führt die Verwendung zu einem fatalen Fehler, da die Klasse nicht existiert.

HRESULT-Codes: Der über getCode() zurückgegebene Fehlercode entspricht dem Windows-HRESULT-Wert. Diese Werte können auf der Microsoft-Dokumentationsseite nachgeschlagen werden. Eine hexadezimale Darstellung via dechex() erleichtert die Recherche erheblich.

Erweiterungsabhängigkeit: Die Erweiterung muss in der php.ini mit extension=com_dotnet aktiviert sein. Ohne diese Aktivierung ist com_exception nicht verfügbar.

Siehe auch

com Exception variant dotnet