Nanoid Php

https://github.com/hidehalo/nanoid-php
Admin
Nanoid Php is a tiny, secure, URL-friendly unique string ID generator, a PHP port of the original...
Tokens:20,213
Snippets:176
Trust Score:8.9
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install nanoid-php with Composer

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/README.md

Install the nanoid-php package via Composer.

```bash
composer require hidehalo/nanoid-php
```

--------------------------------

### Creating Client instances

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/configuration.md

Example of creating Client instances with default and custom size. The first uses the default size 21 and the bundled secure Generator source; the second uses size 32.

```php
use Hidehalo\Nanoid\Client;

$client = new Client();          // size 21, bundled secure Generator source
$longer = new Client(32);        // size 32
```

--------------------------------

### Implement Custom Engine with CoreInterface

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/core-interface.md

Example of implementing a custom engine that implements CoreInterface, using the SAFE_SYMBOLS constant.

```php
use Hidehalo\Nanoid\CoreInterface;
use Hidehalo\Nanoid\GeneratorInterface;

class MyEngine implements CoreInterface
{
    public function random(GeneratorInterface $generator, $size, $alphabet = CoreInterface::SAFE_SYMBOLS)
    {
        // implement rejection sampling here; keep $alphabet <= 256 symbols
        throw new RuntimeException('not implemented');
    }
}
```

--------------------------------

### Named implementation wired into Client constructor

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/generator-interface.md

Example showing a named class HardwareSource implementing GeneratorInterface, reading from /dev/urandom, and passing it to the Client constructor. Uses Client::MODE_DYNAMIC.

```php
use Hidehalo\Nanoid\Client;
use Hidehalo\Nanoid\GeneratorInterface;

class HardwareSource implements GeneratorInterface
{
    public function random($size)
    {
        // e.g. read the requested number of bytes from /dev/urandom
        return unpack('C*', file_get_contents('/dev/urandom', false, null, 0, $size));
    }
}

$client = new Client(21, new HardwareSource());
echo $client->generateId(21, Client::MODE_DYNAMIC);
```

--------------------------------

### Use Core::random() with Default and Custom Alphabets

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/core-interface.md

Example of using the random method through the Core class with default and custom alphabets.

```php
use Hidehalo\Nanoid\Core;
use Hidehalo\Nanoid\Generator;

$engine = new Core();
$id = $engine->random(new Generator(), 21);                    // SAFE_SYMBOLS default
$id2  = $engine->random(new Generator(), 16, 'abcdefghijkl');  // custom alphabet
```

--------------------------------

### formatedId usage example

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Example of using formatedId to generate a 12-character ID from a lowercase alphabet.

```php
use Hidehalo\Nanoid\Client;

$client = new Client();
echo $client->formatedId('abcdefghijklmnopqrstuvwxyz', 12);
```

--------------------------------

### GeneratorInterface::random

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/generator-interface.md

Documentation for the GeneratorInterface::random method, including signature, parameters, return type, contract notes, and usage examples.

```APIDOC
## GeneratorInterface::random

### Description
Returns an array of random byte values. This method is the contract for custom random-byte sources consumed by `Core::random()`.

### Method
`public function random($size)`

### Parameters
- **$size** (integer) - Required - Number of random bytes requested.

### Returns
- **array** - An array with `$size` random byte values, each in range `0..255`.

### Contract Notes
- The return value does not have to be a numerically-indexed array starting at index 0; it may begin from index 1.
- Over-requesting (`$size` larger than needed) is safe; values outside the alphabet-derived mask are discarded.
- Returning an empty array for `$size > 0` can cause infinite loops in the consumer.

### Throws
Not specified by the interface; exceptions propagate unchanged.

### Example (Anonymous Class)
```php
use Hidehalo\Nanoid\Client;
use Hidehalo\Nanoid\GeneratorInterface;

$client = new Client();
$id = $client->formattedId(
    '0123456789abcdefg',
    21,
    new class implements GeneratorInterface {
        public function random($size)
        {
            $bytes = [];
            for ($i = 0; $i < $size; $i++) {
                $bytes[] = mt_rand(0, 255);
            }
            return $bytes;
        }
    }
);
echo $id;
```

### Example (Named Implementation)
```php
use Hidehalo\Nanoid\Client;
use Hidehalo\Nanoid\GeneratorInterface;

class HardwareSource implements GeneratorInterface
{
    public function random($size)
    {
        return unpack('C*', file_get_contents('/dev/urandom', false, null, 0, $size));
    }
}

$client = new Client(21, new HardwareSource());
echo $client->generateId(21, Client::MODE_DYNAMIC);
```
```

--------------------------------

### generateId

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Documentation for the generateId method of the Hidehalo\Nanoid\Client class, including parameters, behavior, return type, and usage examples.

