variant_add — Funktion · PHP-Referenz

Signatur

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

Beschreibung

variant_add() führt eine Addition auf zwei COM-Variant-Werten durch und entspricht dem VBScript-Operator + für Varianten. Die Funktion ist Teil der Windows-spezifischen COM-Erweiterung von PHP und steht daher nur auf Windows-Systemen zur Verfügung.

Variant-Typen sind spezielle Datencontainer, die vom Windows Component Object Model (COM) verwendet werden. Sie können unterschiedliche Datentypen (Integer, Float, String, Boolean, Datum usw.) aufnehmen, ähnlich einer typenlosen Variable. variant_add() berücksichtigt dabei die internen Typregeln von COM, die sich von den PHP-eigenen Typregeln unterscheiden können – insbesondere bei der String-Verkettung (Strings werden addiert, nicht verkettet).

Die Funktion ist sinnvoll, wenn man mit COM-Objekten (z. B. Excel via COM, Windows Scripting Host) arbeitet und Rechenoperationen exakt so durchführen möchte, wie es VBScript oder andere COM-Clients tun würden, ohne PHP-eigene Typumwandlungen zu riskieren.

Beide Argumente können entweder native PHP-Werte (Integer, Float, String) oder VARIANT-Objekte sein. Das Ergebnis ist stets ein VARIANT-Objekt.

Parameter

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

Rückgabewert

Typ

mixed

Beschreibung

Gibt ein VARIANT-Objekt mit dem Ergebnis der Addition zurück. Der genaue Typ des zurückgegebenen Variant-Werts richtet sich nach den COM-Typregeln für die Eingabeoperanden.

Beispiele

Einfache Addition zweier Integer-Variant-Werte

<?php
// Zwei VARIANT-Objekte erstellen und addieren
$a = new VARIANT(10, VT_I4);
$b = new VARIANT(25, VT_I4);

$result = variant_add($a, $b);
echo (int) $result; // 35

35

Addition mit nativen PHP-Werten

<?php
// variant_add akzeptiert auch native PHP-Werte direkt
$result = variant_add(7.5, 2.5);
echo (float) $result; // 10.0

// Achtung: Strings werden nach COM-Regeln numerisch addiert, nicht verkettet!
$strResult = variant_add('10', '20');
echo (int) $strResult; // 30 — NICHT '1020'

10 30

Verwendung mit einem COM-Excel-Objekt

<?php
// Beispiel: Zellwert aus Excel per COM auslesen und etwas addieren
$excel = new COM('Excel.Application');
$excel->Visible = false;
$workbooks = $excel->Workbooks->Open('C:\\Daten\\tabelle.xlsx');
$sheet = $workbooks->Worksheets(1);

$cellValue = $sheet->Cells(1, 1)->Value; // VARIANT-Wert aus Excel
$sum = variant_add($cellValue, new VARIANT(100, VT_I4));
echo 'Summe: ' . (int) $sum;

$excel->Quit();
unset($excel);

// Wichtig · Fallstricke

Windows-only: variant_add() ist ausschließlich auf Windows-Systemen verfügbar, da sie die COM-Erweiterung (php_com_dotnet.dll) voraussetzt. Auf Linux/macOS führt der Aufruf zu einem Fatal Error.

String-Verhalten: Anders als PHP's .-Operator werden zwei Strings nach COM-Regeln numerisch addiert, nicht verkettet. variant_add('5', '3') ergibt 8, nicht '53'. Dieses Verhalten entspricht VBScript und kann zu unerwartetem Ergebnis führen, wenn man PHP-Konventionen erwartet.

Typverhalten: Das Ergebnis richtet sich nach den COM-internen Typpromotion-Regeln. Wenn unklar ist, welcher Typ zurückgegeben wird, empfiehlt sich ein expliziter Cast des Ergebnisses.

Siehe auch

variant_sub variant_mul variant_div variant_mod variant_int COM