rgzone/bignum

Arbitrary precision integer PHP extension backed by Rust.

dev-master 2026-06-02 14:38 UTC

Requires

• php: >=8.3

Provides

• ext-bignum: 0.1.0

MIT

Extension name: ext-bignum

Supports Zend Thread Safety (ZTS): ✅

Supports non-Thread Safe mode (NTS): ✅

Supported operating systems: no restrictions

README

Arbitrary-precision integer support for PHP 8.3+, implemented as a native extension backed by Rust.

The extension exposes two immutable-friendly integer classes:

• RGZ\BigNum\IntegerSigned
• RGZ\BigNum\IntegerUnsigned

Both implement RGZ\BigNum\IntegerInterface.

Features

• Arbitrary-precision signed integers
• Arbitrary-precision unsigned integers
• Arithmetic operations on large values
• Bitwise operations
• Comparisons
• String-based API with strict input validation
• Native PHP extension packaging via PIE

Requirements

• PHP >= 8.3
• A working C build toolchain for PHP extensions
• Rust toolchain for local builds
• cargo
• PIE to install from the package repository

Install With PIE

The published package name is rgzone/bignum on Packagist:

• https://packagist.org/packages/rgzone/bignum

Given the package metadata in this repository (type: php-ext and extension name bignum), the install flow is:

pie install rgzone/bignum

Then enable the extension if PIE does not do it automatically in your environment:

extension=bignum

Verify the installation:

php -m | grep bignum

Note: the pie install rgzone/bignum command is inferred from the package name in this repository and the published Packagist package URL above.

API Overview

RGZ\BigNum\IntegerSigned

Construct from a decimal string:

<?php

declare(strict_types=1);

use RGZ\BigNum\IntegerSigned;

$value = new IntegerSigned('-12345678901234567890');

RGZ\BigNum\IntegerUnsigned

Construct from a non-negative decimal string:

<?php

declare(strict_types=1);

use RGZ\BigNum\IntegerUnsigned;

$value = new IntegerUnsigned('12345678901234567890');

Negative input for IntegerUnsigned is rejected.

Supported operations

Both classes support:

• copy()
• add(), addInPlace()
• subtract(), subtractInPlace()
• multiply(), multiplyInPlace()
• divide(), divideInPlace()
• modulo(), moduloInPlace()
• raiseToPower()
• bitAnd(), bitAndInPlace()
• bitOr(), bitOrInPlace()
• bitXor(), bitXorInPlace()
• invertBits()
• shiftLeft(), shiftLeftInPlace()
• shiftRight(), shiftRightInPlace()
• compare()
• equals()
• lessThan()
• lessThanOrEqual()
• greaterThan()
• greaterThanOrEqual()
• isZero()
• __toString()

Binary operands must be either:

• a decimal string
• another RGZ\BigNum\IntegerInterface

Example

<?php

declare(strict_types=1);

use RGZ\BigNum\IntegerSigned;
use RGZ\BigNum\IntegerUnsigned;

$a = new IntegerSigned('-10');
$b = new IntegerSigned('3');

echo $a->add($b), PHP_EOL;          // -7
echo $a->multiply('12'), PHP_EOL;   // -120
echo $a->shiftLeft(4), PHP_EOL;     // -160

$u = new IntegerUnsigned('200');
echo $u->add('55'), PHP_EOL;        // 255
echo $u->invertBits(16), PHP_EOL;   // 65280

Local Development

Build in Docker playground

This repository includes a Docker-based playground for manual testing.

Start an interactive shell in the prepared container:

task playground:shell

Build the image and install playground dependencies:

task playground:build

Run the test suite in the playground container:

task playground:tests

What the playground does

The playground container:

• builds the extension with PIE
• enables bignum
• mounts sources/playground into /srv/app
• keeps the container alive in the dev override so you can exec into it

Project Layout

• sources/extension Rust extension source
• sources/playground Minimal PHP project used for manual checks and PHPUnit tests
• docker/php/Dockerfile Builder and playground image definition
• Taskfile.dist.yml Development tasks

Testing

PHPUnit tests live under:

• sources/playground/tests

They cover:

• arithmetic behavior
• bitwise behavior
• long-number cases via data providers
• invalid argument handling
• unsigned rejection of negative values

License

MIT. See LICENSE.