variant_cat — Funktion · PHP-Referenz

Signatur

variant_cat(mixed $left, mixed $right): mixed

Beschreibung

variant_cat() ist eine Windows-spezifische Funktion aus der COM/VARIANT-Erweiterung von PHP. Sie verkettet zwei Variant-Werte ähnlich wie der .-Operator in PHP Zeichenketten zusammenfügt, arbeitet jedoch direkt mit VARIANT-Objekten, die im COM-Interop-Kontext unter Windows verwendet werden.

Die Funktion ist primär dann sinnvoll, wenn man mit COM-Objekten (z. B. Microsoft Office-Anwendungen via COM) kommuniziert und dabei Variant-Werte erzeugt oder verarbeitet, die später als Parameter an COM-Methoden übergeben werden sollen. Sie stellt sicher, dass die Typinformationen des VARIANT-Typsystems korrekt erhalten bleiben.

Beide Parameter können entweder native PHP-Werte (z. B. Strings oder Zahlen) oder VARIANT-Objekte sein. PHP konvertiert einfache Typen automatisch in kompatible VARIANT-Darstellungen. Das Ergebnis ist ein neuer Variant-Wert, der die Verkettung beider Operanden repräsentiert.

Wichtig: Diese Funktion steht nur auf Windows-Systemen mit aktivierter COM-Erweiterung (php_com_dotnet.dll) zur Verfügung. Auf Linux- oder macOS-Systemen ist sie nicht verfügbar.

Parameter

Name	Typ	Default	Beschreibung
$left Pflicht	mixed		Der linke Operand der Verkettung. Kann ein nativer PHP-Wert oder ein `VARIANT`-Objekt sein.
$right Pflicht	mixed		Der rechte Operand der Verkettung. Kann ein nativer PHP-Wert oder ein `VARIANT`-Objekt sein.

Rückgabewert

Typ

mixed

Beschreibung

Gibt einen neuen Variant-Wert zurück, der die Verkettung von left und right darstellt. Bei einem Fehler (z. B. inkompatible Typen) wird eine com_exception ausgelöst.

Beispiele

Einfache Verkettung zweier Zeichenketten als Variant

<?php
// Nur unter Windows mit aktivierter COM-Erweiterung verfügbar
$left  = new VARIANT('Hallo, ', VT_BSTR);
$right = new VARIANT('Welt!', VT_BSTR);

$result = variant_cat($left, $right);

echo $result; // Gibt: Hallo, Welt!

Hallo, Welt!

Verkettung mit nativen PHP-Strings

<?php
// PHP konvertiert einfache Typen automatisch
$vorname = 'Max';
$nachname = new VARIANT(' Mustermann', VT_BSTR);

$vollname = variant_cat($vorname, $nachname);

echo $vollname; // Gibt: Max Mustermann

Max Mustermann

Verwendung im COM-Kontext mit Excel

<?php
// Beispiel: Zusammensetzen eines Zellinhalts für eine Excel-Zelle via COM
try {
    $excel = new COM('Excel.Application');
    $excel->Visible = true;

    $workbook  = $excel->Workbooks->Add();
    $worksheet = $workbook->Worksheets(1);

    $teil1 = new VARIANT('Gesamt: ', VT_BSTR);
    $teil2 = new VARIANT('1234 EUR', VT_BSTR);

    $zelleninhalt = variant_cat($teil1, $teil2);

    $worksheet->Cells(1, 1)->Value = $zelleninhalt;

    echo "Zelleninhalt gesetzt: " . $zelleninhalt;
} catch (com_exception $e) {
    echo 'COM-Fehler: ' . $e->getMessage();
}

Zelleninhalt gesetzt: Gesamt: 1234 EUR

// Wichtig · Fallstricke

Plattformabhängigkeit: variant_cat() ist ausschließlich unter Windows verfügbar und erfordert die aktivierte PHP-Erweiterung php_com_dotnet.dll in der php.ini. Auf anderen Betriebssystemen führt der Aufruf zu einem schwerwiegenden Fehler (Fatal Error).

Fehlerbehandlung: Bei inkompatiblen VARIANT-Typen (z. B. wenn einer der Operanden einen numerischen Typ hat, der keine Verkettung unterstützt) wirft die Funktion eine com_exception. Diese sollte immer mit einem try/catch-Block abgefangen werden.

Alternativen: Für rein PHP-seitige Zeichenkettenverkettung ohne COM-Kontext sollte stets der einfache .-Operator verwendet werden. variant_cat() ist nur dort sinnvoll, wo die VARIANT-Typen und deren Metadaten für die COM-Schnittstelle relevant sind.

Siehe auch

variant_add variant_sub variant_mul variant_div COM VARIANT