Download the PHP package visus/cuid2 without Composer
On this page you can find all versions of the php package visus/cuid2. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Package cuid2
Short Description A PHP library for generating collision-resistant ids (CUIDs).
License MIT
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package cuid2
visus/cuid2
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
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.
Architecture
CUID2 Structure
Each CUID2 identifier contains several components. The library combines and hashes these components to make the identifier unique.
- 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
- Prefix: The library adds a random lowercase letter. This adds entropy.
- Timestamp: The library records the current time in milliseconds. This makes the identifier sortable.
- Counter: The library adds a value that always increases. This prevents collisions when you generate identifiers quickly.
- Fingerprint: The library adds an identifier for the machine and the process. This identifier includes the hostname, the process ID, and environment data.
- Random Data: The library adds cryptographically secure random bytes.
- Hashing: The library combines all components and hashes them with SHA3-512. The result is a raw 64-byte digest, not a hex string.
- Encoding: The library converts the raw digest bytes directly to base36. It does not build an intermediate hex string.
- 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
Installation
Use Composer to install 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 base36 conversion roughly 9 to 30 times faster, depending on the input size.
Instance-Based Usage
Static-Based Usage
Validation
The isValid() method checks whether a string matches the CUID2 format.
[!NOTE] This method validates only the format. It does not guarantee that this library generated the value. It does not guarantee that the value is globally unique.
Considerations
Performance: GMP Extension
This library converts a raw hash digest to base36 during identifier generation. It reads the digest bytes directly and never builds an intermediate hex string, on either the GMP path or the pure-PHP fallback. For the best performance, install and enable the GMP extension. This step is strongly recommended.
Performance Comparison (GMP median vs. the pure-PHP Utils::bytesToBase36() fallback):
| Digest Size | GMP Median | Pure PHP Median | Performance Gain |
|---|---|---|---|
| SHA3-512 (64 bytes) | 0.36 μs | 11.3 μs | ~31x faster |
| 32 bytes | 0.22 μs | 4.7 μs | ~21x faster |
| 16 bytes | 0.15 μs | 2.2 μs | ~15x faster |
| 8 bytes | 0.14 μs | 1.3 μs | ~9x faster |
Key Takeaways:
- GMP makes base36 conversion roughly 9 to 30 times faster, depending on the input size.
- Larger digests gain more benefit from GMP. CUID2 uses SHA3-512, the largest digest in this comparison.
- Without GMP, the library uses a pure-PHP fallback: it packs the digest into base-2³² limbs and divides them by 36⁵ per pass, extracting 5 base36 digits at a time. See ARCHITECTURE.md for details.
- Both implementations produce the same results.
- These measurements are illustrative. The digest sizes differ from the ones in this repository's benchmark suite. Run
composer dev:benchmarkto measure pure-PHP timings on your own hardware.
Installation:
To check whether the extension is loaded, run one of these commands. On Unix, run php -m | grep gmp. On Windows, run php -m | findstr gmp.
Contributing
You can contribute to this project. See CONTRIBUTING.md for detailed guidelines about:
- How to set up your development environment
- How to run tests and code quality checks
- Coding standards and conventions
- How to submit a pull request
This project follows the Conventional Commits standard. This project maintains 100% code coverage.
