Math Biginteger Laravel Package

Getting Started

pear/math_biginteger is a single-class PEAR library (Math_BigInteger) for arithmetic on integers larger than PHP_INT_MAX. It is archived and unmaintained — treat it as a fallback, not a foundation.

1. Install (may fail on modern Laravel/PHP):

   composer require pear/math_biginteger
   

   If Composer resolution fails, the whole library is one file. Download Math/BigInteger.php into app/Support/ and require_once it. There is no PSR-4 namespace — the class is literally Math_BigInteger.

2. First place to look: the constructor and the method list in Math/BigInteger.php. Everything routes through it; there is no config, service provider, or facade.

3. First use case — values that overflow PHP ints (snowflake IDs, wei amounts, large counters, crypto math):

   require_once base_path('app/Support/Math/BigInteger.php');
   
   $a = new Math_BigInteger('123456789012345678901234567890');
   $b = new Math_BigInteger('98765432109876543210');
   
   $a->add($b)->toString();        // '123456789012345678901234567891'
   (new Math_BigInteger('ff', 16))->toString(); // '255'
   

Pass strings to the constructor, never raw PHP ints that have already overflowed.

Implementation Patterns

Isolate it behind a value object. Don't let Math_BigInteger leak into controllers or Blade. Wrap it:

final class BigInt
{
    private function __construct(public readonly Math_BigInteger $v) {}

    public static function of(string|int $n, int $base = 10): self
    {
        return new self(new Math_BigInteger((string) $n, $base));
    }

    public function add(self $o): self { return new self($this->v->add($o->v)); }
    public function toString(): string { return $this->v->toString(); }
}

Typical day-to-day workflows:

• Opaque ID generation — Math_BigInteger::random(128) (or randomRange) for tokens/IDs you don't want as sequential ints.
• Crypto primitives — modPow() and modInverse() are the reason many devs reach for this class (RSA-style operations, DH-style schemes). Wrap them in a Crypto service; never inline.
• Base conversion — new Math_BigInteger($hex, 16)->toString() and ->toHex() / ->toBytes() for encoding boundary work.
• Aggregations on integer strings — sum balances stored as strings in SQL to avoid float drift in a queued job.

Laravel integration tips:

• Bind a small service in AppServiceProvider if used in more than one place.
• Store results back to the DB as strings (decimal(65,0)), never cast to float.
• Use it inside queued jobs, not request threads — pure-PHP math is slow.
• If you're on a modern Laravel, prefer brick/math (Composer-native, PSR-4, actively maintained) for decimal arithmetic, and phpseclib/phpseclib (\phpseclib3\Math\BigInteger) for crypto. Both are drop-in replacements with better ergonomics.

Gotchas and Tips

• Archived = frozen. Expect PHP 8.1+ deprecation notices, and no typed properties, no return types. If you must run it, pin php in composer.json and silence deprecations in tests, not production.
• No autoloading. Math_BigInteger is a PEAR-underscore class. You'll need require_once, an include-path entry, or a classmap in composer.json. Conflicts arise if another package ships a class with the same name.
• Constructor input is fragile. new Math_BigInteger(1.5e30) loses precision before the class ever sees it. Always pass strings; validate with a regex.
• Don't use ==, <, > on instances. Use ->compare($other) which returns -1|0|1. Object comparison operators in PHP compare properties and give wrong answers.
• Modulo/divide sign handling is a classic source of bugs with negatives — write a test for each sign combination before shipping.
• Performance: with GMP or BCMath loaded, the class delegates to the extension. Without them it's pure PHP and multiply/divide are quadratic — a 2048-bit modPow loop in a request will time out. Detect extensions at boot:

  $engine = extension_loaded('gmp') ? 'gmp' : (extension_loaded('bcmath') ? 'bcmath' : 'php');
  

  Log the engine; it's the #1 cause of "it worked in dev, not prod."
• No exceptions on bad input. Malformed bases or strings can produce 0 or silent garbage. Validate inputs at the boundary and assert with ->toString() round-trips in tests.
• Serialization is unsafe. Don't serialize Math_BigInteger into cache or queues — store ->toString() and reconstruct. Objects don't survive version upgrades cleanly.
• Extension points are thin. Subclassing to add helpers works, but that's the entire surface. If you need fluent chains, comparisons, or decimal (non-integer) math, switch libraries instead of wrapping.
• Debugging tip: dump ->toString() and ->toHex() side by side; almost every bug is a base mismatch (decimal string fed into a base-16 constructor, etc.).
• Migration path: brick/math's BigInteger and phpseclib3's BigInteger both cover the same API surface with cleaner code, autoloading, and maintained releases. Plan the swap before this becomes load-bearing.