```APIDOC
## `generateId`

### Description
Generates a unique ID using either the default PRNG path or a cryptographically strong dynamic mode.

### Signature
```php
public function generateId($size = 0, $mode = self::MODE_NORMAL)
```

### Parameters
- `$size` (integer) - Optional - Default: `0` - Number of symbols in the returned ID. Values `<= 0` fall back to the constructor-configured `$this->size` (default `21`).
- `$mode` (integer) - Optional - Default: normal mode - One of `MODE_NORMAL` (`1`) or `MODE_DYNAMIC` (`2`). Any other value takes the `default` switch branch, i.e. the normal path.

### Behavior
```php
$size = $size > 0 ? $size : $this->size;
switch ($mode) {
    case self::MODE_DYNAMIC:
        return $this->core->random($this->generator, $size, $this->alphabet);
    default:
        return $this->normalRandom($size);
}
```

- `MODE_DYNAMIC`: delegates to `Core::random()` using the configured `GeneratorInterface` source and the default alphabet (`SAFE_SYMBOLS`).
- `MODE_NORMAL` (default): uses the private PRNG path (`normalRandom`, `src/Client.php:110-119`) that assembles the ID from `$this->alphabet` using a scaled PRNG value. The source calls `mt_rand()`, `mt_getrandmax()` and `intval()` (`src/Client.php:114-115`); none of these three is a standard PHP function name, so the exact runtime behavior of this path could not be verified by static analysis.

### Returns
`string` — the generated ID, always `$size` symbols long (or `$this->size` when `$size <= 0`).

### Throws
None declared. In `MODE_DYNAMIC`, implied failures match `Core::random()` (see [`api-reference/core.md`](core.md)) — e.g. a misbehaving custom generator that never yields enough in-mask bytes keeps the internal loop running forever (`src/Core.php:16-29`).

### Examples
Basic call (default 21-symbol URL-safe ID):

```php
use Hidehalo\Nanoid\Client;

$client = new Client();
echo $client->generateId();          // e.g. "V1StGXRt_Jn5f0cH3YgBm"
echo $client->generateId(8);         // 8 symbols
echo $client->generateId(8);         // again — different result each call
```

Switching to the cryptographically strong mode and handling a `size` fallback:

```php
use Hidehalo\Nanoid\Client;

$client = new Client();
$id = $client->generateId(21, Client::MODE_DYNAMIC);
echo $id;                            // 21 symbols from the secure path

// negative/zero sizes silently fall back to the configured default (21):
echo $client->generateId(0, Client::MODE_DYNAMIC);
```
```

--------------------------------

### Basic usage of Generator::random()

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/generator.md

Creates a Generator instance and calls random(8) to get an array of 8 random bytes.

```php
use Hidehalo\Nanoid\Generator;

$generator = new Generator();
$bytes = $generator->random(8);   // array with 8 entries, each 0..255
echo count($bytes);
```

--------------------------------

### formattedId

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Documentation for the formattedId method of the Client class, including signature, parameters, behavior, return type, and usage examples.

```APIDOC
## `formattedId`

### Description
Generates a random ID using the original nanoid API, always using the secure `Core::random()` path. The alphabet, size, and generator can be customized per call.

### Method
`formattedId`

### Signature
```php
public function formattedId($alphabet, $size = 0, ?GeneratorInterface $generator = null)
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$alphabet` | `string` | Yes (positional) | Fallback `CoreInterface::SAFE_SYMBOLS` when falsy | Symbols to be used in the ID. May contain 256 symbols or less; beyond that the generator is not secure. |
| `$size` | `integer` | No | `0` → falls back to `$this->size` (constructor default `21`) | Number of symbols in the returned ID. |
| `$generator` | `?GeneratorInterface` (nullable) | No | `null` → falls back to `$this->generator` | Random-bytes source used for this call only. |

### Behavior
```php
$alphabet = $alphabet ?: CoreInterface::SAFE_SYMBOLS;
$size = $size > 0 ? $size : $this->size;
$generator = $generator ?: $this->generator;

return $this->core->random($generator, $size, $alphabet);
```

### Returns
`string` — the generated ID over the given alphabet, `$size` symbols long.

### Throws
None declared; implied failure modes are those of `Core::random()`.

### Examples
Basic call with a custom alphabet:

```php
use Hidehalo\Nanoid\Client;

$client = new Client();
$id = $client->formattedId('0123456789abcdefg', 21); // 21 hex-ish symbols
echo $id;
```

Non-trivial call: digits-only alphabet with a deterministic (non-crypto) generator, plus defensive validation of the alphabet length:

```php
use Hidehalo\Nanoid\Client;
use Hidehalo\Nanoid\GeneratorInterface;

class DummyGenerator implements GeneratorInterface
{
    public function random($size)
    {
        $bytes = [];
        for ($i = 0; $i < $size; $i++) {
            $bytes[] = mt_rand(0, 255);
        }
        return $bytes;
    }
}

