Signatur
Beschreibung
Die Klasse variant ist PHPs Wrapper für den COM-Datentyp VARIANT – das universelle Datencontainer-Format der Windows COM-Technologie. Ein VARIANT kann Werte unterschiedlicher Typen (Integer, Float, String, Boolean, Datum, Array usw.) aufnehmen und dabei den genauen COM-Typ explizit festhalten. PHP konvertiert primitive Werte beim Übergeben an COM-Objekte zwar automatisch, aber mit variant lässt sich der Zieltyp präzise steuern.
Die Klasse wird hauptsächlich benötigt, wenn eine COM-Methode oder -Eigenschaft einen bestimmten VARIANT-Typ erwartet, der von der automatischen Typkonvertierung Phpens nicht korrekt erzeugt würde – etwa VT_DATE, VT_CY (Currency) oder vorzeichenlose Integer-Typen. Durch das Angeben einer der VT_*-Konstantenwerte als zweites Argument lässt sich der gewünschte COM-Typ erzwingen.
Zusätzlich unterstützt die Klasse arithmetische Operationen (variant_add(), variant_mul() usw.) über zugehörige Hilfsfunktionen sowie Vergleichsoperationen über variant_cmp(). Diese Operationen arbeiten nach den COM-Konvertierungsregeln und können daher von PHPs normalen Typregeln abweichen.
Voraussetzung: Die com_dotnet-Erweiterung muss aktiv sein (Windows-only). Auf Nicht-Windows-Systemen steht diese Klasse nicht zur Verfügung.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value | mixed | null | Der initiale Wert des VARIANT. PHP konvertiert den übergebenen PHP-Wert gemäß $type in den entsprechenden COM-Typ. |
| $type | int | VT_EMPTY | Eine der VT_*-Konstanten (z. B. VT_I4, VT_BSTR, VT_DATE), die den gewünschten COM-Datentyp festlegen. Wird kein Typ angegeben, wählt PHP einen passenden Typ automatisch. |
| $codepage | int | CP_ACP | Codepage für die String-Konvertierung (z. B. CP_UTF8). Relevant nur, wenn der Wert oder Teile davon Zeichenketten sind. |
Beispiele
Einfachen VARIANT-Wert erstellen und an COM übergeben
<?php
// Voraussetzung: Windows mit aktiver com_dotnet-Erweiterung
// Excel per COM steuern
$excel = new COM('Excel.Application');
$excel->Visible = true;
$excel->Workbooks->Add();
$sheet = $excel->ActiveSheet;
// Einen explizit als VT_BSTR (String) typisierten VARIANT übergeben
$cellValue = new variant('Hallo COM-Welt', VT_BSTR);
$sheet->Cells(1, 1)->Value = $cellValue;
echo "Wert wurde als BSTR-VARIANT gesetzt.\n";
$excel->Quit();
unset($excel);Datumswert als VT_DATE-VARIANT übergeben
<?php
// Datum explizit als COM-Datumswert (VT_DATE) übergeben
// COM erwartet hier einen OLE Automation Date (Double)
$comDate = new variant(44927.0, VT_DATE); // 01.01.2023 als OLE-Datumszahl
echo variant_date_to_timestamp($comDate); // Unix-Timestamp ausgebenArithmetik mit variant-Hilfsfunktionen
<?php
// variant_add() folgt COM-Typregeln, nicht PHP-Typregeln
$a = new variant(10, VT_I4); // 32-Bit-Integer
$b = new variant(3, VT_I4);
$summe = variant_add($a, $b);
echo $summe; // 13
$produkt = variant_mul($a, $b);
echo $produkt; // 30// Wichtig · Fallstricke
Windows-only: Die Klasse variant sowie alle variant_*()-Funktionen sind ausschließlich unter Windows verfügbar, wenn die Erweiterung php_com_dotnet.dll geladen ist.
Typfallen: Ohne explizite VT_*-Angabe wählt PHP den Typ selbst – dies führt gelegentlich zu unerwarteten Konvertierungen auf der COM-Seite. Bei Typen wie VT_DATE oder VT_CY sollte der Typ immer explizit gesetzt werden.
Vererbung: Die Klassen com und dotnet erben von variant, so dass COM-Objekte selbst VARIANT-Instanzen sind.