==========
Decimal128
==========

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 2
   :class: singlecol

Overview
--------

MongoDB 3.4 introduced support for a :manual:`Decimal128 BSON type
</manual/release-notes/3.4/#decimal-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 :manual:`monetary
data </tutorial/model-monetary-data>`, such as financial and tax computations.

The :php:`MongoDB\BSON\Decimal128 <mongodb-bson-decimal128>` class, which was
introduced in :php:`PHP driver <mongodb>` 1.2.0, may be used to work with this
type in PHP.

Working with Decimal128 Values
------------------------------

Inserting a Decimal128
~~~~~~~~~~~~~~~~~~~~~~

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

.. code-block:: php

   <?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"
       }
     }
   }

Mathematical Operations with BCMath
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The :php:`PHP driver <mongodb>` does not provide any functionality for working
with ``Decimal128`` values; however, the string representation of a
:php:`MongoDB\BSON\Decimal128 <mongodb-bson-decimal128>` object may be used
with PHP's :php:`BCMath <bcmath>` extension.

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

.. code-block:: php

   <?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 :php:`bcadd() <bcadd>` to
obtain the expected result:

.. code-block:: php

   <?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
:php:`bcscale() <bcscale>` or the :php:`bcmath.scale INI setting
<manual/en/bc.configuration.php#ini.bcmath.scale>`. The ``Decimal128`` type
supports up to 34 decimal digits (i.e. significant digits).