Getting started

Complete Installation first.

Floats cannot represent most decimal fractions exactly:

var_dump(0.1 + 0.2 === 0.3); // bool(false)
var_dump(0.1 + 0.2 - 0.3);   // float(5.551115123125783E-17)

Decimal stores the number as a string of digits and calculates with bcmath, so decimal fractions can be added exactly.

Save this as example.php in the directory containing composer.json:

<?php
require __DIR__ . '/vendor/autoload.php';

use PhpCollective\DecimalObject\Decimal;

$sum = Decimal::create('0.1')->add('0.2');

echo $sum, PHP_EOL;           // 0.3
var_dump($sum->equals('0.3')); // bool(true)

Run php example.php. Later snippets use the same Composer autoloader and Decimal import.

Immutability

A Decimal never changes. Each operation returns a new object, so assign the result:

$price = Decimal::create('19.90');
$total = $price->multiply('3');

echo $price; // 19.90
echo $total; // 59.70

A small invoice

$net = Decimal::create('19.99');
$tax = $net->multiply('0.19')->round(2); // 3.80
$gross = $net->add($tax);                // 23.79

if ($gross->greaterThan('20')) {
    echo 'Total: ' . $gross;
}

multiply() returned 3.7981 here, with the scales of both operands added up. round(2) brings it back to two decimal places. Precision and scale explains the rules for each operation.

Use strings for input

Pass decimal strings whenever you can. Float conversion follows PHP's precision setting. With its default of 14 digits, string conversion drops digits in this example:

echo Decimal::create('1234567890.1234567'); // 1234567890.1234567
echo Decimal::create(1234567890.1234567);   // 1234567890.1235

See Creating decimals for all accepted input.

Where to go next

• Arithmetic for the math operations
• Rounding for round(), floor(), ceil() and truncate()
• Comparison and checks
• API reference for every method on one page