$alphabet = '0123456789';
if (strlen($alphabet) > 256) {
    // CoreInterface::random() requires <= 256 symbols to stay secure
    throw new RuntimeException('Alphabet too large');
}

$client = new Client();
$numericId = $client->formattedId($alphabet, 10, new DummyGenerator());
echo $numericId;
```
```

--------------------------------

### Anonymous class implementation of GeneratorInterface

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/generator-interface.md

Example from the README showing an anonymous class implementing GeneratorInterface, used with Client::formattedId(). Requires PHP >= 7.0. The random method must return an array of $size random byte values in range 0..255.

```php
use Hidehalo\Nanoid\Client;
use Hidehalo\Nanoid\GeneratorInterface;

$client = new Client();
$id = $client->formattedId(
    '0123456789abcdefg',
    21,
    new class implements GeneratorInterface {
        public function random($size)
        {
            // must return $size random byte values (0..255)
            $bytes = [];
            for ($i = 0; $i < $size; $i++) {
                $bytes[] = mt_rand(0, 255);
            }
            return $bytes;
        }
    }
);
echo $id;
```

--------------------------------

### Import Client class

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Import the Client class, the main entry point of the library.

```php
use Hidehalo\Nanoid\Client;
```

--------------------------------

### Basic Client construction

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Basic construction with defaults. Creates a `Client` with size `21` and the default `Generator`.

```php
use Hidehalo\Nanoid\Client;

$client = new Client(); // size = 21, default Generator
```

--------------------------------

### Run tests with Composer

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/README.md

Run the test suite for the nanoid-php package.

```bash
composer test
```

--------------------------------

### Import Core class

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/core.md

Import the Core class from the Hidehalo\Nanoid namespace.

```php
use Hidehalo\Nanoid\Core;
```

--------------------------------

### Direct use with custom generator

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/core.md

Shows how to use Core directly with a custom GeneratorInterface implementation, demonstrating the variable-length/iterable array contract and defensive handling of a misbehaving source.

```php
use Hidehalo\Nanoid\Core;
use Hidehalo\Nanoid\GeneratorInterface;

class EntropySource implements GeneratorInterface
{
    public function random($size)
    {
        // May legally return more or fewer values than $size;
        // Core simply iterates whatever is returned.
        $bytes = [];
        for ($i = 0; $i < $size * 2; $i++) {
            $bytes[] = mt_rand(0, 127);
        }
        return $bytes;
    }
}

$core  = new Core();
$bytes = $core->random(new EntropySource(), 10, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ');
echo $bytes;
```

--------------------------------

### Basic usage with bundled Generator

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/core.md

Creates a Core instance and uses the bundled Generator to produce a default nanoid and a hex nanoid with a custom alphabet.

```php
use Hidehalo\Nanoid\Core;
use Hidehalo\Nanoid\Generator;

$core = new Core();
$generator = new Generator();

$id = $core->random($generator, 21);                      // default SAFE_SYMBOLS alphabet
$hexId = $core->random($generator, 8, '0123456789abcdef'); // custom alphabet
echo $id;
echo $hexId;
```

--------------------------------

### Run tests with composer test

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/CONTRIBUTING.md

Use this command to run the project's test suite. It is the standard way to verify your changes before submitting a pull request.

```bash
$ composer test
```

--------------------------------

### random() method body

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/core.md

The full implementation of the random() method, including mask calculation, batch step, and rejection sampling loop.

```php
$len = strlen($alphabet);
$mask = (2 << (int) (log($len - 1) / M_LN2)) - 1;
$step = (int) ceil(1.6 * $mask * $size / $len);
$id = '';
while (true) {
    $bytes = $generator->random($step);
    // NOTE: `$bytes` maybe not a normal "Array"
    // sometimes it's begin from index 1, use iterator please
    foreach ($bytes as $byte) {
        $byte &= $mask;
        if (isset($alphabet[$byte])) {
            $id .= $alphabet[$byte];
            if (strlen($id) === $size) {
                return $id;
            }
        }
    }
}
```

--------------------------------

### Import Generator class

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/generator.md

Import the Generator class from the Hidehalo\Nanoid namespace.

```php
use Hidehalo\Nanoid\Generator;
```

--------------------------------

### Import GeneratorInterface

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/generator-interface.md

Import the GeneratorInterface class from the Hidehalo\Nanoid namespace.

```php
use Hidehalo\Nanoid\GeneratorInterface;
```

--------------------------------

### Import CoreInterface

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/core-interface.md

Import the CoreInterface class for use in PHP code.

```php
use Hidehalo\Nanoid\CoreInterface;
```

--------------------------------

### __construct

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Constructor for the Client class. Initializes the default ID size and random generator. Accepts optional size and generator parameters.

