marcoconsiglio/bcmath-extended

The BCMathExtended library extends the PHP BCMath extension adding more features like abs, min, max, random, factorial, type comparison between integer and decimal or positive and negative, modulo and power modulo with negative modulus (see more on BCMath extendsion http://php.net/manual/en/book.bc.

v2.2.0 2026-03-10 21:49 UTC

Requires

• php: ^8.4
• ext-bcmath: *

Requires (Dev)

• fakerphp/faker: ^1.24
• marcoconsiglio/faker-php-number-helpers: ^1.1
• phpunit/phpunit: ^13.0

MIT

• Marco Consiglio

• math
• precision
• bcmath
• rand
• Arbitrary-precision
• bignumber
• round
• ceil
• floor
• abs

README

bcmath-extended

This PHP library extends the BCMath PHP estension. Since the class BCMath\Number is a final class, this library extends through composition with a child class (Number).

It was inspired by krowinski/bcmath-extended.

Index

• Installation
• Features
• Input types
• Notes
• API documentation

Installation

composer require marcoconsiglio/bcmath-extended

Features

Base features

The following list of features of the Number class are the same as those found in BCMath\Number:

• Base instance $value
• Base instance $scale
• Addition
• Subtracion
• Multiplication
• Division
• Exponentiation
• Square root
• Ceil
• Floor
• Round
• Cast to string

Missing base features

These are the missing features:

• Spaceship comparison
• Comparison operator overloading
• Serialization/unserialization

Added features

This list consists of the new features added in this library:

• float type input **
• Cast to float type **
• Modulo *
• Power & modulo *
• Division & modulo *
• Absolute
• Min
• Max
• Random
• Equal comparison
• Different comparison
• Greater than comparison
• Greater than or equal comparison
• Less than comparison
• Less than or equal comparison
• Convert to radian
• Convert to degree

Input types

The same input type set of BCMath is used:

• int
• string
• float **
• BCMath\Number
• MarcoConsiglio\BCMathExtended\Number

String numeric format

• Only decimal separator . is allowed.
• Thousand separator is not supported.
• Scientific notation is not supported (use Number::string() method to cast very big or small float numbers to numeric string without scientific notation).

For example "1234567.89" is allowed while "1,234,567.89" is not.

Notes

* Consideration on modulo operation

As already pointed by krowinsky in PHP issue #76287

bcmod() doesn't use floor() but rather truncates towards zero,
which is also defined this way for POSIX fmod(), so that the
result always has the same sign as the dividend.  Therefore, this
is not a bug, but rather a documentation issue.

the modulo operation in BCMath extension is not correct in case the modulus is negative. Therefore in this library the following formula is used:

$$ a \pmod n = a - n \times \left \lfloor {\dfrac{a}{n}} \right \rfloor $$

With this formula a negative modulus $n$ is allowed.

** Consideration on float type

If you need to convert a float to Number and back, prepare for the worst. Keep in mind that floating point arithmetic is full of hidden flaws, that's why aribtrary arithmetic is needed (in this case implemented by BcMath PHP extension).

While this library accept a float type input, it is not recommended to cast a Number instance to float, otherwise nasty things could happen.

Use this library only for end calculations, like print a report. If other subsystem of your software need float type inputs, it is strongly advised to avoid this library for intermediate calculations.

API documentation

You can find the API documentation at docs/html/index.html.