README

RGZ BigNum

A PHP extension that provides arbitrary-precision signed and unsigned integer support by building a native PHP API on top of the Rust num-bigint crate.

The extension exposes two immutable-friendly integer classes:

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

Both implement RGZ\BigNum\IntegerInterface.

Installation

You can install this extension using PIE:

pie install rgzone/bignum

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.1
• installed Rust toolchain
• cargo
• PIE

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

extension=bignum

Verify the installation:

php -m | grep bignum

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
• an int
• 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->add(3), 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->add('55'), PHP_EOL;        // 255
echo $u->invertBits(16), PHP_EOL;   // 65280

Local Development

Development is centered around the Docker playground and task targets from Taskfile.dist.yml.

Open a playground shell

Start an interactive shell with the extension built and enabled:

task play:console

This target:

• builds the playground service
• starts the container in the background
• opens bash inside it

With the development compose override, sources/playground is mounted into /srv/app.

Rebuild the playground from scratch

Rebuild the playground image without cache, start it, and install playground dependencies:

task play:buildup

Run tests

Run the PHPUnit suite for the current environment:

task play:phpunit

Run the full PHP version matrix defined in the repository:

task play:pipeline

Supported matrix targets are:

• current
• php81
• php82
• php83
• php84
• php85

You can also run a single target explicitly:

task play:phpunit EXTRA_ENV=php84

Project Layout

• sources/extension Rust extension source
• sources/playground Minimal PHP project used for manual checks and PHPUnit tests
• sources/playground/Dockerfile Docker image definition for the playground, local builds, and test runs
• 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