```APIDOC
## __construct

### Description
Constructor for the Client class. Initializes the default ID size and random generator. Accepts optional size and generator parameters.

### Method
__construct

### Signature
public function __construct($size = 21, ?GeneratorInterface $generator = null)

### Parameters
- **$size** (integer) - Optional - Default: 21 - Default number of symbols per generated ID. Values <= 0 are normalized to 21.
- **$generator** (?GeneratorInterface) - Optional - Default: null - Custom random-bytes source. When null, a new Generator() is used.

### Behavior
Initializes all protected/private state:

```php
$this->size = $size > 0 ? $size : 21;
$this->generator = $generator ?: new Generator();
$this->core = new Core();
$this->alphabet = CoreInterface::SAFE_SYMBOLS;
```

### Returns
Nothing (constructor).

### Throws
None declared. The constructor instantiates Core and Generator; if the paragonie/random_compat package is not installed, no error occurs here — it surfaces later in Generator::random().

### Examples
Basic construction with defaults:

```php
use Hidehalo\Nanoid\Client;

$client = new Client(); // size = 21, default Generator
```

Construction with a custom default size and custom random source:

```php
use Hidehalo\Nanoid\Client;
use Hidehalo\Nanoid\GeneratorInterface;

class MyGenerator implements GeneratorInterface
{
    public function random($size)
    {
        // dummy source; a real implementation must return $size random byte values
        $bytes = [];
        for ($i = 0; $i < $size; $i++) {
            $bytes[] = mt_rand(0, 255);
        }
        return $bytes;
    }
}

$client = new Client(32, new MyGenerator());
```
```

--------------------------------

### Client constructor signature

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/configuration.md

Constructor signature for the Client class. The $size parameter defaults to 21 and any value <= 0 is normalized to 21. The $generator parameter is nullable and defaults to a new Generator instance when null or falsy.

```php
public function __construct($size = 21, ?GeneratorInterface $generator = null)
```

--------------------------------

### Constructor initialization

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Initializes all protected/private state in the constructor. Sets `$size` to `21` if not positive, uses the provided generator or a new `Generator`, creates a new `Core`, and assigns `CoreInterface::SAFE_SYMBOLS` to `$alphabet`.

```php
$this->size = $size > 0 ? $size : 21;
$this->generator = $generator ?: new Generator();
$this->core = new Core();
$this->alphabet = CoreInterface::SAFE_SYMBOLS;
```

--------------------------------

### Typical usage with Client and explicit Generator

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/generator.md

Uses the Client facade with an explicit Generator instance passed to formattedId.

```php
use Hidehalo\Nanoid\Client;

// Client instantiates Generator internally when none is given:
$client = new Client();
$secureId = $client->formattedId('0123456789abcdefghijklmnopqrstuvwxyz', 21, new \Hidehalo\Nanoid\Generator());
echo $secureId;
```

--------------------------------

### Client class declaration

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Class declaration of the Client class, located in src/Client.php at line 4.

```php
class Client
```

--------------------------------

### Equivalent usage without explicit Generator

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/generator.md

The same call as above but omitting the third argument, relying on the client's default Generator.

```php
use Hidehalo\Nanoid\Client;

$client = new Client();
$secureId = $client->formattedId('0123456789abcdefghijklmnopqrstuvwxyz', 21);
echo $secureId;
```

--------------------------------

### Client mode constants

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Class constants for generation modes: MODE_NORMAL (non-secure) and MODE_DYNAMIC (secure). Accessed as Client::MODE_NORMAL and Client::MODE_DYNAMIC.

```php
const MODE_NORMAL = 1;
const MODE_DYNAMIC = 2;
```

--------------------------------

### Custom generator and size

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Construction with a custom default size and custom random source. Defines a `MyGenerator` implementing `GeneratorInterface` and passes it to the `Client` constructor with size `32`.

```php
use Hidehalo\Nanoid\Client;
use Hidehalo\Nanoid\GeneratorInterface;

class MyGenerator implements GeneratorInterface
{
    public function random($size)
    {
        // dummy source; a real implementation must return $size random byte values
        $bytes = [];
        for ($i = 0; $i < $size; $i++) {
            $bytes[] = mt_rand(0, 255);
        }
        return $bytes;
    }
}

$client = new Client(32, new MyGenerator());
```

--------------------------------

### generateId with MODE_DYNAMIC and size fallback

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Switches to the cryptographically strong MODE_DYNAMIC path. Passing 21 yields 21 symbols from the secure path; a size of 0 silently falls back to the configured default of 21.

```php
use Hidehalo\Nanoid\Client;

$client = new Client();
$id = $client->generateId(21, Client::MODE_DYNAMIC);
echo $id;                            // 21 symbols from the secure path

// negative/zero sizes silently fall back to the configured default (21):
echo $client->generateId(0, Client::MODE_DYNAMIC);
```

--------------------------------

### Define CoreInterface Constants

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/core-interface.md

Interface constants for the default alphabet and masks.

