Cuid2 Laravel Package

Product Decisions This Supports

Use this assessment to make or defend the following decisions:

• Identifier strategy for user-visible resources. Choose between auto-increment integers, UUIDv4, UUIDv7/ULID, and CUID2 for IDs exposed in URLs, APIs, webhooks, and exports. CUID2 delivers URL-safe, non-sequential, collision-resistant strings with a configurable length of 4–32 characters (default 24).
• Build vs. buy for ID generation. Avoid building and maintaining a custom generator. This package is MIT-licensed, Composer-installable, dependency-light, and exposes both instance (new Cuid2(10)) and static (Cuid2::generate(10)) APIs.
• Feature-level use cases. Public share links, invoice/project/profile URLs, webhook event IDs, idempotency keys (with caveats), object/file naming, multi-tenant record IDs, seeded fixtures, and any place where an opaque, non-sequential token is useful.
• Horizontal scalability architecture. Generation requires no central coordination. This supports multi-node deployments, queue workers, offline/batch jobs, per-tenant databases, and client-side or edge generation patterns.
• Privacy and abuse posture. Non-sequential IDs reduce enumeration of record counts and avoid leaking business volume through auto-increment gaps.
• Database/index design. Standard string columns (VARCHAR/CHAR) with a chosen length policy; no native UUID type required. Decide a minimum length (e.g., 16–24) because 4–8 character IDs have small spaces (36⁴ ≈ 1.7M) and are unsuitable for high-volume user-facing identifiers.
• Roadmap and migration risk. Adopting now is cheap; if requirements later shift to native UUIDs or strictly time-ordered keys, migration requires a string-column swap plus backfill/dual-write. Keep an internal IdGenerator interface to make this a one-file change.

Important diligence finding: the README claims sortability because a timestamp is embedded, but the timestamp is hashed into a SHA3-512 digest and base36-encoded, so CUID2 strings do not sort chronologically. Treat this as an opaque ID and always store a separate created_at indexing column. If chronological, lexicographically sortable primary keys are a hard requirement, this package is the wrong tool.

Also note: isValid() validates format only, not origin or uniqueness; IDs are not secrets and must not replace auth tokens or API keys.

When to Consider This Package

Adopt when most of these are true:

• The stack is PHP 8.3+ with Composer (Laravel, Symfony, or plain PHP).
• IDs can be stored as strings; you do not need a database-native uuid column or RFC 9562 interop.
• You want URL-safe, non-sequential, coordination-free IDs for public resources at moderate-to-high generation rates.
• GMP is available or installable. The README benchmarks GMP as 60–306x faster for base conversion; the pure-PHP fallback works but may be a throughput concern under heavy load.
• You value a small, auditable surface (static/instance generation, format validation, cached value per instance) over ecosystem size.
• You are comfortable pinning the version and monitoring a low-adoption project (44 stars, effectively 0 dependents). Vendor review, lockfile pinning, and an abstraction layer are prudent.

Look elsewhere when:

• You need strict time-ordered IDs for clustered primary keys — use UUIDv7 or ULID (symfony/uid, ramsey/uuid).
• You need cross-language or standards-based UUID interoperability, database uuid types, or broad tooling support — use ramsey/uuid or symfony/uid.
• You are generating secrets, API keys, signed URLs, password-reset tokens — use a CSPRNG token or HMAC, not an ID library.
• You are on PHP < 8.3 or cannot add GMP and expect very high generation volume.
• You need enterprise support, long-term commercial backing, or a large community with many production references.
• Very short IDs (4–8 chars) are required for UX; the collision space is too small for high-volume use.

How to Pitch It (Stakeholders)

Executive summary. This is a low-cost, MIT-licensed PHP library that replaces hand-rolled ID code with secure, URL-safe, collision-resistant identifiers. It lets services on many machines generate IDs independently, removes a central ID service from the critical path, and stops auto-increment IDs from leaking record volumes in URLs and APIs. Cost is one Composer dependency; the main risks are a small community and single-vendor maintenance, which we mitigate with version pinning and a thin internal interface. Recommended next step: a timeboxed pilot in one service, not an org-wide standard.

For engineering. PHP 8.3 floor; install and enable GMP for a 60–306x improvement in base conversion. API is trivial: Cuid2::generate(), new Cuid2($length), Cuid2::isValid($value, expectedLength: $n). SHA3-512 hashing, secure random source, cached generation, 100% coverage claim, CI and static analysis badges. Three caveats to design around: (1) the embedded timestamp is hashed, so IDs are not chronologically sortable — add a created_at column and never sort by ID for time order; (2) isValid() is format-only, not proof of origin; (3) IDs are identifiers, not secrets.

Decision ask. Approve a two-sprint pilot behind an IdGenerator contract, with a documented minimum length policy, GMP in the container image, and a fallback plan to UUIDv7/ULID if sortable keys or standards interop become requirements.