Signatur
Beschreibung
Die Klasse com ist der zentrale Einstiegspunkt für die PHP-COM-Erweiterung unter Windows. Sie erlaubt es, beliebige OLE-kompatible COM-Objekte zu erzeugen, ihre Methoden aufzurufen und auf ihre Eigenschaften lesend und schreibend zuzugreifen – genauso, wie man es aus Visual Basic oder Windows Script Host kennt.
Typische Anwendungsfälle sind die Automatisierung von Microsoft-Office-Anwendungen (Word, Excel, Outlook), die Nutzung von Windows-Systemkomponenten (z. B. WScript.Shell, ADODB.Connection, Scripting.FileSystemObject) sowie die Integration beliebiger registrierter COM-Server. Das COM-Objekt wird über seinen ProgID- oder CLSID-String identifiziert.
Nach der Instanziierung verhält sich das zurückgegebene Objekt weitgehend wie ein normales PHP-Objekt: Eigenschaften können per -> gelesen und gesetzt werden, Methoden werden direkt aufgerufen. Intern erbt com von variant und kann daher auch als Variant-Wert an andere COM-Methoden übergeben werden.
Wichtig: Die COM-Erweiterung ist ausschließlich unter Windows verfügbar und muss in der php.ini mit extension=php_com_dotnet.dll aktiviert sein.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $module_name Pflicht | string | ProgID oder CLSID des zu instanziierenden COM-Objekts, z. B. 'Excel.Application' oder '{00024500-0000-0000-C000-000000000046}'. |
|
| $server_name | string|array|null | null | Name eines DCOM-Servers, auf dem das Objekt erzeugt werden soll. Kann auch ein Array mit Verbindungsparametern (z. B. 'Server', 'Username', 'Password') sein. null bedeutet lokale Erzeugung. |
| $codepage | int | CP_ACP | Codepage für die Umwandlung zwischen PHP-Strings und Unicode-Strings. Typische Werte: CP_ACP (Standard), CP_UTF8, CP_OEM. |
| $typelib | string | Pfad oder Name einer Typbibliothek (.tlb), die geladen werden soll, um Konstanten der Typbibliothek in den globalen Namensraum zu importieren. |
Beispiele
Excel-Datei per COM-Automatisierung erstellen
<?php
// Excel starten (Windows + COM-Erweiterung erforderlich)
$excel = new com('Excel.Application') or die('Excel konnte nicht gestartet werden.');
$excel->Visible = false; // Excel unsichtbar im Hintergrund
$workbook = $excel->Workbooks->Add();
$worksheet = $workbook->Worksheets(1);
$worksheet->Cells(1, 1)->Value = 'Name';
$worksheet->Cells(1, 2)->Value = 'Umsatz';
$worksheet->Cells(2, 1)->Value = 'Müller GmbH';
$worksheet->Cells(2, 2)->Value = 125000;
$workbook->SaveAs('C:\\Temp\\umsatz.xlsx');
$workbook->Close(false);
$excel->Quit();
unset($worksheet, $workbook, $excel);
echo 'Excel-Datei wurde erfolgreich erstellt.';
Windows-Shell-Befehl über WScript.Shell ausführen
<?php
// WScript.Shell COM-Objekt nutzen, um einen Systemprozess zu starten
$shell = new com('WScript.Shell');
// Einen einfachen Ping-Befehl ausführen (synchron, Rückgabe: Exit-Code)
$exitCode = $shell->Run('cmd /c ping -n 1 127.0.0.1 > NUL', 0, true);
if ($exitCode === 0) {
echo 'Ping erfolgreich – Loopback erreichbar.';
} else {
echo 'Ping fehlgeschlagen (Exit-Code: ' . $exitCode . ').';
}
unset($shell);
ADODB-Datenbankverbindung über COM
<?php
// ADODB Connection über COM (z. B. für Access-Datenbanken)
$conn = new com('ADODB.Connection');
$conn->Open('Provider=Microsoft.ACE.OLEDB.12.0;Data Source=C:\\Daten\\test.accdb');
$rs = $conn->Execute('SELECT Name, Alter FROM Personen');
while (!$rs->EOF) {
echo $rs->Fields('Name')->Value . ' (' . $rs->Fields('Alter')->Value . ')' . PHP_EOL;
$rs->MoveNext();
}
$rs->Close();
$conn->Close();
unset($rs, $conn);
// Wichtig · Fallstricke
Plattformbeschränkung: Die com-Klasse funktioniert ausschließlich unter Windows. Auf Linux oder macOS ist sie nicht verfügbar. Produktivsysteme sollten daher auf Windows-Server oder entsprechende Umgebungen beschränkt sein.
Sicherheit: COM-Automatisierung mit externen oder nutzergesteuerten Eingaben birgt erhebliche Sicherheitsrisiken. Niemals ungefilterte Benutzereingaben als ProgID oder in Methoden-Argumenten verwenden – das kann zur Ausführung beliebiger Systembefehle führen. Besondere Vorsicht bei WScript.Shell und ähnlichen mächtigen COM-Servern.
Ressourcenfreigabe: COM-Objekte (besonders Office-Anwendungen) müssen explizit mit Quit() bzw. Close() beendet und mit unset() freigegeben werden, da sonst Prozesse im Hintergrund weiterlaufen.
Codepage: Bei Problemen mit Umlauten empfiehlt sich die Verwendung von CP_UTF8 als dritten Parameter, sofern das COM-Objekt Unicode unterstützt.