```php
const SAFE_SYMBOLS = '_-0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
const MASKS = [15, 31, 63, 127, 255];
```

--------------------------------

### random() method signature

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/generator.md

The public method signature for random().

```php
public function random($size)
```

--------------------------------

### random() method signature

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/core.md

The public method signature for random(), which generates a nanoid using a generator, size, and optional alphabet.

```php
public function random(GeneratorInterface $generator, $size, $alphabet = CoreInterface::SAFE_SYMBOLS)
```

--------------------------------

### Core::random

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/core.md

Documentation for the Core::random method, which generates a random ID using a specified alphabet and random byte generator.

```APIDOC
## `Core::random`

### Description
Generates a random ID of a specified size using a given alphabet and a random byte generator. This method implements the core algorithm for creating nanoids.

### Method
`public function random(GeneratorInterface $generator, $size, $alphabet = CoreInterface::SAFE_SYMBOLS)`

### Parameters
- **$generator** (GeneratorInterface) - Required - Source of random bytes. Called with a batch size; must return an array (or array-like, iterable) of byte values.
- **$size** (integer) - Required - Number of symbols the returned ID must contain.
- **$alphabet** (string) - Optional - Symbols to be used in the ID. Must contain 256 symbols or fewer, otherwise the generator will not be secure. Defaults to `CoreInterface::SAFE_SYMBOLS`.

### Returns
`string` - The generated ID, exactly `$size` symbols long, drawn from `$alphabet`.

### Behavior
1. **Mask calculation** - Computes the smallest power-of-two-minus-one that covers the alphabet length.
2. **Batch step** - Over-requests random bytes so the mask-rejection loop terminates quickly.
3. **Rejection sampling** - Bytes are fetched in batches until `$size` valid symbols have been collected. Each byte is masked; only bytes that index a valid alphabet position are appended. The loop only exits once the ID reaches the requested length.

### Throws / Implied Failure Modes
- **Non-termination (infinite loop)**: If the custom `$generator` returns an empty batch, or repeatedly returns bytes that all fall outside the mask, or throws, the `while (true)` loop never returns. There is no retry limit or error path.
- **Generator contract errors**: Any exception raised inside `$generator->random($step)` propagates to the caller unchanged, because no `try`/`catch` exists in this method.

### Example
```php
use Hidehalo\Nanoid\Core;
use Hidehalo\Nanoid\Generator;

$core = new Core();
$generator = new Generator();

$id = $core->random($generator, 21);                      // default SAFE_SYMBOLS alphabet
$hexId = $core->random($generator, 8, '0123456789abcdef'); // custom alphabet
echo $id;
echo $hexId;
```
```

--------------------------------

### Generate ID with default and dynamic modes

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/README.md

Generate a URL-friendly ID with 21 characters using the default random generator or the more secure dynamic mode (Client::MODE_DYNAMIC).

```php
use Hidehalo\Nanoid\Client;
use Hidehalo\Nanoid\GeneratorInterface;

$client = new Client();

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

--------------------------------

### Declare CoreInterface

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/core-interface.md

Declaration of the CoreInterface interface.

```php
interface CoreInterface
```

--------------------------------

### formatedId size fallback and delegation

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Implementation of formatedId: it merges the size fallback (if size is 0, uses $this->size) and delegates to formattedId.

```php
$size = $size > 0 ? $size : $this->size;
return $this->formattedId($alphabet, $size, $generator);
```

--------------------------------

### Core class declaration

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/core.md

The Core class implements the CoreInterface contract.

```php
class Core implements CoreInterface
```

--------------------------------

### random() method body

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/generator.md

The full body of the random() method, which uses random_bytes and unpack.

```php
return unpack('C*', \random_bytes($size));
```

--------------------------------

### normalRandom ID generation loop

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Implementation of normalRandom: it builds an ID by repeatedly generating a PRNG fraction and indexing the alphabet. Uses mt_rand, mt_getrandmax, and intval, which are not standard PHP built-ins.

```php
while (1 <= $size--) {
    $rand = mt_rand() / (mt_getrandmax() + 1);
    $id .= $this->alphabet[intval($rand * 64)];
}
```

--------------------------------

### formatedId

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Documentation for the `formatedId` method, a backwards-compatible alias for `formattedId` in the nanoid-php client.

```APIDOC
## `formatedId`

Backwards-compatible alias (the misspelled name), present since 1.0.0 (`@since 1.0.0`, `src/Client.php:92`).

### Signature (exact, `src/Client.php:94`)

```php
public function formatedId($alphabet, $size = 0, ?GeneratorInterface $generator = null)
```

### Parameters

