Signatur
Beschreibung
BcMath\Number ist eine in PHP 8.4 eingeführte Klasse, die eine beliebig genaue Dezimalzahl kapselt und die volle Funktionalität der BCMath-Erweiterung objektorientiert zugänglich macht. Im Gegensatz zu den prozeduralen bc*-Funktionen erlaubt diese Klasse den Einsatz natürlicher PHP-Operatoren wie +, -, *, /, %, ** sowie Vergleichsoperatoren direkt auf Number-Instanzen.
Ein zentrales Merkmal ist die unveränderliche (immutable) Natur der Objekte: Jede Rechenoperation liefert eine neue BcMath\Number-Instanz zurück, anstatt das bestehende Objekt zu verändern. Die Genauigkeit (Nachkommastellen) kann per Konstruktor oder über die globale BCMath-Skalierung gesteuert werden.
Typische Einsatzgebiete sind Finanzberechnungen, wissenschaftliche Anwendungen oder jeder Kontext, in dem Float-Rundungsfehler nicht akzeptabel sind. Da die Klasse Stringable implementiert, lassen sich Instanzen direkt in String-Kontexten verwenden, etwa mit echo oder sprintf.
Alle arithmetischen BCMath-Methoden wie add(), sub(), mul(), div(), mod(), pow(), sqrt() u. v. m. stehen als Instanzmethoden zur Verfügung und akzeptieren sowohl andere Number-Instanzen als auch numerische Strings und Integer-Werte als Argumente.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $num Pflicht | string|int | Der Anfangswert der Zahl als numerischer String (z. B. '3.14159') oder als Integer. Wissenschaftliche Notation (z. B. '1.5e3') wird nicht unterstützt. |
|
| $scale | int | null | Anzahl der Nachkommastellen, die für diese Instanz und ihre Operationsergebnisse verwendet werden. Wird null übergeben, gilt die globale BCMath-Skalierung (bcscale()). |
Beispiele
Grundlegende arithmetische Operationen mit Operatorüberladung
<?php
use BcMath\Number;
$a = new Number('10.5');
$b = new Number('3.2');
$sum = $a + $b;
$product = $a * $b;
$power = $a ** 2;
echo $sum; // 13.7
echo PHP_EOL;
echo $product; // 33.60
echo PHP_EOL;
echo $power; // 110.25
Finanzberechnung mit fester Genauigkeit
<?php
use BcMath\Number;
// Mehrwertsteuer-Berechnung mit 2 Nachkommastellen
$netto = new Number('199.99', 2);
$mwstSatz = new Number('0.19', 2);
$mwst = $netto * $mwstSatz;
$brutto = $netto + $mwst;
printf("Netto: %s EUR\n", $netto);
printf("MwSt: %s EUR\n", $mwst);
printf("Brutto: %s EUR\n", $brutto);
Vergleichsoperatoren und Methoden
<?php
use BcMath\Number;
$x = new Number('7.5');
$y = new Number('7.50');
$z = new Number('8');
var_dump($x == $y); // true (wertgleich)
var_dump($x < $z); // true
var_dump($x > $z); // false
// Methode sqrt() mit expliziter Skalierung
$root = (new Number('2'))->sqrt(scale: 10);
echo $root; // 1.4142135623
Unveränderlichkeit (Immutability) demonstrieren
<?php
use BcMath\Number;
$original = new Number('42');
$result = $original + new Number('8');
echo $original; // 42 — unverändert
echo PHP_EOL;
echo $result; // 50
echo PHP_EOL;
// Instanzen sind nicht identisch
var_dump($original === $result); // false
// Wichtig · Fallstricke
Genauigkeitsfallen: Wird kein scale-Parameter übergeben und wurde bcscale() nicht gesetzt, beträgt die Standardskalierung 0, was bei Divisionen zu ganzzahligen Ergebnissen führen kann. Immer explizit eine Skalierung angeben oder global mit bcscale() festlegen.
Keine wissenschaftliche Notation: Eingaben wie '1.5e10' lösen einen ValueError aus. Solche Werte müssen vorher in reguläre Dezimalstrings umgewandelt werden.
Vergleichsoperatoren: Da PHP-Objekte bei == normalerweise per Referenz verglichen werden, implementiert BcMath\Number einen eigenen Vergleichsmechanismus, der einen wertbasierten Vergleich ermöglicht. === prüft hingegen weiterhin Objektidentität.
Kompatibilität: Die Klasse setzt die BCMath-Erweiterung voraus, die ab PHP 8.4 standardmäßig aktiviert ist. In älteren PHP-Versionen steht BcMath\Number nicht zur Verfügung — dort müssen die prozeduralen bc*-Funktionen verwendet werden.