Download the PHP package niktomo/konayuki without Composer

Konayuki

English | 日本語

粉雪 (konayuki) — powdery snow. Each flake is tiny, unique, and falls in vast quantities.

High-throughput 63-bit Snowflake ID generator with a Hexagonal architecture: pluggable counter backends (APCu / File / Redis), pluggable worker_id strategies (FileLock / Fixed / IP-based / Hostname-hash), and pluggable timestamp strategies — all driven by .env and config/konayuki.php.

• 2.4M+ IDs / sec on a single APCu-backed PHP process
• 63-bit fits inside PHP signed int — safe for JSON, MySQL BIGINT, etc.
• k-sortable time-prefixed IDs (great for indexes)
• Zero collisions across 8 forked processes × 10K IDs in CI

⚠️ Read this before deploying to multiple hosts

The default worker_id strategy is file-lock, which is safe for a single host only.

If you scale out to 2 or more web servers (5 hosts, 200 hosts, 1000 hosts, ...) and leave the default in place, every host independently claims worker_id=0, 1, 2..., all hosts produce overlapping ID space, and you will get duplicate Snowflake IDs across hosts. This is silent — there is no error message; you simply discover collisions in your database later.

Before deploying to N hosts (N ≥ 2), pick one of these strategies:

N hosts	Recommended	Why
2–50	hostname-hash or fixed	Stable, no collision if hostnames stable
50–500	fixed (orchestrator-injected) or hostname-hash	Same; fixed is deterministic
500–1024	fixed only — KONAYUKI_MAX_WORKERS=1024 is the hard cap	Hash strategies' collision probability becomes unacceptable
> 1024	Increase worker_bits first (e.g. 12 bits → 4096 workers), then fixed	10 bits is exhausted

Jump to → worker_id Strategy for full details and .env snippets.

Table of Contents

• Quick Start
• Configuration Matrix
• Concurrency Model
• AtomicCounter (per-ID atomicity)
• worker_id Strategy (boot-time uniqueness)
• Bit Layout
• Epoch
• Timestamp Strategy
• Benchmarks
• Why Konayuki?
• FAQ

Quick Start

Laravel auto-discovers the service provider. Out of the box, the defaults work for single-host PHP-FPM / FrankenPHP / Octane:

Default config (no .env needed):

Configuration Matrix (pick your shape)

Find your row by host count first, then by orchestration. Copy the .env, done.

Single host (1 host)

Multi-host (2–1024 hosts) — file-lock is unsafe here

Very large fleets (>1024 hosts)

10-bit worker_id is exhausted at 1024 workers. Either:

1. Increase worker_bits to 12 (4096 workers) — costs you 2 bits of sequence; sustained burst capacity drops from 4096 to 1024 IDs / ms / worker
2. Use sharding at the application layer (multiple Konayuki instances with disjoint worker_id ranges)

Full env reference is in config/konayuki.php.

Concurrency Model (what makes next() multi-process safe)

Konayuki has only one PHP-userland lock — the boot-time flock for worker_id. The per-call sequence increment uses a single atomic CPU instruction in the C extension, with no PHP-side mutex, no flock, no semaphore. The two mechanisms below are easy to confuse, so the distinction is spelled out explicitly:

Why both are needed

TL;DR: flock is for "who am I" (boot-time identity, runs once). apcu_inc is for "what's the next number" (runtime atomicity, runs every call). Both are required; neither replaces the other.

apcu_inc() is fully multi-process safe — implemented as an atomic operation in the APCu C extension (backed by a pthread mutex or spinlock depending on build). The "lock" is invisible from PHP userland and adds no syscall on the fast path. From an application code perspective, AtomicCounter::nextSequence() looks like an ordinary function call.

AtomicCounter (per-ID atomicity)

AtomicCounter is the per-millisecond sequence counter. The choice determines throughput, durability after process restart, and what infrastructure must be running.

Comparison

When to switch

The APCu + per-host worker_id combination is the production sweet spot: each host runs its own APCu counter (no network hop), and the unique worker_id makes cross-host collisions impossible by construction.

.env examples

Note: KONAYUKI_COUNTER switching is wired in config/konayuki.php. If you forked an older copy, ensure the counter block is present.

APCu sizing (apc.shm_size)

Konayuki itself uses ≪ 2 MB. Sizing depends on co-tenants in the same APCu segment:

worker_id Strategy (boot-time uniqueness)

worker_id is the unique identifier for the running process / host that gets baked into every ID. Picking the wrong strategy is the #1 cause of duplicate IDs across hosts.

⚠️ file-lock is single-host only

file-lock (the default) coordinates worker_id slots within one host's filesystem. Two hosts cannot see each other's lock files, so:

Symptom: no errors, no warnings — duplicate BIGINT PKs appear silently in your database, often noticed weeks later when a unique constraint finally trips.

Rule of thumb: if you have ≥ 2 web/app servers, change KONAYUKI_WORKER_ID_MODE to one of fixed, hostname-hash, ip-hash, or ip-last-octet.

Reminder (see Concurrency Model): the strategy below runs once at boot to resolve worker_id to an int. After that, IdGenerator just stores the int as a field — there is no per-next() cost regardless of which strategy you pick. The per-call atomicity is handled separately by AtomicCounter.

Decision flowchart

All 5 modes

1. file-lock (default — single host)

Each PHP process atomically claims the next free slot via flock. The kernel releases the lock on process exit, so crashes / kill -9 cannot leak slots.

Use when: one host, multi-process (PHP-FPM workers, queue workers, cron). Do not use when: multiple hosts — each host would independently claim worker_id=0, 1, 2... → guaranteed collision.

Performance note: acquire() runs once per process at boot (when IdGenerator is constructed), not per ID. Measured cost: ~1.5 µs / boot (see Benchmarks). After boot, worker_id is a plain int field — zero cost on next().

