Alphanum for PHP

A blazing fast, zero-dependency PHP library for converting decimal numbers into alphanumeric formats (Sexagesimal Base-60, Base62, Base58, Base36, and custom alphabets) and vice versa.

Supports PHP 7.4 through PHP 8.5+, BigInt / arbitrary-precision integers, output padding, validation, and instance & static APIs.

---

🚀 Features

• Backwards-Compatible: Seamless drop-in replacement for v0.1 with original sexagesimal encoding preserved.
• High Performance: $O(1)$ cached inverted lookup tables and optimized loop operations (~3M ops/sec).
• Multiple Bases & Custom Alphabets: Built-in support for Sexagesimal (Base 60), Base62, Base58 (Bitcoin style), Base36, or any custom character set.
• BigInt Support: Easily handles numbers exceeding 64-bit PHP_INT_MAX (e.g. Snowflake IDs, UUIDs, 128-bit numbers) using GMP, BCMath, or a pure-PHP fallback.
• Padding & Min Length: Generate fixed-width or padded alphanumeric strings for link shorteners.
• Validation: Fast validation methods to verify format integrity before decoding.
• Flexible API: Clean static methods and configurable Object-Oriented instances.

---

📦 Installation

Install via Composer:

composer require nabeghe/alphanum

---

🫡 Usage

1. Basic (Default Character Set)

By default, Alphanum uses its standard character set containing digits 0-9, uppercase A-Z, lowercase a-z, and _ (63 characters):

use Nabeghe\Alphanum\Alphanum;

// Encoding
echo Alphanum::generate(0);            // 0
echo Alphanum::generate(1);            // 1
echo Alphanum::generate(10);           // A
echo Alphanum::generate(24);           // O
echo Alphanum::generate(62);           // _
echo Alphanum::generate(63);           // 10
echo Alphanum::generate(100);          // 1b

// Decoding
echo Alphanum::toDecimal('0');         // 0
echo Alphanum::toDecimal('1');         // 1
echo Alphanum::toDecimal('A');         // 10
echo Alphanum::toDecimal('O');         // 24
echo Alphanum::toDecimal('_');         // 62
echo Alphanum::toDecimal('10');        // 63
echo Alphanum::toDecimal('1b');        // 100

(Note: Alphanum::encode($number) is also available as an alias for Alphanum::generate($number)).

---

2. Predefined & Custom Alphabets

You can use standard built-in alphabets or provide your own:

use Nabeghe\Alphanum\Alphanum;

// Base60 Sexagesimal
$encoded60 = Alphanum::generate(1403, Alphanum::BASE60); // NN
$decoded60 = Alphanum::toDecimal('NN', Alphanum::BASE60); // 1403

// Base62 (0-9, A-Z, a-z)
$encoded62 = Alphanum::generate(123456789, Alphanum::BASE62);
$decoded62 = Alphanum::toDecimal($encoded62, Alphanum::BASE62);

// Base58 (Bitcoin style: excludes 0, O, I, l to prevent visual confusion)
$encoded58 = Alphanum::generate(987654321, Alphanum::BASE58);
$decoded58 = Alphanum::toDecimal($encoded58, Alphanum::BASE58);

// Base36 (0-9, a-z - case insensitive)
$encoded36 = Alphanum::generate(1000000, Alphanum::BASE36);
$decoded36 = Alphanum::toDecimal($encoded36, Alphanum::BASE36);

// Custom alphabet (e.g. Hexadecimal or custom shuffled charset)
$customAlphabet = '0123456789abcdef';
$hex = Alphanum::generate(255, $customAlphabet); // ff

---

3. BigInt / Arbitrary-Precision Numbers

When dealing with IDs that exceed 64-bit integer limits (PHP_INT_MAX), pass the number as a numeric string. The library automatically leverages GMP or BCMath if available, or falls back to an internal pure-PHP arbitrary-precision algorithm:

use Nabeghe\Alphanum\Alphanum;

$bigId = '123456789012345678901234567890';

// Encode large decimal string
$shortCode = Alphanum::generate($bigId);

// Decode back to arbitrary-precision decimal string
$restoredBigId = Alphanum::toBigDecimal($shortCode);
echo $restoredBigId; // '123456789012345678901234567890'

// Auto-decoder: returns int if it fits in PHP_INT_MAX, or string if it exceeds
$val = Alphanum::decode($shortCode);

---

4. Padding & Minimum Length

Useful for URL shorteners to ensure generated codes have a consistent minimum length:

use Nabeghe\Alphanum\Alphanum;

// Pad to at least 6 characters (padded with '0' by default)
echo Alphanum::generate(5, null, 6); // '000005'

// Custom pad character
echo Alphanum::generate(10, null, 6, 'X'); // 'XXXXXA'

// Manual pad / unpad helpers
echo Alphanum::pad('1f', 6, '0');    // '00001f'
echo Alphanum::unpad('00001f', '0'); // '1f'

---

5. String Validation

Validate whether an input string is composed strictly of characters belonging to the active alphabet and base:

use Nabeghe\Alphanum\Alphanum;

Alphanum::isValid('1f');                     // true
Alphanum::isValid('1f!@#');                  // false
Alphanum::isValid('zO', Alphanum::BASE62);   // true

---

6. Object-Oriented Instance API

Create configured instances to avoid repeating arguments:

use Nabeghe\Alphanum\Alphanum;

$shortener = new Alphanum(Alphanum::BASE58, 6, '1');

$code = $shortener->encodeNumber(42);  // '11111k'
$num  = $shortener->decodeToInt($code); // 42

$isValid = $shortener->validate($code); // true
echo $shortener->getBase();             // 58

---

🧪 Testing

Run the test suite with PHPUnit:

composer test

Tested and verified across PHP 7.4, 8.0, 8.1, 8.2, 8.3, 8.4, and 8.5.

---

📖 License

Licensed under the MIT license, see LICENSE.md for details.