Signatur
Beschreibung
com_safearray_proxy ist eine interne PHP-Klasse, die automatisch erzeugt wird, wenn auf ein mehrdimensionales SAFEARRAY aus einem COM-Objekt zugegriffen wird. Sie stellt einen Proxy-Mechanismus bereit, über den PHP-Code die Elemente eines solchen Arrays schrittweise traversieren kann, ohne dass der gesamte Speicherinhalt sofort in eine PHP-Datenstruktur kopiert werden muss.
Ein SAFEARRAY ist ein in Microsoft COM/OLE weit verbreiteter Datentyp, der typisierte, mehrdimensionale Arrays beschreibt. Wenn ein COM-Objekt (z. B. eine Excel- oder ADO-Instanz) ein solches Array zurückliefert, kapselt PHP den Zugriff automatisch in einem com_safearray_proxy-Objekt, sodass der Entwickler über die gewohnte Array-Syntax auf die Inhalte zugreifen kann.
Diese Klasse wird nicht direkt instanziiert; sie entsteht implizit, sobald PHP-Code auf ein COM-Property oder eine Methode zugreift, die ein mehrdimensionales SAFEARRAY liefert. Sie ist ausschließlich unter Windows im Zusammenspiel mit der COM-Erweiterung verfügbar.
Typische Anwendungsgebiete sind der Zugriff auf Excel-Zellbereiche, ADO-Recordset-Felder oder andere OLE-Automation-Objekte, die Arrays als SAFEARRAY-Varianten zurückgeben. Der Entwickler sollte sich bewusst sein, dass com_safearray_proxy nur als Durchgangsschicht fungiert und nicht für eigenständige Operationen gedacht ist.
Beispiele
Zugriff auf ein Excel-Zellbereich-SAFEARRAY via COM
<?php
// Voraussetzung: Windows, COM-Erweiterung aktiviert, Excel installiert
$excel = new COM('Excel.Application');
$excel->Visible = false;
$workbooks = $excel->Workbooks->Open('C:\\test.xlsx');
$sheet = $workbooks->Sheets(1);
// Range->Value2 kann ein mehrdimensionales SAFEARRAY zurückliefern
$range = $sheet->Range('A1:C3');
$safeArray = $range->Value2; // Liefert ein com_safearray_proxy-Objekt
// Zugriff auf Elemente über Array-Syntax (1-basierter Index bei Excel)
echo $safeArray[1][1]; // Zelle A1
echo $safeArray[2][3]; // Zelle C2
$excel->Quit();
unset($excel);
?>Iteration über ein SAFEARRAY-Proxy-Objekt
<?php
// Annahme: $safeArray ist ein durch COM zurückgegebenes com_safearray_proxy
// z. B. aus einem ADO-Recordset oder Excel-Range
// Konvertierung in ein normales PHP-Array
function safeArrayToPhpArray($proxy): array {
$result = [];
foreach ($proxy as $row) {
if ($row instanceof com_safearray_proxy) {
$result[] = safeArrayToPhpArray($row);
} else {
$result[] = $row;
}
}
return $result;
}
// $safeArray wurde zuvor von einem COM-Objekt geliefert
// $phpArray = safeArrayToPhpArray($safeArray);
// print_r($phpArray);
?>// Wichtig · Fallstricke
Nur unter Windows verfügbar: com_safearray_proxy ist ausschließlich Teil der Windows-spezifischen COM-Erweiterung (ext/com_dotnet) und steht auf Linux/macOS nicht zur Verfügung.
Nicht manuell instanziieren: Die Klasse ist intern und sollte niemals direkt per new com_safearray_proxy() erzeugt werden. Jede direkte Nutzung außerhalb des COM-Erweiterungs-Kontexts ist undefiniertes Verhalten.
Indexierung: Viele COM-Objekte (insbesondere Office-Anwendungen) verwenden 1-basierte Indizes für SAFEARRAY-Zugriffe. Dies weicht vom üblichen PHP-Verhalten (0-basiert) ab und kann zu Verwirrung führen.
Speicher: Bei großen Arrays (z. B. umfangreiche Excel-Bereiche) kann die Konvertierung in PHP-Arrays erhebliche Speichermengen beanspruchen. Es empfiehlt sich, nur die tatsächlich benötigten Teilbereiche abzurufen.