Base62

PHP encoder and decoder for arbitrary data

Base62 is an url safe way of encoding data. This is useful for example for generating random tokens which are going to be included in a web address.

GitHub stars Latest Version Software License Build Status HHVM Status Coverage

Install

Install with composer.

$ composer require tuupola/base62

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.

$base62 = new Tuupola\Base62;

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

Note that if you are encoding to and from integer you need to pass boolean true as the second argument for decode() method. This is because decode() method does not know if the original data was an integer or binary data.

$integer = $base62->encode(987654321); /* 14q60P */
print $base62->decode("14q60P", true); /* 987654321 */

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

$integer = $base62->encode(987654321); /* 14q60P */
$string = $base62->encode("987654321"); /* KHc6iHtXW3iD */

Character sets

By default Base62 uses GMP style character set. Shortcut is provided for the inverted character set which is also commonly used. You can also use any custom character set of 62 unique characters.

use Tuupola\Base62;

print Base62:GMP; /* 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz */
print Base62:INVERTED; /* 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ */

$default = new Base62(["characters" => Base62:GMP]);
$inverted = new Base62(["characters" => Base62:INVERTED]);
print $default->encode("Hello world!");/* T8dgcjRGuYUueWht */
print $inverted->encode("Hello world!"); /* t8DGCJrgUyuUEwHT */

Speed

Install GMP if you can. It is much faster pure PHP encoder. Below benchmarks are for encoding random_bytes(128) data. BCMatch encoder is also included but it is mostly just a curiosity. It is too slow to be usable.

$ phpbench run benchmarks/ --report=default

+-----------------------+-----------------+----------------+
| subject               | mean            | diff           |
+-----------------------+-----------------+----------------+
| benchGmpEncoder       | 73,099.415ops/s | 0.00%          |
| benchGmpEncoderCustom | 61,349.693ops/s | +19.15%        |
| benchPhpEncoder       | 25.192ops/s     | +290,072.37%   |
| benchBcmathEncoder    | 7.264ops/s      | +1,006,253.07% |
+-----------------------+-----------------+----------------+

Why yet another Base62 encoder?

Because all encoders I found were encoders only for integer numbers. I needed to be able to encode arbitrary data. This is usefull for example when generating url safe random tokens for database identifiers.

$token = $base62->encode(random_bytes(9));

Static Proxy

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

use Tuupola\Base62Proxy as Base62;

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

Short UUID

If you are already using UUIDs they can be encoded.

use Ramsey\Uuid\Uuid;
use Tuupola\Base62Proxy as Base62;

$uuid = Uuid::fromString("d84560c8-134f-11e6-a1e2-34363bd26dae");
Base62::encode($uuid->getBytes()); /* 6a630O1jrtMjCrQDyG3D3O */
$uuid = Uuid::fromBytes(Base62::decode("6a630O1jrtMjCrQDyG3D3O"));
print $uuid; /* d84560c8-134f-11e6-a1e2-34363bd26dae */

Testing

You can run tests either manually...

$ composer test

... or automatically on every code change. This requires entr to work.

$ composer watch

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

License

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