A PHP library to work with arbitrary precision numbers.
This library is installable via Composer:
composer require brick/math
This library requires PHP 7.1 or later.
For PHP 5.6 and PHP 7.0 compatibility, use version
0.5: this version will still be supported until 31 December 2018, when support for PHP 5.6 and 7.0 will be definitely dropped. It will not receive any new features, but will be patched if any bugs are found.
Although the library can work seamlessly on any PHP installation, it is highly recommended that you install the GMP or BCMath extension to speed up calculations. The fastest available calculator implementation will be automatically selected at runtime.
Project status & release process
While this library is still under development, it is well tested and should be stable enough to use in production environments.
The current releases are numbered
0.x.y. When a non-breaking change is introduced (adding new methods, optimizing
existing code, etc.),
y is incremented.
When a breaking change is introduced, a new
0.x version cycle is always started.
It is therefore safe to lock your project to a given release cycle, such as
If you need to upgrade to a newer release cycle, check the release history
for a list of changes introduced by each further
This library provides the following public classes in the
- BigNumber: base class for
- BigInteger: represents an arbitrary-precision integer number.
- BigDecimal: represents an arbitrary-precision decimal number.
- BigRational: represents an arbitrary-precision rational number (fraction).
- RoundingMode: holds constants for the rounding modes.
And the following exceptions in the
- MathException: base class for all exceptions
- DivisionByZeroException: thrown when a division by zero occurs
- IntegerOverflowException: thrown when attempting to convert a too large
- NumberFormatException: thrown when parsing a number string in an invalid format
- RoundingNecessaryException: thrown when the result of the operation cannot be represented without explicit rounding
- NegativeNumberException: thrown when attempting to calculate the square root of a negative number
The constructors of the classes are not public, you must use a factory method to obtain an instance.
All classes provide an
of() factory method that accepts any of the following types:
stringrepresentations of integer, decimal and rational numbers
BigInteger::of(123546); BigInteger::of('9999999999999999999999999999999999999999999'); BigDecimal::of(1.2); BigDecimal::of('9.99999999999999999999999999999999999999999999'); BigRational::of('2/3'); BigRational::of('1.1'); // 11/10
Note that all
of() methods accept all of the representations above, as long as it can be safely converted to
the current type:
BigInteger::of('1.00'); // 1 BigInteger::of('1.01'); // MathException BigDecimal::of('1/8'); // 0.125 BigDecimal::of('1/3'); // MathException
Note about native integers: instantiating from an
int is safe as long as you don't exceed the maximum
value for your platform (
PHP_INT_MAX), in which case it would be transparently converted to
float by PHP without
notice, and could result in a loss of information. In doubt, prefer instantiating from a
string, which supports
an unlimited numbers of digits:
echo BigInteger::of(999999999999999999999); // 1000000000000000000000 echo BigInteger::of('999999999999999999999'); // 999999999999999999999
Note about floating-point values: instantiating from a
float might be unsafe, as floating-point values are
imprecise by design, and could result in a loss of information. Always prefer instantiating from a
supports an unlimited number of digits:
echo BigDecimal::of(1.99999999999999999999); // 2 echo BigDecimal::of('1.99999999999999999999'); // 1.99999999999999999999
Immutability & chaining
BigRational classes are immutable: their value never changes,
so that they can be safely passed around. All methods that return a
return a new object, leaving the original object unaffected:
$ten = BigInteger::of(10); echo $ten->plus(5); // 15 echo $ten->multipliedBy(3); // 30
The methods can be chained for better readability:
echo BigInteger::of(10)->plus(5)->multipliedBy(3); // 45
All methods that accept a number:
multipliedBy(), etc. accept the same types as
For example, given the following number:
$integer = BigInteger::of(123);
The following lines are equivalent:
$integer->multipliedBy(123); $integer->multipliedBy('123'); $integer->multipliedBy($integer);
of(), other types of
BigNumber are acceptable, as long as they can be safely converted to the current type:
echo BigInteger::of(2)->multipliedBy(BigDecimal::of('2.0')); // 4 echo BigInteger::of(2)->multipliedBy(BigDecimal::of('2.5')); // MathException echo BigDecimal::of(2.5)->multipliedBy(BigInteger::of(2)); // 5.0
Division & rounding
By default, dividing a
BigInteger returns the exact result of the division, or throws an exception if the remainder
of the division is not zero:
echo BigInteger::of(999)->dividedBy(3); // 333 echo BigInteger::of(1000)->dividedBy(3); // RoundingNecessaryException
You can pass an optional rounding mode to round the result, if necessary:
echo BigInteger::of(1000)->dividedBy(3, RoundingMode::DOWN); // 333 echo BigInteger::of(1000)->dividedBy(3, RoundingMode::UP); // 334
If you're into quotients and remainders, there are methods for this, too:
echo BigInteger::of(1000)->quotient(3); // 333 echo BigInteger::of(1000)->remainder(3); // 1
You can even get both at the same time:
[$quotient, $remainder] = BigInteger::of(1000)->quotientAndRemainder(3);
BigDecimal always requires a scale to be specified. If the exact result of the division does not fit in
the given scale, a rounding mode must be provided.
echo BigDecimal::of(1)->dividedBy('8', 3); // 0.125 echo BigDecimal::of(1)->dividedBy('8', 2); // RoundingNecessaryException echo BigDecimal::of(1)->dividedBy('8', 2, RoundingMode::HALF_DOWN); // 0.12 echo BigDecimal::of(1)->dividedBy('8', 2, RoundingMode::HALF_UP); // 0.13
If you know that the division yields a finite number of decimals places, you can use
exactlyDividedBy(), which will
automatically compute the required scale to fit the result, or throw an exception if the division yields an infinite
echo BigDecimal::of(1)->exactlyDividedBy(256); // 0.00390625 echo BigDecimal::of(1)->exactlyDividedBy(11); // RoundingNecessaryException
The result of the division of a
BigRational can always be represented exactly:
echo BigRational::of('123/456')->dividedBy('7'); // 123/3192 echo BigRational::of('123/456')->dividedBy('9/8'); // 984/4104
BigInteger supports bitwise operations:
and bit shifting:
BigRational can be safely serialized on a machine and unserialized on another,
even if these machines do not share the same set of PHP extensions.
For example, serializing on a machine with GMP support and unserializing on a machine that does not have this extension installed will still work as expected.