gogh-idawoodjee/shortcode

Encode integers and UUIDs to short, URL-safe Base62 strings and back.

v1.0.0 2026-05-26 21:56 UTC

Requires

• php: ^8.2
• ext-bcmath: *

Requires (Dev)

• pestphp/pest: ^3.0

MIT

• Ish Dawoodjee

• encoder
• uuid
• shortcode
• base62
• short-url

README

Encode integers and UUIDs to short, URL-safe Base62 strings and back.

Turn 550e8400-e29b-41d4-a716-446655440000 into 5mSYFjfBLkNseKP0tQ8y0w and back again losslessly.

Encoding	Characters	UUID length
Hex (raw UUID)	0-9, a-f	32 chars
Base64	A-Z, a-z, 0-9, +, /	22 chars (needs padding/escaping)
Base62	A-Z, a-z, 0-9	~22 chars (URL-safe, no escaping)

Base62 gives you near-optimal compression while staying alphanumeric — no +, /, =, or %-encoding needed.

Installation

composer require gogh-idawoodjee/shortcode

Requires PHP 8.2+ and the bcmath extension.

Usage

Integers

use GoghIdawoodjee\ShortCode\ShortCode;

ShortCode::encode(123456);    // "W7E"
ShortCode::decode('W7E');     // 123456

UUIDs

$uuid = '550e8400-e29b-41d4-a716-446655440000';

$short = ShortCode::encodeUuid($uuid);  // "5mSYFjfBLkNseKP0tQ8y0w"
$back  = ShortCode::decodeUuid($short); // "550e8400-e29b-41d4-a716-446655440000"

UUIDs with or without dashes are both accepted. The output is always alphanumeric so it's safe for URLs, filenames, and QR codes.

Laravel Facade

A Laravel facade is included and auto-discovered — no manual registration needed.

use GoghIdawoodjee\ShortCode\Facades\ShortCode;

ShortCode::encodeUuid($uuid);
ShortCode::decodeUuid($code);

Error Handling

All methods throw InvalidArgumentException on bad input:

ShortCode::encode(-1);           // negative number
ShortCode::decode('abc!');       // invalid character
ShortCode::encodeUuid('nope');   // not a valid UUID

Testing

composer test

License

MIT