PHPackages wickedbyte/int-to-uuid - 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. wickedbyte/int-to-uuid ActiveLibrary[Utility & Helpers](/categories/utility) wickedbyte/int-to-uuid ====================== Utility for Bidirectional Conversion of Integer Ids to UUIDs v1.1.0(1mo ago)13195MITPHPPHP ^8.3CI passing Since Dec 11Pushed 1mo ago1 watchersCompare [ Source](https://github.com/wickedbyte/int-to-uuid)[ Packagist](https://packagist.org/packages/wickedbyte/int-to-uuid)[ Docs](https://github.com/wickedbyte/int-to-uuid)[ RSS](/packages/wickedbyte-int-to-uuid/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (3)Dependencies (16)Versions (5)Used By (0) IntToUuid: Integer ID To RFC 9562 UUID Converter ================================================ [](#inttouuid-integer-id-to-rfc-9562-uuid-converter) > **Note:** This is the reference implementation of the [IntToUuid](https://github.com/wickedbyte/int-to-uuid-spec) specification. Bidirectionally encodes a non-negative 64-bit unsigned "id" integer and optional 32-bit "namespace" integer into a valid [RFC 9562 Version 8 UUID](https://www.rfc-editor.org/rfc/rfc9562#section-5.8). The id and namespace integers are encoded to obscure their value and produce non-sequential UUIDs, while guaranteeing uniqueness and reproducibility. This could be used to present an auto-incrementing integer "database id" as a UUID (proxy ID) in a public context, where you would not want to expose an enumerable, sequential value directly tied to your database structure/data. Since the encoded UUID can be converted back into integer namespace and id values at runtime, the UUID does not need to be persisted in the database or otherwise indexed to the ID it represents. In practice, you would want to map namespace values to the different types of data that they represent. For example, you might want to use a namespace of `1`for a user ID, `2` for a post ID, `3` for a comment ID, and so on. This ensures that the UUIDs generated for each type of data are unique within your application. The namespace does not need to be known ahead of time to decode the UUID and is returned along with the decoded id value. **Note:** The integer ID and namespace values are only *encoded* in the UUID, not *encrypted*, and the value can be recovered by a third party with effort. This library is intended to support on-demand conversion between an integer and a UUID, while mitigating basic "user enumeration attacks". Securely encrypting a 64-bit integer in the 122 bits available in a UUID is currently outside the scope of this library. Requirements ------------ [](#requirements) - PHP >= 8.3 - [`ramsey/uuid`](https://github.com/ramsey/uuid) ^4.6 Installation ------------ [](#installation) The preferred method of installation is to use [Composer](https://getcomposer.org/): ``` composer require wickedbyte/int-to-uuid ``` Usage ----- [](#usage) #### Encode Integer ID with Default Namespace to UUID [](#encode-integer-id-with-default-namespace-to-uuid) ``` $id = \WickedByte\IntToUuid\IntegerId::make(42); $uuid = \WickedByte\IntToUuid\IntToUuid::encode($id); echo $uuid->toString(); // 99c45a05-a33b-8544-8024-f4be69401069 ``` #### Encode Integer ID with Custom Namespace to UUID [](#encode-integer-id-with-custom-namespace-to-uuid) ``` $id = \WickedByte\IntToUuid\IntegerId::make(42, 12); $uuid = \WickedByte\IntToUuid\IntToUuid::encode($id); echo $uuid->toString(); // dee5e9d2-c3e4-8273-b0d5-b3b5307bf749 ``` #### Decode UUID to ID and Namespace Integers [](#decode-uuid-to-id-and-namespace-integers) ``` $uuid = \Ramsey\Uuid\Uuid::fromString('99c45a05-a33b-8544-8024-f4be69401069'); $id = \WickedByte\IntToUuid\IntToUuid::decode($uuid); echo $id->value; // 42 echo $id->namespace; // 0 $uuid = \Ramsey\Uuid\Uuid::fromString('dee5e9d2-c3e4-8273-b0d5-b3b5307bf749'); $id = \WickedByte\IntToUuid\IntToUuid::decode($uuid); echo $id->value; // 42 echo $id->namespace; // 12 ``` Specification ------------- [](#specification) See the full specification at ### Conversion Algorithm [](#conversion-algorithm) Encoding an integer uses a deterministic seed based on the [xxHash](https://github.com/cyan4973/xxhash) XXH3 hash of the concatenated binary strings packed from the id and namespace values. The first 32-bits of the hash are used as the contiguous `time_hi_and_version`, `clk_seq_hi_res`, and `clock_seq_low` fields. To comply with the RFC 9562 Version 8, the seed is multiplexed with the required Version and Variant bits, leaving 26 bits of deterministic "pseudo-randomness". The encoded id is the id integer packed as a 64-bit binary string XOR the xxHash hash of the namespace and seed. The encoded namespace is the namespace integer packed as a 32-bit binary string XOR the xxHash hash of the seed. The resulting octets are arranged into a valid UUID and a new `UuidInterface` (from the [`ramsey/uuid`](https://github.com/ramsey/uuid)library) is returned. Decoding is the reverse of the encoding process: the UUID octets are split into the encoded id, encoded namespace, and seed binary strings, XOR is applied to the encoded values and corresponding hashes, and a "checksum" seed is produced from the decoded binary strings, which are then unpacked into integer values. If the seed value from the UUID does not match the checksum seed, then UUID does not encode valid information, and an exception is thrown. An exception is also thrown if the UUID passed into the decode function is not a valid Version 8 UUID. #### RFC 4122 UUID Field Names and Bit Layout [](#rfc-4122-uuid-field-names-and-bit-layout) ``` 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | time_low | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | time_mid | time_hi_and_version | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |clk_seq_hi_res | clk_seq_low | node (0-1) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | node (2-5) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ``` #### RFC 9562 UUIDv8 Field Names and Bit Layout [](#rfc-9562-uuidv8-field-names-and-bit-layout) ``` 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | custom_a | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | custom_a | ver | custom_b | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |var| custom_c | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | custom_c | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ``` #### Encoded Integer ID Field and Bit Layout [](#encoded-integer-id-field-and-bit-layout) ``` 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | namespace | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | id (0-1) | seed (0-1) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | seed (2-3) | id (2-3) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | id (4-7) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ``` ### Why RFC 9562 Version 8? [](#why-rfc-9562-version-8) > Note: RFC 9562 incorporates and obsoletes the more well-known UUID specification, [RFC 4122](https://www.rfc-editor.org/rfc/rfc4122). It is common to see "on spec" UUIDs referred by either "RFC 9562" or "RFC 4122". The other UUID versions defined by [RFC 9562](https://www.rfc-editor.org/rfc/rfc9562) have distinct generation algorithms and properties. Versions 1, 2, 6, and 7 are based on the current timestamp. Version 3 (Name-Based MD5) and Version 5 (Name-Based SHA1) are deterministic for a string "name" and "namespace" values, but are unidirectional because they are based on hash functions. Version 4 (Random) comes the closest to fulfilling our needs: 122 of the 128 bits are randomly/pseudo-randomly generated. The same algorithm used here *could* be used to generate encoded UUIDs that *look* like Version 4 UUIDs, but they would not be technically compatible with the RFC definition or have the expected universal uniqueness property. Version 8 defines an RFC-compatible format for experimental or vendor-defined UUIDs. The definition allows for both implementation-specific uniqueness and for the embedding of arbitrary information, both of which are key to this particular use case. Contributing ------------ [](#contributing) Contributions are welcome, please see [CONTRIBUTING.md](CONTRIBUTING.md) for more information, including reporting bugs and creating pull requests. Coordinated Disclosure ---------------------- [](#coordinated-disclosure) Keeping user information safe and secure is a top priority, and we welcome the contribution of external security researchers. If you believe you've found a security issue, please read [SECURITY.md](SECURITY.md) for instructions on submitting a vulnerability report. License ------- [](#license) This project is licensed under the MIT License. See [LICENSE.md](LICENSE.md) for details. ### Health Score 46 — FairBetter than 93% of packages Maintenance92 Actively maintained with recent releases Popularity16 Limited adoption so far Community12 Small or concentrated contributor base Maturity53 Maturing project, gaining track record Bus Factor1 Top contributor holds 96.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 ~55 days Total 3 Last Release 38d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/1cb54d6b31124b5524b1e1b39e87f3a902a7ff5bab5526c34ccf45691a89fe1d?d=identicon)[andysnell](/maintainers/andysnell) --- Top Contributors [![andysnell](https://avatars.githubusercontent.com/u/7006523?v=4)](https://github.com/andysnell "andysnell (27 commits)")[![rodrigoprimo](https://avatars.githubusercontent.com/u/77215?v=4)](https://github.com/rodrigoprimo "rodrigoprimo (1 commits)") --- Tags uuidrfc4122rfc9562id obfuscationprimary keyid-encodinguuid-encodinguuid-obfuscationIntToUuid ### Code Quality TestsPHPUnit Static AnalysisPHPStan, Rector Type Coverage Yes ### Embed Badge ![Health badge](/badges/wickedbyte-int-to-uuid/health.svg) ``` [![Health](https://phpackages.com/badges/wickedbyte-int-to-uuid/health.svg)](https://phpackages.com/packages/wickedbyte-int-to-uuid) ``` ### Alternatives [webpatser/laravel-uuid Laravel integration for webpatser/uuid - High-performance drop-in UUID replacements (15% faster than Ramsey). Provides Str macros, HasUuids trait, facades, and casts. RFC 4122/9562 compliant. 1.8k17.3M128](/packages/webpatser-laravel-uuid)[pascaldevink/shortuuid PHP 7.4+ library that generates concise, unambiguous, URL-safe UUIDs 5951.8M15](/packages/pascaldevink-shortuuid)[mhujer/jms-serializer-uuid Uuid serializer and deserializer for JMS Serializer library 291.2M4](/packages/mhujer-jms-serializer-uuid)[thamtech/yii2-uuid Yii 2 UUID Helper 35347.9k7](/packages/thamtech-yii2-uuid)[your-app-rocks/eloquent-uuid Adds support for UUID generation automatically for Models Eloquents. 6888.5k2](/packages/your-app-rocks-eloquent-uuid)[gamez/ramsey-uuid-normalizer Symfony Normalizer and Denormalizer for ramsey/uuid 16619.1k3](/packages/gamez-ramsey-uuid-normalizer) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)