README

Lightweight PHP library for generating unique, time-ordered IDs with optional typed token support

Description

limeQ IDs generates compact, URL-safe, time-ordered unique identifiers encoded in Base62. Each ID encodes a millisecond-precision timestamp and a version number into a fixed 16-character string, making IDs both sortable by creation time and inspectable after the fact.

The library provides two layers of functionality. The base Id class handles raw ID generation and timestamp extraction, suitable for any entity that needs a unique identifier. The TypedId class extends this with a token system that prefixes the ID with a 2-character type code and appends an HMAC checksum, producing verifiable, type-safe tokens that can be safely exposed in URLs, APIs or other public-facing contexts. The checksum prevents token forgery and ensures a token cannot be misused as a different entity type.

IDs are generated from a configurable custom epoch (defaulting to January 1, 2026 UTC), keeping the timestamp component compact and relevant for the lifetime of the application.

Features

• 16-character Base62-encoded unique IDs
• Millisecond-precision timestamp embedded in each ID, extractable after generation
• Time-ordered: IDs sort chronologically by default
• Versioned format for future compatibility
• Typed token support with 2-character type codes
• HMAC checksum verification on tokens to prevent forgery and type confusion
• Configurable epoch, checksum length and checksum secret
• No external dependencies beyond PHP's built-in GMP extension

Requirements

• PHP 8.3+
• GMP extension (php-gmp)

Installation

composer require limeq/ids

Usage

See the full documentation for details.

Development

See the source on GitLab: https://gitlab.com/limeq/ids.

Contribution Guidelines

If you have suggestions or would like to help contribute to this project, please contact me.

If this project has been helpful, you can support ongoing development at:
Buy Me a Coffee

Authors

• Ian S Goldstein

Version History

See CHANGELOG.md

License

This project is licensed under the BSD 3-Clause License:
See the LICENSE file for details.

Contact

Please reach out through the project's website:

• limeQ