Download the PHP package pikaid/pikaid-php without Composer

PikaID

PikaID is a tiny PHP library that creates unique, short, and sortable IDs —
a modern alternative to UUIDs for your databases, APIs, and distributed systems.

💡 Example Use Case

Imagine you’re building a web app where users can post messages or create orders.
Each new item needs a unique ID so your system can recognize it.

If you use normal numbers (1, 2, 3…), you can have conflicts when several servers create data at the same time.
If you use UUIDs, you get long, messy IDs that are hard to read and don’t follow creation time.

PikaID solves this:

• Every new ID is unique, even if many servers create them at once.
• IDs are short, so they look clean in URLs or logs.
• They are time-ordered, so when you list data, the newest appears last or first automatically.

You can use PikaID to:

• Identify users, orders, invoices, or API resources.
• Name uploaded files safely.
• Tag events or logs across distributed systems.

In short: PikaID gives you clean, safe, and sortable IDs for anything that needs a unique reference.

Pikaid (PHP)

Small · Sortable · Secure ID generator

This is the official PHP implementation. Fully compliant with v1.0.3.

Pikaid is a 26-character, lowercase Base36 identifier, composed of:

• 7-character timestamp (seconds since epoch)
• 19-character cryptographically secure randomness

It’s a modern, compact alternative to UUID and ULID:

• Lexicographically sortable
• Collision-resistant
• Compact binary form (BINARY(17))

📚 Specifications & Benchmarks

See the full technical specs and benchmarks at pikaid/pikaid-specs

⚙️ Requirements

• PHP 7.4+ (PHP 8 recommended)
• ext-gmp (recommended for best performance) or ext-bcmath (optional)
• If neither extension is installed, a pure-PHP fallback is used.

📦 Installation

Install via Composer:

Include Composer's autoloader in your project:

🚀 Basic Usage

🧩 API Reference

Pikaid::generate(): string

Generate a new 26-character string ID.

• Layout: [7 chars timestamp][19 chars randomness]
• Sortable by second.

Pikaid::generateBinary(): string

Generate the binary form directly (BINARY(17)).

• Layout: [5 bytes timestamp (uint40, big-endian)][12 bytes entropy].

Pikaid::toBinary(string $id): string

Convert a string ID to its binary (17 bytes) representation. Throws InvalidArgumentException if the input is not a valid 26-character Pikaid or if the timestamp is out of range.

Pikaid::fromBinary(string $bin): string

Convert binary (17 bytes) back into a 26-char string. Throws InvalidArgumentException if the binary length isn’t exactly 17 bytes.

Pikaid::isValid(string $id): bool

Check if the given string is a valid Pikaid.

• Must be 26 chars long
• Must match regex: /^[0-9a-z]{26}$/

Pikaid::parse(string $id): array

Parse a string ID into its components:

• timestamp → DateTimeImmutable (UTC)
• randomness → lowercase hex string (24 chars = 12 bytes)

Throws InvalidArgumentException on invalid input.

Pikaid::fromDateTime(DateTimeInterface $t): string

Generate a string ID for a specific timestamp (seconds precision).

🔄 Order Guarantee

• String and binary representations sort lexicographically by second:

🛢 Storage Recommendations

Pikaid is designed to be compact and index-friendly, with a predictable layout:

🔹 Option 1: Store as BINARY(17) (Recommended)

Binary form stores exactly 17 bytes:

Table Definition

Insert Example (PHP)

Select Example (PHP)

Benefits

• Small index size = better performance
• Binary comparison matches chronological order
• Perfect for PRIMARY KEY or clustered indexes

🔹 Option 2: Store as CHAR(26) (String)

If you need IDs to remain human-readable directly in SQL queries, store the string form.

Table Definition

Insert Example (PHP)

Select Example (PHP)

Notes

• Slightly larger storage and index compared to BINARY(17)
• Ideal for debugging or manual inspection of IDs

🔄 Order Guarantee

Both BINARY(17) and CHAR(26) maintain natural chronological order:

📄 License

PikaID is free software licensed under the GNU Lesser General Public License, version 3 or any later version (LGPL-3.0-or-later).

In practical terms: you can use this library in both open-source and proprietary applications. You can integrate it into your own codebase, extend it, subclass it, and build commercial or closed-source software on top of it without having to release your whole application under the LGPL.

The main condition is about the library itself:

• if you distribute a modified version of PikaID,
• those modifications to the library must remain available under the LGPL.

This is an intentional choice: the goal is to keep the library easy to adopt in real-world PHP projects while ensuring that improvements to the core engine are contributed back when they are distributed.

For the exact legal terms, see the LICENSE file.

✉️ Contact

For licensing or project-related questions: [email protected]