PHPackages alesitom/hybrid-id - 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. alesitom/hybrid-id ActiveLibrary[Utility & Helpers](/categories/utility) alesitom/hybrid-id ================== Compact, time-sortable unique ID generator for PHP. Drop-in UUID/ULID alternative with base62 encoding, Stripe-style prefixes, and configurable entropy profiles. v4.3.0(2mo ago)0144[4 issues](https://github.com/alesitom/hybridId_package/issues)[2 PRs](https://github.com/alesitom/hybridId_package/pulls)2MITPHPPHP >=8.3CI passing Since Feb 14Pushed 2mo agoCompare [ Source](https://github.com/alesitom/hybridId_package)[ Packagist](https://packagist.org/packages/alesitom/hybrid-id)[ RSS](/packages/alesitom-hybrid-id/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (10)Dependencies (3)Versions (64)Used By (2) HybridId ======== [](#hybridid) **Compact, time-sortable unique identifiers for PHP** [![Packagist Version](https://camo.githubusercontent.com/0710634a33a9bd2aad099508707b4557ff1b5c93c6b14367a84750a070a04b87/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f616c657369746f6d2f6879627269642d69642e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/alesitom/hybrid-id)[![PHP Requirement](https://camo.githubusercontent.com/69b71adcbece7bb41d495e987456ae81d08bc678a1bb492b530a647686fcf4fb/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f616c657369746f6d2f6879627269642d69642e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/alesitom/hybrid-id)[![License](https://camo.githubusercontent.com/9571bebed6056c6ab99207c652bf3fedc16ce45afe0506075e73527741c12b4d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f616c657369746f6d2f6879627269642d69642e7376673f7374796c653d666c61742d737175617265)](https://github.com/alesitom/hybridId_package/blob/main/LICENSE)[![Tests](https://camo.githubusercontent.com/f6f4df8a13108143c156fb20d34a522cad79801ad88e813b3f5e3d5c2f288b60/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f616c657369746f6d2f68796272696449645f7061636b6167652f63692e796d6c3f7374796c653d666c61742d737175617265266c6162656c3d7465737473)](https://github.com/alesitom/hybridId_package/actions)[![Coverage](https://camo.githubusercontent.com/173a4864a48d56d293124ad58e5f2609e551708885ffa1e8524e01f02ebc731b/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f6769746875622f616c657369746f6d2f68796272696449645f7061636b6167653f7374796c653d666c61742d737175617265)](https://codecov.io/gh/alesitom/hybridId_package)[![PHPStan](https://camo.githubusercontent.com/38722f611b1083b1ea52358c73c42c40d08de176989d463cd9d588d25b97da48/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d6c6576656c2532306d61782d626c75653f7374796c653d666c61742d737175617265)](https://phpstan.org/) A space-efficient alternative to UUID with configurable entropy profiles, Stripe-style prefixes, and an instance-based API. Generate chronologically sortable, URL-safe identifiers 33-56% smaller than canonical UUIDs — with zero dependencies. Why HybridId? ------------- [](#why-hybridid) FeatureHybridIdTypeIDKSUIDUUIDv7NanoIDCUID2Length16-24 chars26 chars27 chars36 chars21 chars24 charsConfigurable sizeYesNoNoNoNoNoType prefixesYesYesNoNoNoNoTime-sortableYesYesYesYesNoNoMetadata extractionFullPartialPartialPartialNoneNoneZero dependenciesYesVariesVariesYesVariesVariesRange queriesYesNoNoNoNoNoMulti-node safeYesYesNoYesN/AN/ARandom entropy47.6 - 83.4+ bits~80 bits128 bits74 bits~126 bits~120 bitsInstallation ------------ [](#installation) ``` composer require alesitom/hybrid-id ``` Requires PHP 8.3, 8.4, or 8.5 (64-bit). No external dependencies. Quick Start ----------- [](#quick-start) ``` use HybridId\HybridIdGenerator; $gen = new HybridIdGenerator(node: 'A1'); $id = $gen->generate(); // 0VBFDQz4A1Rtntu09sbf $id = $gen->generate('usr'); // usr_0VBFDQz4A1Rtntu09sbf $id = $gen->compact('log'); // log_0VBFDQz6xK9mLp2w $id = $gen->extended('txn'); // txn_0VBFDQz7A1pBKVwwn2xiF0 ``` Profiles -------- [](#profiles) Three built-in profiles with different size/entropy tradeoffs: ProfileLengthStructureRandom entropyUse case`compact`168ts + 8rand47.6 bitsInternal PKs, low-scale apps`standard`208ts + 2node + 10rand59.5 bitsGeneral purpose (default)`extended`248ts + 2node + 14rand83.4 bitsHigh-scale, public-facing IDs``` Standard / Extended: Compact (no node): 0VBFDQz4 A1 Rtntu09sbf 0VBFDQz4 xK9mLp2w |______| |_| |_________| |______| |________| ts node random ts random ``` - **ts** (8 chars): Millisecond timestamp in base62. Enables chronological sorting. - **node** (2 chars, standard/extended): Server/process identifier. Prevents cross-node collisions. - **rand** (variable): Cryptographically secure random bytes via `random_bytes()`. Custom profiles are available via `ProfileRegistry` — see [API Reference](docs/api-reference.md#custom-profiles). Configuration ------------- [](#configuration) ``` use HybridId\HybridIdGenerator; // Standard profile with explicit node (recommended for production) $gen = new HybridIdGenerator(node: 'A1'); // Explicit profile $gen = new HybridIdGenerator(profile: 'extended', node: 'A1'); // Compact — no node needed $gen = new HybridIdGenerator(profile: 'compact'); // From environment variables (HYBRID_ID_PROFILE, HYBRID_ID_NODE, HYBRID_ID_BLIND, HYBRID_ID_BLIND_SECRET) $gen = HybridIdGenerator::fromEnv(); ``` By default, standard and extended profiles **require** an explicit node to prevent accidental collisions in production. Pass `requireExplicitNode: false` for local development. Prefixes -------- [](#prefixes) Stripe-style prefixes make IDs self-documenting: ``` $gen->generate('usr'); // usr_0VBFDQz4A1Rtntu09sbf $gen->generate('ord'); // ord_0VBFDQz5A1xiF0G9pBKV ``` Rules: 1-8 chars, lowercase alphanumeric, starts with a letter. All extraction and validation methods handle prefixed IDs transparently. Database -------- [](#database) ### Column sizing [](#column-sizing) ProfileNo prefixWith prefix (max 3)With prefix (max 8)`compact``CHAR(16)``VARCHAR(20)``VARCHAR(25)``standard``CHAR(20)``VARCHAR(24)``VARCHAR(29)``extended``CHAR(24)``VARCHAR(28)``VARCHAR(33)`### Collation (MySQL/MariaDB) [](#collation-mysqlmariadb) Base62 uses mixed case (`A` != `a`). You **must** use `ascii_bin` or `utf8mb4_bin` collation — the default `utf8mb4_0900_ai_ci` will silently break uniqueness and sort order. ``` CREATE TABLE users ( id CHAR(20) COLLATE ascii_bin NOT NULL PRIMARY KEY, ... ); ``` PostgreSQL and SQLite are case-sensitive by default — no special collation needed. ### Storage efficiency [](#storage-efficiency) FormatSizeSavings vs UUIDUUID (canonical)CHAR(36)—ULIDCHAR(26)28%TypeIDVARCHAR(34)6%HybridId compactCHAR(16)56%HybridId standardCHAR(20)44%HybridId extendedCHAR(24)33%Smaller primary keys improve B-tree index density and reduce page splits. Time-sorted layout eliminates the random-insert penalty of UUID v4. See [Database Guide](docs/database.md) for time-range queries, NoSQL patterns, and migration strategies. Security -------- [](#security) **Not for secrets.** Do NOT use HybridId for security tokens, session IDs, API keys, or password resets. The timestamp is predictable — use `random_bytes()` with 128+ bits for those. **Standards alignment:** - [RFC 9562](https://www.rfc-editor.org/rfc/rfc9562): UUIDv8 compliant via `UuidConverter::toUUIDv8()` - CSPRNG: `random_bytes()` backed by OS-level cryptographic random - [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986): URL-safe base62, no percent-encoding needed - Rejection sampling eliminates modulo bias (NIST SP 800-90A aligned) **What HybridId is NOT:** not OWASP ASVS V2.6 compliant, not constant-time in validation, timestamps are predictable by design (same as UUIDv7). Blind Mode ---------- [](#blind-mode) HMAC-hashes the timestamp and node with a per-instance secret, making creation time unextractable. Same length and format — an observer cannot tell if an ID is blind. ``` $gen = new HybridIdGenerator(node: 'A1', blind: true); $id = $gen->generate('usr'); // usr_ ``` See [Blind Mode](docs/blind-mode.md) for details on what works, what changes, and when to use it. UUID Interoperability --------------------- [](#uuid-interoperability) Convert between HybridId and RFC 9562 UUIDs: MethodLosslessNotes`UuidConverter::toUUIDv8()` / `fromUUIDv8()`YesProfile auto-detected on decode`UuidConverter::toUUIDv7()` / `fromUUIDv7()`NoTimestamp-preserving, needs profile hint`UuidConverter::toUUIDv4Format()` / `fromUUIDv4Format()`NoLossy, NOT a true UUIDv4Compact and standard profiles only. Prefixed IDs are rejected — strip prefix first. See [UUID Interoperability](docs/uuid-interoperability.md) for full examples and compatibility matrix. Framework Integrations ---------------------- [](#framework-integrations) PackageFrameworkInstall[hybrid-id-laravel](https://github.com/alesitom/hybrid-id-laravel)Laravel 11/12`composer require alesitom/hybrid-id-laravel`[hybrid-id-doctrine](https://github.com/alesitom/hybrid-id-doctrine)Doctrine DBAL 4 / ORM 3`composer require alesitom/hybrid-id-doctrine`See [Dependency Injection & Testing](docs/dependency-injection.md) for `IdGenerator` interface, DI wiring, and framework examples. Requirements ------------ [](#requirements) - PHP 8.3, 8.4, or 8.5 (64-bit) - No external dependencies Learn More ---------- [](#learn-more) TopicLinkFull API (validation, parsing, metadata, sorting, custom profiles)[docs/api-reference.md](docs/api-reference.md)UUID conversion (v8, v7, v4-format)[docs/uuid-interoperability.md](docs/uuid-interoperability.md)Database (time-range queries, NoSQL, migration from UUID)[docs/database.md](docs/database.md)Blind mode (HMAC-hashed timestamps)[docs/blind-mode.md](docs/blind-mode.md)CLI reference[docs/cli.md](docs/cli.md)Dependency injection & testing[docs/dependency-injection.md](docs/dependency-injection.md)Internals (clock drift, concurrency, design decisions)[docs/internals.md](docs/internals.md)Upgrading (v1 → v2 → v3 → v4)[UPGRADING.md](UPGRADING.md)Changelog[CHANGELOG.md](CHANGELOG.md)License ------- [](#license) MIT ### Health Score 46 — FairBetter than 93% of packages Maintenance84 Actively maintained with recent releases Popularity14 Limited adoption so far Community12 Small or concentrated contributor base Maturity63 Established project with proven stability Bus Factor1 Top contributor holds 98.4% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~0 days Total 24 Last Release 82d ago Major Versions v1.4.1 → v2.0.02026-02-14 v2.2.0 → v3.0.02026-02-16 v3.2.2 → v4.0.02026-02-17 PHP version history (2 changes)v1.0.0PHP >=8.2 v1.1.1PHP >=8.3 ### Community Maintainers ![](https://www.gravatar.com/avatar/027a2a89c88ec6e75a1acd67c7149eb5828555771423544a686adca49bf817d1?d=identicon)[CheerfulBox8976](/maintainers/CheerfulBox8976) --- Top Contributors [![alesitom](https://avatars.githubusercontent.com/u/22220729?v=4)](https://github.com/alesitom "alesitom (127 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (2 commits)") --- Tags stripeuuidsortableulidprefixidbase62unique-idtime-sortablesnowflakecompact ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/alesitom-hybrid-id/health.svg) ``` [![Health](https://phpackages.com/badges/alesitom-hybrid-id/health.svg)](https://phpackages.com/packages/alesitom-hybrid-id) ``` ### Alternatives [symfony/uid Provides an object-oriented API to generate and represent UIDs 610280.0M754](/packages/symfony-uid)[identifier/identifier Common Interfaces and Factories for Identifiers 3226.2k1](/packages/identifier-identifier)[ramsey/identifier A PHP library for generating and working with identifiers, including UUIDs, ULIDs, and Snowflakes 603.0k1](/packages/ramsey-identifier)[infocyph/uid UUID (RFC 4122 + Unofficial/Draft), ULID, Snowflake ID, Sonyflake ID, TBSL (library exclusive) generator! 105.1k](/packages/infocyph-uid)[pugx/shortid-php An implementation of shortid in PHP 52588.5k3](/packages/pugx-shortid-php)[michalsn/codeigniter4-uuid UUID and ULID package for CodeIgniter 4 with support for Model. 4728.7k4](/packages/michalsn-codeigniter4-uuid) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)