- How do I install visus/cuid2 in a Laravel project?
- Install it with composer require visus/cuid2. The package requires PHP 8.2 or newer. It is a standalone PHP library, so no Laravel service provider or config file is needed; just import the Cuid2 class wherever you generate identifiers.
- Which PHP and Laravel versions does visus/cuid2 support?
- The library requires PHP 8.2 or higher, which rules out legacy Laravel apps still running older PHP versions. Any Laravel release that runs on PHP 8.2+ (Laravel 10, 11 and newer) can use it. If you must support PHP 8.0 or 8.1, look at ramsey/uuid instead.
- How do I use CUID2 as an Eloquent model primary key instead of a UUID?
- Set $incrementing to false and $keyType to 'string' on the model, then assign a CUID2 generated through the package's static API inside booted() or a model factory. Create the database column as CHAR(24) for the default length, or CHAR(n) for a custom length. CUID2 is not a drop-in replacement for UUID columns, so a schema migration is required.
- Can I generate shorter CUID2 IDs for things like feature flags?
- Yes. CUID2 supports configurable lengths, so you can use around 10 characters for low-risk identifiers such as feature flags and the default 24 characters for primary keys. Shorter IDs reduce entropy, so check the length against your collision-resistance requirements before using them on high-volume tables.
- Is visus/cuid2 safe for multi-server or microservice ID generation?
- Yes. CUID2 combines a timestamp, a per-process counter and a fingerprint, then hashes them with SHA3-512, so machines do not need to coordinate with each other. That makes it a good fit for Laravel microservices, queue workers and other multi-process deployments where UUID coordination is impractical.
- How do I validate a CUID2 string in a Laravel form request or API?
- Use the package's validator, Cuid2::isValid(), inside a custom validation rule or a closure in your FormRequest. Validation adds CPU cost, so cache the result if you check the same value repeatedly in middleware. Enforcing the format at the API boundary keeps malformed IDs out of your database.
- Do I need the GMP extension to use visus/cuid2?
- GMP is not strictly required, but it makes the SHA3-512 hashing and base36 conversion much faster; without it the fallback path is dramatically slower under load. If you generate more than roughly 10,000 IDs per second, treat ext-gmp as mandatory. Confirm your Docker image or shared host allows the extension before committing to it.
- Can I query CUID2 IDs by time range, or do they store a sortable timestamp?
- CUID2 starts with a time-based prefix, which gives rough chronological ordering when you sort by the ID column. Unlike ULIDs, that timestamp is not cleanly parseable, so range queries such as 'IDs from the last hour' need a separate created_at column or a SUBSTRING expression on the prefix. Adding created_at is the simplest and most portable fix.
- What is the collision risk with CUID2 in high-volume generation?
- Collisions are extremely unlikely because each ID mixes time, a counter and a fingerprint before SHA3-512 hashing. The realistic edge case is fingerprint collisions when several processes on the same host share a hostname and PID, so add extra entropy if you run many workers per host. Log generation failures and monitor for duplicates in production.
- How does visus/cuid2 compare to ramsey/uuid or ULIDs for Laravel?
- CUID2 produces shorter, URL-safe, base36 identifiers designed for distributed collision resistance, whereas ramsey/uuid produces RFC-compliant UUIDs and ULIDs. CUID2 is not a drop-in replacement for either because the format differs, so existing UUID or ULID columns, route bindings and API contracts need migration. A hybrid approach with both a cuid and a uuid column works well during a transition.