Docs Menu

Docs HomePHP Library Manual

Decimal128

On this page

  • Overview
  • Working with Decimal128 Values
  • Inserting a Decimal128
  • Mathematical Operations with BCMath

MongoDB 3.4 introduced support for a Decimal128 BSON type, which is a 128-bit decimal-based floating-point value capable of emulating decimal rounding with exact precision. This functionality is intended for applications that handle monetary data, such as financial and tax computations.

The MongoDB\BSON\Decimal128 class, which was introduced in PHP driver 1.2.0, may be used to work with this type in PHP.

The following example inserts a value of type Decimal128 into the price field of a collection named inventory:

<?php
$collection = (new MongoDB\Client)->test->inventory;
$collection->insertOne([
'_id' => 1,
'item' => '26-inch monitor',
'price' => new MongoDB\BSON\Decimal128('428.79'),
]);
$item = $collection->findOne(['_id' => 1]);
var_dump($item);

The output would then resemble:

object(MongoDB\Model\BSONDocument)#9 (1) {
["storage":"ArrayObject":private]=>
array(3) {
["_id"]=>
int(1)
["item"]=>
string(15) "26-inch monitor"
["price"]=>
object(MongoDB\BSON\Decimal128)#13 (1) {
["dec"]=>
string(6) "428.79"
}
}
}

The PHP driver does not provide any functionality for working with Decimal128 values; however, the string representation of a MongoDB\BSON\Decimal128 object may be used with PHP's BCMath extension.

The following example adds two Decimal128 values and creates a new Decimal128 value with the result from bcadd():

<?php
$lhs = new MongoDB\BSON\Decimal128('1.234');
$rhs = new MongoDB\BSON\Decimal128('5.678');
$sum = new MongoDB\BSON\Decimal128(bcadd($lhs, $rhs));
var_dump($sum);

The output would then resemble:

object(MongoDB\BSON\Decimal128)#4 (1) {
["dec"]=>
string(1) "6"
}

This does not match the expected result of "6.912". Each operation in the BCMath API uses a scale to determine the number of decimal digits in the result. The default scale is zero, which is why the above example produces a result with no decimal precision.

In the following example, we use a scale of three for bcadd() to obtain the expected result:

<?php
$lhs = new MongoDB\BSON\Decimal128('1.234');
$rhs = new MongoDB\BSON\Decimal128('5.678');
$sum = new MongoDB\BSON\Decimal128(bcadd($lhs, $rhs, 3));
var_dump($sum);

The output would then resemble:

object(MongoDB\BSON\Decimal128)#4 (1) {
["dec"]=>
string(5) "6.912"
}

In lieu of specifying a scale for each operation, a default scale may be set via bcscale() or the bcmath.scale INI setting. The Decimal128 type supports up to 34 decimal digits (i.e. significant digits).

←  Custom Data-TypesIn-Use Encryption →