2. fixed (orchestrator-injected)

The caller (Kubernetes / ECS / Nomad / CI) injects a guaranteed-unique ID via env.

Use when: ECS ECS_TASK_INDEX, k8s StatefulSet ordinal (hostname ends in -N), or any system that gives each instance a numeric index. Do not use when: the value is not actually unique (e.g. two pods both reading WORKER_ID=0 from a shared ConfigMap).

3. ip-last-octet (deterministic, /24 only)

Uses the last octet of the host's primary IPv4 as worker_id.

Use when: all hosts share a single /24 subnet (or smaller). DO NOT USE when: hosts span multiple subnets — 10.0.0.17 and 10.0.1.17 collide on worker_id=17 → ID collision.

4. ip-hash (probabilistic, multi-subnet)

Hashes crc32(primary_ip) % max_workers. Works for IPv4 and IPv6.

Use when: multi-host, multi-subnet, no orchestrator injection available. Collision probability: roughly N²/(2·max_workers). At 8 hosts with max_workers=1024, ~3% chance of any pair colliding. Increase max_workers (or upgrade to fixed) when at scale.

5. hostname-hash (Kubernetes StatefulSet)

Hashes crc32(gethostname()) % max_workers. Stable when hostnames are stable.

Use when: Kubernetes StatefulSet (pods get stable name-0, name-1 ordinals), on-prem with stable hostnames. DO NOT USE when: Docker default randomized hostnames (e.g. 7f3a2b1c4d) — every restart gives a new worker_id, defeating the point.

Common worker_id env keys

Bit Layout

• 41 bits timestamp → ~69.7 years from custom epoch
• 10 bits worker_id → 1024 unique workers
• 12 bits sequence → 4096 IDs per ms per worker

Sum must equal 63 (1 sign bit reserved). Customize via config/konayuki.php:

Trade-offs:

Epoch

The 41-bit timestamp is relative to a custom epoch (not Unix epoch). Default: 2026-01-01 00:00:00 UTC.

Operational rules (from ADR-0015):

1. Choose epoch ≥ project release date — earlier wastes lifespan.
2. Never change epoch after deploy — past IDs would re-decode to wrong timestamps.
3. Same epoch in all environments (dev/staging/prod) — required for cross-env comparisons.
4. Never rewind the system clock — Snowflake assumes monotonic ms; rewinds can produce duplicate IDs.

Sequence Strategy

The 12-bit sequence portion of each ID can start at either 0 (default) or a random value per ms window. The choice has zero impact on uniqueness — the (workerId, ms, sequence) tuple stays unique either way — and the trade-off only affects intra-millisecond ordering.

Why no "jittered timestamp" mode anymore? An earlier prototype perturbed the timestamp itself to spread shard distribution. That broke k-sortable ordering for zero gain — sequence randomization achieves the same shard-distribution goal while keeping ms-level ordering intact. The timestamp strategy is now real only.

Benchmarks

Measured in Docker (PHP 8.4, APCu) on Apple Silicon:

Adapter comparison (50K IDs each):

WorkerIdAllocator boot-time cost (acquire() runs once per process at IdGenerator construction — not per ID):

file-lock is ~10× slower than the hint-based allocators because it actually opens a file and calls flock, but at 1.5 µs / boot it is invisible compared to typical PHP-FPM / Octane request latency (>1 ms). After boot, all five allocators have the same runtime cost: zero (the resolved worker_id is just an int field on IdGenerator).

Run all benchmarks yourself:

Why Konayuki?

FAQ

What happens if I deploy the default file-lock to 200 web servers?

You get silent duplicate IDs across hosts. Each host independently runs its own FileLockWorkerIdAllocator, sees its own empty lock directory, and claims worker_id=0 first. Hosts B, C, ... all do the same. Now hosts A, B, C all generate IDs as worker_id=0, and the (timestamp, worker_id, sequence) tuple is no longer globally unique → Snowflake collisions.

There is no runtime error. The collision rate depends on your write traffic and the number of hosts that hit the same millisecond. Symptoms surface later as:

• Integrity constraint violation: 1062 Duplicate entry on BIGINT PK inserts
• Inserts that should have failed silently overwriting due to upserts
• Foreign-key references suddenly pointing to wrong rows

Fix: set KONAYUKI_WORKER_ID_MODE to fixed / hostname-hash / ip-hash / ip-last-octet before going to production, and verify with vendor/bin/konayuki-doctor on each host.

Are 63-bit IDs safe to send to clients?

Keep SnowflakeId as a PHP int inside your application. Convert to string only at the API boundary.

JavaScript / TypeScript — Number.MAX_SAFE_INTEGER is 2^53 - 1; Snowflake IDs reach 2^62. Always send as a JSON string, parse with BigInt on the client:

C# / Unity — long is 64-bit signed, fully covers the 63-bit range:

Obfuscation with Kasumi — if you want to hide sequential nature and internal structure from public API consumers:

Why APCu instead of Redis by default?

• 200× faster (no network hop)
• No additional infrastructure
• Per-host APCu + unique worker_id is collision-free by construction

Switch to Redis when you genuinely need cross-host atomicity (rare for ID generation).

What happens if APCu gets wiped (server restart, OOM)?

Konayuki detects this via a sentinel key (apcu_add returns true only on key creation). On detection, it sleeps 1 ms before continuing — guaranteeing the new sequence cannot collide with any pre-wipe ID in the same millisecond.

Can I use this without Laravel?

Yes. The Konayuki\Laravel\ namespace is opt-in. Construct IdGenerator directly:

How do I diagnose problems?

Checks PHP version, APCu, locking type, apcu_inc correctness, available memory, flock support.

Contributing

License

MIT