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. visus/cuid2

ActiveLibrary

visus/cuid2
===========

A PHP library for generating collision-resistant ids (CUIDs).

6.0.0(5mo ago)421.1M↓43.5%14MITPHPPHP ^8.2CI passing

Since Mar 23Pushed 1mo 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 1mo ago

READMEChangelog (9)Dependencies (13)Versions (11)Used By (4)

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)

A PHP implementation of collision-resistant identifiers that are secure, URL-safe, and horizontally scalable. Perfect for distributed systems where unique identifiers need to be generated across multiple machines without coordination.

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 (Collision-resistant Unique Identifier, version 2) is a modern approach to generating unique identifiers that addresses common issues with UUIDs and other identification systems. This PHP implementation provides:

- **Collision Resistance**: Uses cryptographic hashing (SHA3-512) combined with timestamps, counters, and fingerprints to ensure uniqueness
- **Horizontal Scalability**: Safe to use across multiple machines and processes without coordination
- **Security**: Employs cryptographically secure random generation and hashing
- **URL-Safe**: Uses base36 encoding (0-9, a-z) with lowercase letters only
- **Sortability**: Incorporates timestamps for chronological ordering
- **Configurable Length**: Supports identifier lengths from 4 to 32 characters (default 24)

You can read more about CUIDs from the [official project website](https://github.com/paralleldrive/cuid2).

Architecture
------------

[](#architecture)

### CUID2 Structure

[](#cuid2-structure)

Each CUID2 identifier is composed of several components that are combined and hashed to ensure uniqueness:

```
[prefix][hash]

```

- **Prefix** (1 character): Random lowercase letter (a-z)
- **Hash** (remaining characters): Base36-encoded SHA3-512 hash of combined components

### Generation Process

[](#generation-process)

1. **Prefix**: Random lowercase letter for additional entropy
2. **Timestamp**: Current time in milliseconds for sortability
3. **Counter**: Monotonically increasing value (prevents collisions for rapid generation)
4. **Fingerprint**: Machine/process identifier (hostname + PID + environment)
5. **Random Data**: Cryptographically secure random bytes
6. **Hashing**: All components are combined and hashed using SHA3-512
7. **Encoding**: Hash is converted from base16 to base36
8. **Truncation**: Result is trimmed to requested length (minus prefix)

Example output: `p6p168tx2rxtgyehd3p2wz04`

This architecture ensures that even if multiple processes generate CUIDs simultaneously, the combination of timestamp, counter, fingerprint, and random data prevents collisions.

Getting Started
---------------

[](#getting-started)

### Installation

[](#installation)

Install visus/cuid2 via [Composer](https://packagist.org/packages/visus/cuid2):

```
composer require visus/cuid2
```

**Requirements:**

- PHP 8.2 or higher
- SHA3-512 hashing algorithm support (typically available in PHP 7.1+)

**Recommended:**

- GMP extension for optimal performance (60-300x faster base conversion)

### Instance-Based Usage

[](#instance-based-usage)

```