PHPackages                             adambean/randflake-id-bundle - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. adambean/randflake-id-bundle

ActiveLibrary[Utility & Helpers](/categories/utility)

adambean/randflake-id-bundle
============================

A distributed, uniform, unpredictable, unique random ID generator: PHP Symfony bundle.

20PHP

Since May 27Pushed 1mo agoCompare

[ Source](https://github.com/Adambean/randflake-id-bundle)[ Packagist](https://packagist.org/packages/adambean/randflake-id-bundle)[ RSS](/packages/adambean-randflake-id-bundle/feed)WikiDiscussions main Synced 3w ago

READMEChangelogDependenciesVersions (1)Used By (0)

Randflake ID Symfony Bundle
===========================

[](#randflake-id-symfony-bundle)

Symfony bundle for my PHP implementation of Randflake ID generator.

This bundle implements my [Randflake ID library package](https://github.com/adambean/randflake-id-php) into your Symfony project with the Doctrine ORM/DBAL integration, providing a custom column type and ID generator for seamless integration, including transparent handling of encrypted and encoded IDs. It also provides a validation constraint for validating Randflake IDs in your Symfony application, and console commands for generating secrets, generating IDs, and inspecting IDs.

While not required, you should familiarise yourself with the library package documentation before using this bundle, as it is beneficial to understand the configuration and usage of this bundle.

**⚠️ This library is currently a work in progress, and should not be used in a production environment until it has undergone peer review.**

Requirements
------------

[](#requirements)

- PHP† 8.1 or later
- Composer
- Symfony 6.4 or later
- Doctrine bundle 2.13 or later

† **This library requires a 64-bit build of PHP to function.** Check your `PHP_INT_SIZE`, which **must** be at least `8`:

```
php -r 'echo PHP_INT_SIZE;'
```

Installation
------------

[](#installation)

Add a Composer package as is usual for PHP projects:

```
composer require adambean/randflake-id-bundle
```

Configuration
-------------

[](#configuration)

### Options

[](#options)

With exception of the node ID and lease times, all configuration options **must** be consistent across all nodes.

#### RANDFLAKE\_ID\_NODE\_ID

[](#randflake_id_node_id)

**Required, unsigned integer, 0 to 131071:** The node ID for this instance. This **must** be unique across all nodes generating IDs to avoid collisions. You **must** keep track of your node ID allocations.

Refer the the library documentation **Nodes** section for more details on managing node IDs.

If you only have one processing node, you can set this to `0`.

#### RANDFLAKE\_ID\_SECRET

[](#randflake_id_secret)

**Required, string, 16 bytes:** The shared secret for your application ID pool. This **must** be a 16-byte string, and **must** be identical across all nodes of your application.

You can generate a secret using the `randflakeid:secret:generate` console command, and optionally pass in the "--excludeSymbols" option to generate a secret without symbols (digits and mixed case letters only).

#### RANDFLAKE\_ID\_ENCRYPTED

[](#randflake_id_encrypted)

**Optional, boolean (default: true):** Whether IDs should be encrypted within your application. Encrypted IDs are unpredictable thus do not leak the creation time, node ID, and ID sequence to end users.

You should never change this setting after your application has begun to generate IDs, though can optionally use the explicit column types to deviate from the configuration.

#### RANDFLAKE\_ID\_ENCODED

[](#randflake_id_encoded)

**Optional, boolean (default: true):** Whether IDs should be encoded within your application. Encoded IDs will be shortened from an integer up to 20 digits down to a string up to 13 characters.

You should never change this setting after your application has begun to generate IDs, though can optionally use the explicit column types to deviate from the configuration.

#### RANDFLAKE\_ID\_LEASE\_START and RANDFLAKE\_ID\_LEASE\_END

[](#randflake_id_lease_start-and-randflake_id_lease_end)

**Optional, integer timestamp (default: 0):** The start and end of the node lease time (in seconds since Unix epoch) for the node ID allocation. This is used to allow for temporary nodes to exist with a limited lease time, allowing you to free up a the node ID later on for another node to replace it.

If the node attempts to generate an ID outside of its lease time an exception will be thrown to block it.

If the node ID allocation is permanent, you can leave both of these at `0` to indicate no limited lease time.

### Environment variables

[](#environment-variables)

Define the required environment variables:

```
RANDFLAKE_ID_NODE_ID=0
RANDFLAKE_ID_SECRET=ThisIsNotSecret!
RANDFLAKE_ID_ENCRYPTED=1
RANDFLAKE_ID_ENCODED=1
RANDFLAKE_ID_LEASE_START=
RANDFLAKE_ID_LEASE_END=
```

### Package

[](#package)

Optional explicit configuration (defaults to the env variables above):

```
# config/packages/adambean_randflake_id.yaml
adambean_randflake_id:
  node_id: '%env(int:default::RANDFLAKE_ID_NODE_ID)%'
  secret: '%env(string:RANDFLAKE_ID_SECRET)%'
  encrypted: '%env(bool:default::RANDFLAKE_ID_ENCRYPTED)%'
  encoded: '%env(bool:default::RANDFLAKE_ID_ENCODED)%'
  lease_start: '%env(int:default::RANDFLAKE_ID_LEASE_START)%'
  lease_end: '%env(int:default::RANDFLAKE_ID_LEASE_END)%'
  time_source: '%env(default::int:RANDFLAKE_ID_TIME_SOURCE)%'
```

Service
-------

[](#service)

The service is registered as `Adambean\Bundle\RandflakeIdBundle\Service\RandflakeIdService` and exposes:

- Static functions:
    - `assertNumericStringId(string $id): void`
    - `assertBase32HexStringId(string $id): void`
    - `assertValidId(string $id, ?bool $expectEncoded = null): void`
    - `generateSecret(bool $excludeSymbols = false): string`
- Instance functions:
    - `changeLease(int $leaseEnd): void`
    - `getNodeId(): int`
    - `getLeaseStart(bool $absolute = false): int`
    - `getLeaseEnd(bool $absolute = false): int`
    - `getTimeSource(): ?int`
    - `isNumericStringIdValid(string $id): void`
    - `isEncodedStringIdValid(string $id): void`
    - `isIdValid(string $id): void`
    - `intToString(int $id): string`
    - `stringToInt(string $id): int`
    - `encryptId(string $idRaw): string`
    - `decryptId(string $idEncrypted): string`
    - `encodeId(string $idPlain): string`
    - `decodeId(string $idEncoded): string`
    - `generate(?bool $encrypted = null, ?bool $encoded = null): string`
    - `inspect(string $id, ?bool $isEncrypted = null): array`

### Example usage in a controller

[](#example-usage-in-a-controller)

```