pugx / shortid-php
An implementation of shortid in PHP
Requires
- php: ^8.1
- paragonie/random-lib: ^2.0
- symfony/polyfill-mbstring: ^1.19
Requires (Dev)
- dg/bypass-finals: ^1.3
- phpunit/phpunit: ^9.6
README
This library is an implementation of ShortId for PHP.
Installation
Install the library via Composer:
composer require pugx/shortid-php
Usage
ShortId is a PHP library that generates short, unique, and random strings. It's useful in scenarios where you need concise identifiers, such as URL shortening or generating unique keys.
Basic usage
Just call PUGX\Shortid\Shortid::generate()
to get a random string with default length 7, like "MfiYIvI".
use PUGX\Shortid\Shortid; require_once __DIR__.'/vendor/autoload.php'; $id = Shortid::generate();
Advanced usage
For more control, you can customize the alphabet and length using the Factory class.
The default alphabet uses all letters (lowercase and uppercase), all numbers, underscore, and hyphen.
use PUGX\Shortid\Factory; use PUGX\Shortid\Shortid; require_once __DIR__.'/vendor/autoload.php'; $factory = new Factory(); // alphabet string must be 64 characters long $factory->setAlphabet('é123456789àbcdefghìjklmnòpqrstùvwxyzABCDEFGHIJKLMNOPQRSTUVWX.!@|'); // length must be between 2 and 20 (default is 7) // of course, a lower length increases the clashing probability $factory->setLength(9); Shortid::setFactory($factory); $id = Shortid::generate();
As an alternative, you can customize single generations:
use PUGX\Shortid\Shortid; require_once __DIR__.'/vendor/autoload.php'; $id9 = Shortid::generate(9, 'é123456789àbcdefghìjklmnòpqrstùvwxyzABCDEFGHIJKLMNOPQRSTUVWX.!@|'); $id5 = Shortid::generate(5);
More readable strings
Sometimes, you want to avoid some ambiguous characters, like B
/8
or I
/l
(uppercase/lowercase).
In this case, you can pass a third parameter true
to generate
method. Notice that in this case the alphabet
will be ignored, so it makes sense to pass a null one.
Example:
use PUGX\Shortid\Shortid; require_once __DIR__.'/vendor/autoload.php'; $id = Shortid::generate(7, null, true);
Pre-defined values
If you need a deterministic string, instead of a random one, you can call directly the class constructor. This could be useful, for instance, when you need pre-defined data for testing purposes.
use PUGX\Shortid\Shortid; require_once __DIR__.'/vendor/autoload.php'; $myFixedId = new Shortid('5h0r71d'); $anotherFixedId = new Shortid('fooBarZ');
Doctrine
If you want to use ShortId with Doctrine ORM, take a look at ShortId Doctrine type.
Doctrine and Symfony
If you want to use ShortId with Doctrine ORM and Symfony framework, take a look to ShortId Doctrine type bundle.
Dependencies replacement
This library uses a polyfill, so it can be used in environments where the mbstring native extension is not available.
If, instead, your environment is offering that extension, you can avoid installing
that polyfill by configuring a replace entry in your composer.json
.
The same applies to the randomLib library: if you are using PHP 8.3 or higher,
you can replace it, since this library uses the native Random
class instead.
Contributing
Contributions are welcome. Feel free to open a Pull Request or file an issue here on GitHub! Please read the contributing guidelines first.