Signatur
Beschreibung
com_get_active_object() ermöglicht es, auf eine bereits gestartete Instanz eines COM-Servers zuzugreifen, ohne eine neue Instanz zu erzeugen. Dies entspricht funktional der Windows-API-Funktion GetActiveObject() und ist besonders nützlich, wenn z. B. Microsoft Excel, Word oder eine andere COM-fähige Anwendung bereits geöffnet ist und von PHP aus gesteuert werden soll.
Die Funktion wird typischerweise eingesetzt, wenn das erneute Starten einer Anwendungsinstanz unerwünscht ist – etwa bei Automatisierungsaufgaben, bei denen ein bereits sichtbares Office-Dokument weiterbearbeitet werden soll, ohne den Benutzer zu unterbrechen.
Ist keine laufende Instanz vorhanden, wirft die Funktion eine com_exception. Der Rückgabewert ist ein variant-Objekt (eine Instanz der PHP-Klasse COM), mit dem anschließend auf alle Methoden und Eigenschaften des COM-Objekts zugegriffen werden kann.
Die Funktion steht nur auf Windows-Systemen mit aktivierter COM-Erweiterung zur Verfügung. Das PHP-INI-Flag com.allow_dcom beeinflusst den Zugriff auf entfernte COM-Objekte, hat aber keinen direkten Einfluss auf lokale aktive Objekte.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $prog_id Pflicht | string | Die ProgID des gewünschten COM-Objekts, z. B. "Excel.Application" oder "Word.Application". Diese ID identifiziert eindeutig den COM-Server in der Windows-Registry. |
|
| $code_page | int | CP_ACP | Die Codepage, die für die Konvertierung von PHP-Strings in Unicode und zurück verwendet wird. Typische Werte sind CP_ACP (Standard-ANSI-Codepage), CP_UTF8 (65001) oder CP_WINUNICODE (1200). |
Rückgabewert
variant-Objekt zurück, das die laufende COM-Instanz repräsentiert. Im Fehlerfall (keine laufende Instanz vorhanden oder die ProgID ist unbekannt) wird eine com_exception geworfen.Beispiele
Zugriff auf eine laufende Excel-Instanz
<?php
try {
// Verbindung zu einer bereits geöffneten Excel-Instanz herstellen
$excel = com_get_active_object('Excel.Application');
// Excel sichtbar machen (falls ausgeblendet)
$excel->Visible = true;
// Titel der aktiven Arbeitsmappe ausgeben
$workbook = $excel->ActiveWorkbook;
if ($workbook !== null) {
echo 'Aktive Arbeitsmappe: ' . $workbook->Name . PHP_EOL;
} else {
echo 'Keine Arbeitsmappe geöffnet.' . PHP_EOL;
}
} catch (com_exception $e) {
echo 'Fehler: Excel ist nicht geöffnet oder nicht erreichbar.' . PHP_EOL;
echo $e->getMessage() . PHP_EOL;
}Fallback: Neue Instanz starten, falls keine vorhanden
<?php
try {
// Versuche, eine laufende Word-Instanz zu verwenden
$word = com_get_active_object('Word.Application');
echo 'Bestehende Word-Instanz gefunden.' . PHP_EOL;
} catch (com_exception $e) {
// Keine laufende Instanz – neue starten
$word = new COM('Word.Application');
echo 'Neue Word-Instanz gestartet.' . PHP_EOL;
}
$word->Visible = true;
// Weiterer Code zur Dokumentbearbeitung ...// Wichtig · Fallstricke
Plattformabhängigkeit: com_get_active_object() ist ausschließlich unter Windows verfügbar und setzt die COM-Erweiterung (ext/com_dotnet) voraus. Auf Linux- oder macOS-Systemen existiert diese Funktion nicht.
Fehlerbehandlung: Die Funktion wirft eine com_exception, wenn das COM-Objekt nicht im Running Object Table (ROT) eingetragen ist – d. h. wenn keine passende Instanz aktiv ist. Daher sollte der Aufruf stets in einem try/catch-Block erfolgen.
Sicherheit: Beim Einsatz in Webserver-Kontexten (z. B. unter IIS) können Berechtigungsprobleme auftreten, da der Webserver-Prozess möglicherweise nicht auf die Desktop-Anwendung des angemeldeten Benutzers zugreifen darf. COM-Interop in Webserver-Umgebungen sollte daher mit Vorsicht eingesetzt werden.