Signatur
Beschreibung
variant_cast konvertiert den Wert eines bestehenden variant-Objekts in einen anderen COM-Variantentyp und gibt das Ergebnis als neues variant-Objekt zurück. Die Funktion ist ausschließlich auf Windows-Systemen verfügbar, da sie Teil der COM-Erweiterung von PHP ist.
Der Zieltyp wird über eine der vordefinierten VT_*-Konstanten angegeben (z. B. VT_I4 für einen 32-Bit-Integer, VT_BSTR für einen Unicode-String, VT_R8 für ein Double). Das Original-Objekt wird dabei nicht verändert; stattdessen wird ein neues variant-Objekt zurückgegeben.
Diese Funktion ist vor allem dann nützlich, wenn COM-Schnittstellen (z. B. Microsoft Office Automation oder ActiveX-Komponenten) einen bestimmten Variantentyp für einen Parameter oder Rückgabewert erwarten und PHP den Typ nicht automatisch korrekt ableitet. Durch explizite Typangabe lassen sich Typkonvertierungsfehler in der COM-Kommunikation vermeiden.
Nicht alle Typkonvertierungen sind möglich; eine unzulässige Konvertierung führt zu einem com_exception-Fehler. Zu den häufig verwendeten Zieltypen gehören VT_I2, VT_I4, VT_R4, VT_R8, VT_BSTR, VT_BOOL und VT_DATE.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $variant Pflicht | variant | Das Quell-variant-Objekt, dessen Wert konvertiert werden soll. |
|
| $type Pflicht | int | Der Ziel-COM-Variantentyp, angegeben als eine der VT_*-Konstanten (z. B. VT_I4, VT_BSTR, VT_R8). |
Rückgabewert
variant-Objekt zurück, das den konvertierten Wert im angegebenen COM-Typ enthält. Bei einer ungültigen oder nicht unterstützten Konvertierung wird eine com_exception ausgelöst.Beispiele
Variant von Float zu Integer konvertieren
<?php
// Erstellt ein variant-Objekt mit einem Float-Wert (VT_R8)
$floatVariant = new variant(3.7, VT_R8);
echo 'Typ vorher: ' . variant_get_type($floatVariant) . PHP_EOL; // 5 = VT_R8
// Konvertierung zu einem 32-Bit-Integer (VT_I4)
$intVariant = variant_cast($floatVariant, VT_I4);
echo 'Typ nachher: ' . variant_get_type($intVariant) . PHP_EOL; // 3 = VT_I4
echo 'Wert: ' . $intVariant . PHP_EOL; // 4 (gerundet)
?>Variant zu String (BSTR) konvertieren für COM-Aufruf
<?php
// Numerischen Wert als BSTR-Variant für eine COM-Komponente vorbereiten
$numericVariant = new variant(42, VT_I4);
// Explizit zu VT_BSTR konvertieren, da die COM-Methode einen String erwartet
$stringVariant = variant_cast($numericVariant, VT_BSTR);
echo 'Typ: ' . variant_get_type($stringVariant) . PHP_EOL; // 8 = VT_BSTR
echo 'Wert: ' . $stringVariant . PHP_EOL; // 42
// Beispiel: Übergabe an eine fiktive COM-Komponente
// $comObject->MethodeErwartetString($stringVariant);
?>// Wichtig · Fallstricke
Plattformabhängigkeit: variant_cast ist ausschließlich unter Windows verfügbar und erfordert die aktivierte PHP-COM-Erweiterung (extension=com_dotnet in der php.ini). Auf anderen Betriebssystemen ist die Funktion nicht vorhanden.
Fehlerbehandlung: Bei einer nicht unterstützten Typkonvertierung (z. B. ein String, der keine gültige Zahl enthält, nach VT_I4) wird eine com_exception geworfen. Es empfiehlt sich, den Aufruf in einem try/catch-Block abzusichern.
Unterschied zu variant_set_type: Im Gegensatz zu variant_set_type, das das bestehende Objekt in-place verändert, erzeugt variant_cast immer ein neues variant-Objekt und lässt das Original unberührt.