PHPackages visus/cuid2 - 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. visus/cuid2 ActiveLibrary[Utility & Helpers](/categories/utility) visus/cuid2 =========== A PHP library for generating collision-resistant ids (CUIDs). 6.0.0(8mo ago)431.1M↓85.2%16MITPHPPHP ^8.2CI passing Since Mar 23Pushed 1w ago2 watchersCompare [ Source](https://github.com/visus-io/php-cuid2)[ Packagist](https://packagist.org/packages/visus/cuid2)[ RSS](/packages/visus-cuid2/feed)WikiDiscussions main Synced 2w ago READMEChangelog (9)Dependencies (13)Versions (13)Used By (6) visus/cuid2 =========== [](#visuscuid2) [![GitHub Workflow Status (with event)](https://camo.githubusercontent.com/87fb29815b3ea2258050037b90df7c5e5efa7b2a787683e1e97ecb6f53116c3a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f76697375732d696f2f7068702d63756964322f63692e796d6c3f7374796c653d666f722d7468652d6261646765266c6f676f3d676974687562)](https://github.com/visus-io/php-cuid2/actions/workflows/ci.yaml) [![Sonar Quality Gate](https://camo.githubusercontent.com/0d4e4dc29005d2605e0909fc149ed36649a9e9381b2d45f77d6f102ee7f9a6a0/68747470733a2f2f696d672e736869656c64732e696f2f736f6e61722f7175616c6974795f676174652f76697375732533417068702d63756964323f7365727665723d6874747073253341253246253246736f6e6172636c6f75642e696f267374796c653d666f722d7468652d6261646765266c6f676f3d736f6e6172636c6f7564266c6f676f436f6c6f723d7768697465)](https://sonarcloud.io/summary/overall?id=visus%3Aphp-cuid2)[![Sonar Coverage](https://camo.githubusercontent.com/d9d8f393aaf43aefb6093b769ce723585fc94ded0fd1a2d43b659527e27ee1df/68747470733a2f2f696d672e736869656c64732e696f2f736f6e61722f636f7665726167652f76697375732533417068702d63756964323f7365727665723d6874747073253341253246253246736f6e6172636c6f75642e696f267374796c653d666f722d7468652d6261646765266c6f676f3d736f6e6172636c6f7564266c6f676f436f6c6f723d7768697465)](https://sonarcloud.io/summary/overall?id=visus%3Aphp-cuid2)[![Sonar Tests](https://camo.githubusercontent.com/42dba5d94b425376c35fca740099456397f63536c589a142aac7fd6b7b53c941/68747470733a2f2f696d672e736869656c64732e696f2f736f6e61722f74657374732f76697375732533417068702d63756964323f7365727665723d6874747073253341253246253246736f6e6172636c6f75642e696f267374796c653d666f722d7468652d6261646765266c6f676f3d736f6e6172636c6f7564266c6f676f436f6c6f723d7768697465)](https://sonarcloud.io/summary/overall?id=visus%3Aphp-cuid2) [![PHP Version](https://camo.githubusercontent.com/54916c5df4d2706b0f9e424e781e525b74b88c5434bb7e93ca0c592621d6056f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f76697375732f63756964322f7068703f7374796c653d666f722d7468652d6261646765)](https://camo.githubusercontent.com/54916c5df4d2706b0f9e424e781e525b74b88c5434bb7e93ca0c592621d6056f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f76697375732f63756964322f7068703f7374796c653d666f722d7468652d6261646765)[![Packagist](https://camo.githubusercontent.com/7dfc3e954646b5d837aeedb24c3fe5d49e4b67fc3a92b850c624753568992425/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f76697375732f63756964323f7374796c653d666f722d7468652d6261646765266c6f676f3d7061636b6167697374266c6f676f436f6c6f723d7768697465266c6162656c3d737461626c65)](https://packagist.org/packages/visus/cuid2)[![Downloads](https://camo.githubusercontent.com/8ab24909831bd7750de80e46c01e261333099168eacc0b70f2ef5424f1d5170a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f76697375732f63756964323f7374796c653d666f722d7468652d6261646765266c6f676f3d7061636b6167697374266c6f676f436f6c6f723d776869746526636f6c6f723d38)](https://camo.githubusercontent.com/8ab24909831bd7750de80e46c01e261333099168eacc0b70f2ef5424f1d5170a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f76697375732f63756964323f7374796c653d666f722d7468652d6261646765266c6f676f3d7061636b6167697374266c6f676f436f6c6f723d776869746526636f6c6f723d38)[![GitHub](https://camo.githubusercontent.com/6778c12937ec443596b09c26bfa8e5ce9a09f2ee63965561c97f881c1778fedf/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f76697375732d696f2f637569642e6e65743f7374796c653d666f722d7468652d6261646765)](https://camo.githubusercontent.com/6778c12937ec443596b09c26bfa8e5ce9a09f2ee63965561c97f881c1778fedf/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f76697375732d696f2f637569642e6e65743f7374796c653d666f722d7468652d6261646765) This library is a PHP implementation of CUID2. CUID2 identifiers are secure, URL-safe, and collision-resistant. You can generate these identifiers on multiple machines at the same time. The machines do not need to coordinate with each other. Table of Contents- [General Overview](#general-overview) - [Architecture](#architecture) - [CUID2 Structure](#cuid2-structure) - [Generation Process](#generation-process) - [Getting Started](#getting-started) - [Installation](#installation) - [Instance-Based Usage](#instance-based-usage) - [Static-Based Usage](#static-based-usage) - [Validation](#validation) - [Considerations](#considerations) - [Performance: GMP Extension](#performance-gmp-extension) - [Contributing](#contributing) General Overview ---------------- [](#general-overview) CUID2 stands for Collision-resistant Unique Identifier, version 2. CUID2 solves common problems with UUIDs and other identifier systems. This PHP library gives you these features: - **Collision resistance**: The library combines a timestamp, a counter, and a fingerprint. It hashes these values with SHA3-512. This method prevents collisions. - **Horizontal scalability**: You can use this library on multiple machines and processes at the same time. The machines do not need to coordinate with each other. - **Security**: The library uses cryptographically secure random data and hashing. - **URL safety**: The library encodes each identifier in base36. It uses only the digits 0-9 and the lowercase letters a-z. - **Sortability**: Each identifier includes a timestamp. You can sort identifiers by time. - **Configurable length**: You can set the identifier length from 4 to 32 characters. The default length is 24 characters. For more information about CUID2, go to the [official project website](https://github.com/paralleldrive/cuid2). Architecture ------------ [](#architecture) ### CUID2 Structure [](#cuid2-structure) Each CUID2 identifier contains several components. The library combines and hashes these components to make the identifier unique. ``` [prefix][hash] ``` - **Prefix** (1 character): a random lowercase letter, from a to z - **Hash** (remaining characters): the SHA3-512 hash of the combined components, encoded in base36 ### Generation Process [](#generation-process) 1. **Prefix**: The library adds a random lowercase letter. This adds entropy. 2. **Timestamp**: The library records the current time in milliseconds. This makes the identifier sortable. 3. **Counter**: The library adds a value that always increases. This prevents collisions when you generate identifiers quickly. 4. **Fingerprint**: The library adds an identifier for the machine and the process. This identifier includes the hostname, the process ID, and environment data. 5. **Random Data**: The library adds cryptographically secure random bytes. 6. **Hashing**: The library combines all components and hashes them with SHA3-512. 7. **Encoding**: The library converts the hash from base16 to base36. 8. **Truncation**: The library trims the result to the length you request, minus the prefix. Example output: `p6p168tx2rxtgyehd3p2wz04` This design prevents collisions. Even when multiple processes generate identifiers at the same time, the timestamp, the counter, the fingerprint, and the random data keep each identifier unique. Getting Started --------------- [](#getting-started) ### Installation [](#installation) Use [Composer](https://packagist.org/packages/visus/cuid2) to install visus/cuid2: ``` composer require visus/cuid2 ``` **Requirements:** - PHP 8.3 or a later version - SHA3-512 hashing support. PHP 7.1 and later versions usually include this support. **Recommended:** - The GMP extension, for better performance. GMP makes base conversion 60 to 300 times faster. ### Instance-Based Usage [](#instance-based-usage) ```