Identical to `formattedId`:

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$alphabet` | `string` | Yes (positional) | — (passed through) | Symbols to be used in the ID. |
| `$size` | `integer` | No | `0` → falls back to `$this->size` | Number of symbols in the returned ID. |
| `$generator` | `?GeneratorInterface` (nullable) | No | `null` (passed through) | Random-bytes source for this call only. |

### Behavior

Merges only the size fallback, then delegates (`src/Client.php:96-98`):

```php
$size = $size > 0 ? $size : $this->size;
return $this->formattedId($alphabet, $size, $generator);
```

### Returns

`string` — identical result to calling `formattedId()` with the same arguments.

### Throws

Same as `formattedId`.

### Examples

```php
use Hidehalo\Nanoid\Client;

$client = new Client();
echo $client->formatedId('abcdefghijklmnopqrstuvwxyz', 12);
```
```

--------------------------------

### Basic generateId usage

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Basic usage of generateId with default settings. The first call returns a 21-symbol URL-safe ID; passing 8 returns 8 symbols. Each call produces a different result.

```php
use Hidehalo\Nanoid\Client;

$client = new Client();
echo $client->generateId();          // e.g. "V1StGXRt_Jn5f0cH3YgBm"
echo $client->generateId(8);         // 8 symbols
echo $client->generateId(8);         // again — different result each call
```

--------------------------------

### CoreInterface::random

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/core-interface.md

The random method is the core contract for generating secure random strings with a custom alphabet. It accepts a generator, size, and optional alphabet, returning a string of the specified length.

```APIDOC
## CoreInterface::random

### Description
Generates a secure random string with a custom alphabet. The alphabet must contain 256 symbols or less to ensure security.

### Method
random

### Signature
```php
public function random(GeneratorInterface $generator, $size, $alphabet = CoreInterface::SAFE_SYMBOLS)
```

### Parameters
- **$generator** (GeneratorInterface) - Required - Random-bytes provider consumed by the algorithm.
- **$size** (integer) - Required - Number of symbols the returned ID must contain.
- **$alphabet** (string) - Optional - Symbols to be used in the ID. Must be ≤ 256 symbols for the derived mask to remain secure. Default: `CoreInterface::SAFE_SYMBOLS`.

### Returns
- **string** - A generated ID of exactly `$size` symbols drawn from `$alphabet`.

### Throws
Not specified by the interface. The bundled implementation never throws by itself.

### Implementations
- `Core` (the only implementation in the package)

### Examples
```php
use Hidehalo\Nanoid\Core;
use Hidehalo\Nanoid\Generator;

$engine = new Core();
$id = $engine->random(new Generator(), 21);                    // SAFE_SYMBOLS default
$id2  = $engine->random(new Generator(), 16, 'abcdefghijkl');  // custom alphabet
```

Using the constant when implementing a third-party engine:

```php
use Hidehalo\Nanoid\CoreInterface;
use Hidehalo\Nanoid\GeneratorInterface;

class MyEngine implements CoreInterface
{
    public function random(GeneratorInterface $generator, $size, $alphabet = CoreInterface::SAFE_SYMBOLS)
    {
        // implement rejection sampling here; keep $alphabet <= 256 symbols
        throw new RuntimeException('not implemented');
    }
}
```
```

--------------------------------

### CoreInterface random() Signature

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/core-interface.md

Signature of the random method in CoreInterface.

```php
public function random(GeneratorInterface $generator, $size, $alphabet = CoreInterface::SAFE_SYMBOLS);
```

--------------------------------

### Private property $core

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Declares the private property `$core` at `src/Client.php:25`. It holds an internal `CoreInterface` instance (`new Core()`, `src/Client.php:43`) used for the secure/dynamic generation path.

```php
private $core;
```

--------------------------------

### Protected $alphabet property

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Protected property holding the alphabet symbols for ID generation. Always initialized to CoreInterface::SAFE_SYMBOLS by the constructor.

```php
protected $alphabet;
```

--------------------------------

### Basic formattedId call with custom alphabet

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Basic usage of formattedId with a custom alphabet and explicit size. Creates a Client and generates a 21-symbol ID using the given alphabet, then echoes it.

```php
use Hidehalo\Nanoid\Client;

$client = new Client();
$id = $client->formattedId('0123456789abcdefg', 21); // 21 hex-ish symbols
echo $id;
```

--------------------------------

### Generate ID with custom alphabet and length

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/README.md

Generate an ID with a custom alphabet and length. The alphabet must contain 256 symbols or less, otherwise the generator will not be secure.

```php
echo $client->formattedId($alphabet = '0123456789abcdefg', $size = 21);
```

--------------------------------

### generateId behavior with mode switch

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Behavior of generateId: if $size is not positive, it falls back to the configured default. MODE_DYNAMIC delegates to Core::random() with the configured generator and alphabet; any other mode uses the normal PRNG path.

```php
$size = $size > 0 ? $size : $this->size;
switch ($mode) {
    case self::MODE_DYNAMIC:
        return $this->core->random($this->generator, $size, $this->alphabet);
    default:
        return $this->normalRandom($size);
}
```

