variant_set_type — Funktion · PHP-Referenz

Signatur

variant_set_type(variant $variant, int $type): void

Beschreibung

variant_set_type() konvertiert den Wert einer bestehenden VARIANT-Instanz direkt in den angegebenen COM-Datentyp. Im Unterschied zu variant_cast(), das eine neue VARIANT zurückgibt, ändert variant_set_type() die übergebene Variable in-place – sie wird also dauerhaft auf den neuen Typ umgestellt.

Diese Funktion ist ausschließlich im Windows-COM-Umfeld relevant und wird benötigt, wenn bestimmte COM-Schnittstellen explizit einen konkreten Variant-Typ erwarten (z. B. VT_I4, VT_BSTR oder VT_BOOL). Die möglichen Typkonstanten sind als VT_*-Konstanten in der PHP-COM-Erweiterung definiert.

Typische Anwendungsfälle sind Situationen, bei denen Parameter für COM-Methoden exakt typisiert sein müssen oder wenn Daten vor der Übergabe an eine ActiveX-Komponente in den korrekten Variant-Typ konvertiert werden sollen.

Die Funktion wirft eine com_exception, wenn die Typkonvertierung fehlschlägt.
Sie steht nur auf Windows-Systemen mit aktivierter com_dotnet-Erweiterung zur Verfügung.

Parameter

Name	Typ	Default	Beschreibung
$variant Pflicht	variant		Die `VARIANT`-Instanz, deren Typ geändert werden soll. Diese Variable wird direkt modifiziert.
$type Pflicht	int		Der Ziel-COM-Variantentyp als `VT_*`-Konstante (z. B. `VT_I4` für 32-Bit-Integer, `VT_BSTR` für einen COM-String, `VT_BOOL` für einen booleschen Wert).

Rückgabewert

Typ

void

Beschreibung

Die Funktion gibt keinen Wert zurück. Die Änderung erfolgt direkt an der übergebenen VARIANT-Variable.

Beispiele

Variant-Wert von String in 32-Bit-Integer umwandeln

<?php
// Nur unter Windows mit COM-Erweiterung verfügbar
if (class_exists('VARIANT')) {
    // VARIANT mit einem String-Wert erstellen
    $v = new VARIANT('42', VT_BSTR);
    echo 'Typ vor Konvertierung: ' . variant_get_type($v) . PHP_EOL; // VT_BSTR = 8

    // In-place-Konvertierung zu VT_I4 (32-Bit-Integer)
    variant_set_type($v, VT_I4);
    echo 'Typ nach Konvertierung: ' . variant_get_type($v) . PHP_EOL; // VT_I4 = 3
    echo 'Wert: ' . $v . PHP_EOL; // 42
}

Typ vor Konvertierung: 8 Typ nach Konvertierung: 3 Wert: 42

Variant für COM-Methode mit exaktem Typ vorbereiten

<?php
// Nur unter Windows mit COM-Erweiterung verfügbar
if (class_exists('VARIANT') && class_exists('COM')) {
    // Excel-Instanz öffnen (Beispiel)
    // $excel = new COM('Excel.Application');

    // Beispiel: Zellwert als Double übergeben
    $zellwert = new VARIANT(3.14159);
    // Sicherstellen, dass der Typ VT_R8 (Double) ist
    variant_set_type($zellwert, VT_R8);

    echo 'Variant-Typ: ' . variant_get_type($zellwert) . PHP_EOL; // VT_R8 = 5
    echo 'Wert: ' . $zellwert . PHP_EOL;
    // $excel->ActiveSheet->Cells(1, 1)->Value = $zellwert;
}

Variant-Typ: 5 Wert: 3.14159

// Wichtig · Fallstricke

Plattformabhängigkeit: variant_set_type() ist ausschließlich auf Windows-Systemen mit der aktivierten PHP-Erweiterung php_com_dotnet.dll verfügbar. Ein Einsatz auf Linux/macOS führt zu einem fatalen Fehler (undefined function).

Fehlerbehandlung: Schlägt die Typkonvertierung fehl (z. B. weil ein String nicht in eine Zahl umgewandelt werden kann), wird eine com_exception ausgelöst. Dies sollte mit einem try/catch-Block abgefangen werden.

Unterschied zu variant_cast(): Während variant_cast() eine neue Kopie mit dem neuen Typ zurückgibt, verändert variant_set_type() die Original-Variable direkt. Dies kann zu unerwartetem Verhalten führen, wenn dieselbe VARIANT-Instanz an mehreren Stellen verwendet wird.

Siehe auch

variant_cast variant_get_type variant_set VARIANT COM