Weave Code
Bits Laravel Package
glhd/bits
Generate unique 64-bit IDs in PHP for distributed systems. Create Twitter Snowflake, Sonyflake, or custom bit-sequence identifiers. Configure worker/datacenter IDs and a custom epoch to avoid collisions across servers.
At a glance
Frequently asked questions about Bits
- How does glhd/bits compare to UUIDs or ULIDs in Laravel for storage efficiency?
- glhd/bits generates 64-bit IDs (8 bytes) instead of UUIDs (16 bytes) or ULIDs (16 bytes), reducing storage by 50% or more. Unlike UUIDs, IDs are sortable by creation time (embedded timestamp) and avoid database joins for time-based queries. For Laravel, this means smaller columns (bigint vs. char/string) and faster indexing.
- Can I use glhd/bits with Laravel Livewire for reactive UI components?
- Yes, glhd/bits includes built-in Livewire property synthesizers (e.g., `SnowflakeSynth`) to generate and display IDs in real-time. The package handles serialization automatically, so IDs work seamlessly in Livewire forms, tables, or reactive components without manual conversion.
- What Laravel versions does glhd/bits officially support?
- glhd/bits is officially supported for Laravel 10–13. It leverages Eloquent traits (e.g., `HasSnowflakes`) and Carbon v2/v3, which are compatible with these versions. For older Laravel versions (9.x), you may need to manually patch Carbon dependencies or use the `setTestNow()` method for testing.
- How do I configure worker and datacenter IDs for a multi-server Laravel deployment?
- Set `BITS_WORKER_ID` (0–31) and `BITS_DATACENTER_ID` (0–31) in your `.env` file. For example, `BITS_WORKER_ID=1` and `BITS_DATACENTER_ID=0` for a single server. Each datacenter must have a unique `DATACENTER_ID`, and workers within the same datacenter must have unique `WORKER_ID`s. Avoid collisions by assigning IDs per environment (e.g., dev/staging/prod).
- Does glhd/bits work with serverless Laravel (e.g., Vapor) or AWS Lambda?
- glhd/bits requires manual coordination for serverless environments like Vapor or Lambda due to stateless execution. You’ll need to reserve IDs externally (e.g., DynamoDB, SQS queues) or use a centralized ID service. The package doesn’t natively support Lambda’s ephemeral nature, but you can integrate it with AWS Step Functions or a Redis-backed resolver for distributed locking.
- How do I query records by time range using Snowflake IDs in Laravel?
- Use the `firstForTimestamp()` method to generate a boundary ID, then query with `where('id', '>', boundary)`. For example, `User::where('id', '>', app(MakesSnowflakes::class)->firstForTimestamp(now()->subDays(1)))` retrieves records from the last 24 hours. This replaces `created_at` joins entirely, improving query performance.
- What happens if I exceed the default 1024-worker limit (5-bit datacenter + worker IDs)?
- If you need more than 1024 workers, customize the bit layout by extending `SnowflakeGenerator` or using Sonyflake’s 39-bit timestamp (which supports ~69 years). For high-cardinality pools, consider sharding IDs by region or service (e.g., `orders_*` vs. `users_*`) or using a hybrid approach with additional bits for worker IDs.
- Can I migrate from UUIDs/ULIDs to glhd/bits without downtime?
- Yes, use a dual-write strategy: add a `snowflake_id` column alongside your existing `id` (UUID/ULID), then populate both during transitions. Update queries to use the new IDs gradually, and finally drop the legacy column. Tools like Laravel migrations and database triggers can automate the sync. Test thoroughly with `setTestNow()` for deterministic ID generation.
- How does glhd/bits handle clock skew in distributed Laravel environments?
- glhd/bits uses a Redis-backed `CacheSequenceResolver` to mitigate clock skew across servers. This ensures millisecond precision for timestamp bits, even if servers’ system clocks drift. For single-server setups, Redis is optional, but distributed systems require it to avoid ID collisions. Configure the resolver in your `config/bits.php` or via environment variables.
- Are there alternatives to glhd/bits for Snowflake IDs in PHP/Laravel?
- Alternatives include `ramsey/uuid` (for UUIDs), `ulid/php` (for ULIDs), or custom implementations like `bramus/shortid`. However, glhd/bits is the most Laravel-native option, offering Eloquent integration, Livewire support, and built-in time-based querying. For Sonyflake specifically, glhd/bits is one of the few PHP libraries that supports the full 39-bit timestamp format out of the box.
Weaver
How can I help you explore Laravel packages today?