--------------------------------

### Generate ID with custom random generator

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/README.md

Generate an ID using a custom random bytes generator implemented as an anonymous class. Requires PHP >= 7.0. The random method must accept the array size and return an array with random numbers.

```php
# PS: anonymous class is new feature when PHP_VERSION >= 7.0
echo $client->formattedId($alphabet = '0123456789abcdefg', $size = 21,
new class implements GeneratorInterface {
    /**
     * @inheritDoc
     */
    public function random($size)
    {
        //TODO: implemenation ...
    }
});
```

--------------------------------

### formattedId default resolution and core call

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Internal behavior of formattedId: resolves defaults for alphabet, size, and generator, then delegates to Core::random(). The alphabet falls back to CoreInterface::SAFE_SYMBOLS when falsy; size falls back to $this->size when not positive; generator falls back to $this->generator when null.

```php
$alphabet = $alphabet ?: CoreInterface::SAFE_SYMBOLS;
$size = $size > 0 ? $size : $this->size;
$generator = $generator ?: $this->generator;

return $this->core->random($generator, $size, $alphabet);
```

--------------------------------

### CoreInterface member signatures

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/types.md

Member signatures of CoreInterface: the SAFE_SYMBOLS constant (64-character URL-safe alphabet), the MASKS constant (declared but never referenced in src/), and the random() method signature.

```php
const SAFE_SYMBOLS = '_-0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
const MASKS = [15, 31, 63, 127, 255];
public function random(GeneratorInterface $generator, $size, $alphabet = CoreInterface::SAFE_SYMBOLS);
```

--------------------------------

### generateId method signature

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Exact signature of the generateId method as found in src/Client.php:54. The default mode uses self::MODE_NORMAL, which resolves to 1; the docblock intends Client::MODE_NORMAL.

```php
public function generateId($size = 0, $mode = self::MODE_NORMAL)
```

--------------------------------

### Generator class declaration

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/generator.md

The Generator class implements the GeneratorInterface.

```php
class Generator implements GeneratorInterface
```

--------------------------------

### GeneratorInterface declaration

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/types.md

Declares the GeneratorInterface contract for random-byte sources consumed by Core::random(). Implementations include Generator and DummyGenerator.

```php
interface GeneratorInterface
```

--------------------------------

### formattedId method signature

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Method signature for formattedId, the original nanoid API. Always uses the secure Core::random() path. Parameters: $alphabet (string, required, fallback to CoreInterface::SAFE_SYMBOLS when falsy), $size (integer, default 0 falls back to $this->size, constructor default 21), $generator (?GeneratorInterface, nullable, default null falls back to $this->generator).

```php
public function formattedId($alphabet, $size = 0, ?GeneratorInterface $generator = null)
```

--------------------------------

### Protected property $size

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Declares the protected property `$size` at `src/Client.php:20`. It stores the default ID length, set by the constructor from the `$size` argument, falling back to `21` when the argument is not positive.

```php
protected $size;
```

--------------------------------

### Client::formattedId

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Generates a formatted ID using a custom alphabet and/or a custom random source.

```APIDOC
## Client::formattedId

### Description
Generates a formatted ID using a custom alphabet and/or a custom random source. This method allows full control over the ID generation parameters.

### Method
`formattedId`

### Signature
```php
public function formattedId($alphabet, $size = 21, ?GeneratorInterface $generator = null)
```

### Parameters
- **$alphabet** (string) - Required - The custom alphabet of symbols to use for ID generation.
- **$size** (int) - Optional - Length of the generated ID. Defaults to 21.
- **$generator** (GeneratorInterface|null) - Optional - A custom random source implementing `GeneratorInterface`. If null, the default random source is used.

### Return Value
- **string** - The generated formatted ID.

### Example
```php
use Hidehalo\Nanoid\Client;

$client = new Client();
$id = $client->formattedId('abc123', 16);
```
```

--------------------------------

### formattedId with custom generator and alphabet validation

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Non-trivial usage of formattedId with a digits-only alphabet and a deterministic (non-crypto) generator. Includes defensive validation that the alphabet length does not exceed 256 symbols, as CoreInterface::random() requires <= 256 symbols to stay secure. Throws RuntimeException if the alphabet is too large.

```php
use Hidehalo\Nanoid\Client;
use Hidehalo\Nanoid\GeneratorInterface;

class DummyGenerator implements GeneratorInterface
{
    public function random($size)
    {
        $bytes = [];
        for ($i = 0; $i < $size; $i++) {
            $bytes[] = mt_rand(0, 255);
        }
        return $bytes;
    }
}

$alphabet = '0123456789';
if (strlen($alphabet) > 256) {
    // CoreInterface::random() requires <= 256 symbols to stay secure
    throw new RuntimeException('Alphabet too large');
}

$client = new Client();
$numericId = $client->formattedId($alphabet, 10, new DummyGenerator());
echo $numericId;
```

