nanoid-php Documentation

To add Nanoid-php to your PHP project, use Composer to require the package.

composer require hidehalo/nanoid-php

Use the formattedId method to specify a custom alphabet and length.

Important: The alphabet must contain 256 symbols or less to ensure the generator remains secure.

$client = new Hidehalo\Nanoid\Client();

// Custom alphabet and size
echo $client->formattedId($alphabet = '0123456789abcdefg', $size = 21);

The Hidehalo\Nanoid\Client provides two modes for generating IDs using the default URL-friendly alphabet (A-Za-z0-9_-) and a default length of 21 characters (matching UUID v4 collision probability).

• Default mode: Uses the standard random generator.
• Client::MODE_DYNAMIC: A more secure random generator mode.

use Hidehalo\Nanoid\Client;

$client = new Client();

// default random generator
echo $client->generateId($size = 21);

// more safer random generator
echo $client->generateId($size = 21, $mode = Client::MODE_DYNAMIC);

You can provide your own randomness logic by implementing the GeneratorInterface and passing it to formattedId. The random method must accept the requested $size and return an array of random numbers.

This is useful if you need to control the source of entropy or use a specific random number generation algorithm.

use Hidehalo\Nanoid\Client;
use Hidehalo\Nanoid\GeneratorInterface;

$client = new Client();

echo $client->formattedId(
    $alphabet = '0123456789abcdefg', 
    $size = 21, 
    new class implements GeneratorInterface {
        /**
         * @inheritDoc
         */
        public function random($size)
        {
            // Your implementation returning an array of random numbers
        }
    }
);

If you need to use a specific set of characters (alphabet) or a specific generator for a single ID generation, use formattedId. This method bypasses the client's default alphabet and generator settings for that specific call.

Note: If you are migrating from version 1.0.0, formatedId (with one 't') is available as a backwards-compatible alias.

use Hidehalo\Nanoid\Client;

$client = new Client();
$customAlphabet = '0123456789ABCDEF';

// Generate an ID with a custom alphabet and size
$id = $client->formattedId($customAlphabet, 10);

// Generate an ID with custom alphabet, size, and a custom generator
$id = $client->formattedId($customAlphabet, 10, $myCustomGenerator);

The Hidehalo\Nanoid\Client class is the primary entry point for generating NanoID strings. You can instantiate it with a default size of 21 or provide a custom size and a custom GeneratorInterface implementation.

By default, the client uses a standard generator and the CoreInterface::SAFE_SYMBOLS alphabet.

use Hidehalo\Nanoid\Client;

// Default client (size 21)
$client = new Client();
$id = $client->generateId();

// Client with custom size
$client = new Client(10);
$id = $client->generateId();

The generateId method allows you to choose between two generation modes:

1. Client::MODE_NORMAL (Default): Uses a standard random algorithm.
2. Client::MODE_DYNAMIC: Uses the Core engine for dynamic random generation.

You can also override the $size for a specific call. If $size is 0 or less, the client uses the size defined during instantiation.

use Hidehalo\Nanoid\Client;

$client = new Client(21);

// Normal mode (default)
$id = $client->generateId();
$id = $client->generateId(0, Client::MODE_NORMAL);

// Dynamic mode
$id = $client->generateId(0, Client::MODE_DYNAMIC);

// Custom size for this specific call
$id = $client->generateId(12, Client::MODE_NORMAL);

The Client class defines the following constants for controlling the generation mode in generateId():

• Client::MODE_NORMAL (value 1): The standard generation mode.
• Client::MODE_DYNAMIC (value 2): The dynamic random generation mode.

const MODE_NORMAL = 1;
const MODE_DYNAMIC = 2;