flametrench/ids

Prefixed wire-format IDs for Flametrench. UUIDv7 storage, self-describing public identifiers.

v0.2.0 2026-04-28 02:22 UTC

Requires

• php: ^8.3
• symfony/uid: ^7.0

Requires (Dev)

• pestphp/pest: ^3.0

Apache-2.0

• NDC Digital, LLC

• id
• uuid
• identifier
• uuidv7
• flametrench

README

Prefixed wire-format identifiers for Flametrench.

use Flametrench\Ids\Id;

Id::generate('usr');
// → "usr_0190f2a81b3c7abc8123456789abcdef"

Id::encode('org', '0190f2a8-1b3c-7abc-8123-456789abcdef');
// → "org_0190f2a81b3c7abc8123456789abcdef"

Id::decode('usr_0190f2a81b3c7abc8123456789abcdef');
// → ['type' => 'usr', 'uuid' => '0190f2a8-1b3c-7abc-8123-456789abcdef']

Id::isValid('usr_0190f2a81b3c7abc8123456789abcdef');           // true
Id::isValid('usr_0190f2a81b3c7abc8123456789abcdef', 'org');    // false

Why prefixed IDs

Flametrench uses UUIDv7 in storage and prefixed strings on the wire. The wire format is self-describing: usr_... is a user, org_... is an organization, ses_... is a session. This is the Stripe playbook, and it pays off in every log line, support ticket, and debugger session.

The specification details live at flametrench/spec/docs/ids.md. Implementations in other languages follow the same format.

Install

composer require flametrench/ids

Requires PHP 8.3 or newer. Ships with a dependency on symfony/uid for UUID handling.

Registered type prefixes

The specification reserves the following prefixes:

Prefix	Resource	Spec version
usr	User	v0.1
org	Organization	v0.1
mem	Membership	v0.1
inv	Invitation	v0.1
ses	Session	v0.1
cred	Credential	v0.1
tup	Authorization tuple	v0.1
mfa	MFA factor	v0.2
shr	Share token	v0.2

Implementations must not invent prefixes outside the specification. New prefixes are added through the specification's RFC process.

Testing

composer install
composer test

The package uses PEST. The test suite covers encoding, decoding, validation, generation, round-trip properties, and sortability of generated IDs.

License

Apache License 2.0. Copyright 2026 NDC Digital, LLC.