--------------------------------

### normalRandom method signature

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Exact signature of the private normalRandom method, used internally by generateId in normal (non-secure) mode.

```php
private function normalRandom($size)
```

--------------------------------

### Protected property $generator

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Declares the protected property `$generator` at `src/Client.php:30`. It holds the `GeneratorInterface` implementation used as the default random source, defaulting to `new Generator()` when none is supplied (`src/Client.php:42`).

```php
protected $generator;
```

--------------------------------

### Client::generateId

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Generates a random ID using the default alphabet and a selectable random mode (normal or dynamic).

```APIDOC
## Client::generateId

### Description
Generates a random ID using the default alphabet and a selectable random mode (normal or dynamic). The mode is specified via the `$mode` parameter, which defaults to `MODE_NORMAL`.

### Method
`generateId`

### Signature
```php
public function generateId($size = 21, $mode = self::MODE_NORMAL)
```

### Parameters
- **$size** (int) - Optional - Length of the generated ID. Defaults to 21.
- **$mode** (int) - Optional - Generation mode: `Client::MODE_NORMAL` (1) for non-secure PRNG-based generation, or `Client::MODE_DYNAMIC` (2) for secure cryptographically strong generation. Defaults to `Client::MODE_NORMAL`.

### Return Value
- **string** - The generated ID.

### Description of Modes
- `MODE_NORMAL` (1): Non-secure generation using a PRNG (`mt_rand()`-style).
- `MODE_DYNAMIC` (2): Secure generation using `Core::random()` with a cryptographically strong random source.

### Example
```php
use Hidehalo\Nanoid\Client;

$client = new Client();
$id = $client->generateId(); // default size 21, normal mode
$secureId = $client->generateId(32, Client::MODE_DYNAMIC);
```
```

--------------------------------

### Generator::random

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/generator.md

Generates an array of cryptographically strong random byte values. This method is used internally by Core::random() and is the primary public method of the Generator class.

```APIDOC
## Generator::random

### Description
Generates an array of cryptographically strong random byte values. This method is used internally by Core::random() and is the primary public method of the Generator class.

### Method
`public function random($size)`

### Parameters
- `$size` (integer) - Required - Number of random bytes requested.

### Returns
`array` - An array of `$size` random integer byte values in the range `0..255`.

### Throws
No exceptions are declared. If the `paragonie/random_compat` dependency is not installed, PHP 8+ raises `Error: Call to undefined function random_bytes()`.

### Examples
Basic use:
```php
use Hidehalo\Nanoid\Generator;

$generator = new Generator();
$bytes = $generator->random(8);   // array with 8 entries, each 0..255
echo count($bytes);
```

Typical use via Client facade:
```php
use Hidehalo\Nanoid\Client;

$client = new Client();
$secureId = $client->formattedId('0123456789abcdefghijklmnopqrstuvwxyz', 21, new \Hidehalo\Nanoid\Generator());
echo $secureId;
```

The explicit-passing form is equivalent to:
```php
use Hidehalo\Nanoid\Client;

$client = new Client();
$secureId = $client->formattedId('0123456789abcdefghijklmnopqrstuvwxyz', 21);
echo $secureId;
```
```

--------------------------------

### Client::formatedId

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Alias of `formattedId()` (note the typo in the method name). Generates a formatted ID using a custom alphabet and/or a custom random source.

```APIDOC
## Client::formatedId

### Description
Alias of `formattedId()` (note the typo in the method name). Generates a formatted ID using a custom alphabet and/or a custom random source.

### Method
`formatedId`

### Signature
```php
public function formatedId($alphabet, $size = 21, ?GeneratorInterface $generator = null)
```

### Parameters
- **$alphabet** (string) - Required - The custom alphabet of symbols to use for ID generation.
- **$size** (int) - Optional - Length of the generated ID. Defaults to 21.
- **$generator** (GeneratorInterface|null) - Optional - A custom random source implementing `GeneratorInterface`. If null, the default random source is used.

### Return Value
- **string** - The generated formatted ID.

### Example
```php
use Hidehalo\Nanoid\Client;

$client = new Client();
$id = $client->formatedId('abc123', 16);
```
```

--------------------------------

### formatedId method signature

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/api-reference/client.md

Exact signature of the formatedId method, a backwards-compatible alias for formattedId. It accepts an alphabet string, an optional size (default 0), and an optional generator.

```php
public function formatedId($alphabet, $size = 0, ?GeneratorInterface $generator = null)
```

--------------------------------

### GeneratorInterface member signature

Source: https://github.com/hidehalo/nanoid-php/blob/2.x/_autodocs/types.md

Member signature of GeneratorInterface: random($size) returns an array of $size random byte values (each 0..255).

```php
public function random($size);
```
Tokens:
Raw