README

This library implements Base32 encoding. In addition to integers it can encode and decode any arbitrary data.

Install

Install with composer.

$ composer require tuupola/base32

This branch requires PHP 7.1 or up. The older 1.x branch supports also PHP 5.6 and 7.0.

$ composer require "tuupola/base32:^1.0"

Usage

This package has both pure PHP and GMP based encoders. By default encoder and decoder will use GMP functions if the extension is installed. If GMP is not available pure PHP encoder will be used instead.

$base32 = new Tuupola\Base32;

$encoded = $base32->encode(random_bytes(128));
$decoded = $base32->decode($encoded);

If you are encoding to and from integer use the implicit decodeInteger() and encodeInteger() methods.

$integer = $base32->encodeInteger(987654321); /* 5N42FR== */
print $base32->decodeInteger("5N42FR=="); /* 987654321 */

Also note that encoding a string and an integer will yield different results.

$integer = $base32->encodeInteger(987654321); /* 5N42FR== */
$string = $base32->encode("987654321"); /* FHE4DONRVGQZTEMI= */

Encoding Modes

RCF4684

RCF4684 is the default when encoder is created without passing any parameters. Explicit parameters shown below.

use Tuupola\Base32;

$base32 = new Base32([
    "characters" => Base32::RFC4648,
    "padding" => "="
]);

print $base32->encode("Hello world!"); /* JBSWY3DPEB3W64TMMQQQ==== */

RCF4684 HEX

RCF4684 base32hex encoding is identical to previous, except for the character set. This encoding is lexically sortable.

$base32hex = new Base32([
    "characters" => Base32::HEX,
    "padding" => "="
]);

print $base32->encode("Hello world!"); /* 91IMOR3F41RMUSJCCGGG==== */

GMP

GMP encoding is identical to previous. Example below is shown with padding disabled.

$gmp = new Base32([
    "characters" => Base32::GMP,
    "padding" => false
]);

print $gmp->encode("Hello world!"); /* 91IMOR3F41RMUSJCCGGG */

Crockford's Base32

When decoding, upper and lower case letters are accepted, and i and l will be treated as 1 and o will be treated as 0. When encoding, only upper case letters are used. Hyphens are ignored during decoding.

$crockford = new Base32([
    "characters" => Base32::CROCKFORD,
    "padding" => false,
    "crockford" => true,
]);

print $crockford->encode("Hello world!"); /* 91JPRV3F41VPYWKCCGGG */
print $crockford->decode("91JPRV3F41VPYWKCCGGG"); /* Hello world! */
print $crockford->decode("91jprv3f41vpywkccggg"); /* Hello world! */
print $crockford->decode("9ljprv3f4lvpywkccggg"); /* Hello world! */

Z-base-32 [WIP]

http://philzimmermann.com/docs/human-oriented-base-32-encoding.txt

Character Sets

By default Base32 uses RFC4648 character set. Shortcut is provided for other commonly used character sets. You can also use any custom character set of 32 unique characters.

use Tuupola\Base32;

print Base32::CROCKFORD; /* 0123456789ABCDEFGHJKMNPQRSTVWXYZ */
print Base32::RFC4648; /* ABCDEFGHIJKLMNOPQRSTUVWXYZ234567 */
print Base32::ZBASE32; /* ybndrfg8ejkmcpqxot1uwisza345h769 */
print Base32::GMP; /* 0123456789ABCDEFGHIJKLMNOPQRSTUV */
print Base32::HEX; /* 0123456789ABCDEFGHIJKLMNOPQRSTUV */

$default = new Base32(["characters" => Base32::RFC4648]);
$crockford = new Base32(["characters" => Base32::CROCKFORD]);
print $default->encode("Hello world!"); /* JBSWY3DPEB3W64TMMQQQ==== */
print $inverted->encode("Hello world!"); /* 91JPRV3F41VPYWKCCGGG==== */

Speed

Install GMP if you can. It is reasonably faster pure PHP encoder. Below benchmarks are for encoding random_bytes(128) data.

$ make benchmark

benchmark: Base32Bench
+-----------------------+----------------+-------+
| subject               | mean           | diff  |
+-----------------------+----------------+-------+
| benchGmpEncoder       | 8,361.204ops/s | 1.00x |
| benchGmpEncoderCustom | 8,393.487ops/s | 1.00x |
| benchPhpEncoder       | 6,881.365ops/s | 1.22x |
+-----------------------+----------------+-------+

Static Proxy

If you prefer to use static syntax use the provided static proxy.

use Tuupola\Base32Proxy as Base32;

$encoded = Base32::encode(random_bytes(128));
$decoded = Base32::decode($encoded);

Testing

You can run tests either manually or automatically on every code change. Automatic tests require entr to work.

$ make test

$ brew install entr
$ make watch

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email tuupola@appelsiini.net instead of using the issue tracker.

License

The MIT License (MIT). Please see License File for more information.