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 do I install and configure glhd/bits for Laravel?
- Run `composer require glhd/bits` to install. Configure `BITS_WORKER_ID` (0–31) and `BITS_DATACENTER_ID` (0–31) in your `.env` for each server/datacenter. Avoid collisions by ensuring uniqueness across workers. Set `BITS_EPOCH` (e.g., `2023-01-01`) to define the minimum timestamp for generated IDs.
- Can I use this package with Laravel Eloquent models?
- Yes. Use the `HasSnowflakes` trait to auto-generate Snowflake IDs for Eloquent models. It integrates with migrations, queries, and Livewire components. Example: `php artisan make:model Post -t=HasSnowflakes`.
- What Laravel versions does glhd/bits support?
- The package supports Laravel 8.x, 9.x, and 10.x. It requires PHP 8.0+. Check the [GitHub releases](https://github.com/glhd/bits/releases) for version-specific notes. No major breaking changes are expected for these versions.
- How do I handle ID generation in serverless environments like Laravel Vapor?
- Serverless functions (e.g., Vapor) share the same worker/datacenter IDs, risking collisions. Use a centralized ID generator (e.g., Redis-backed `CacheSequenceResolver`) or implement locking mechanisms. The package includes a warning about this in the README.
- Does glhd/bits work with PostgreSQL/MySQL for primary keys?
- Yes. Store IDs as `BIGINT UNSIGNED` (PostgreSQL/MySQL) or Laravel’s `unsignedBigInteger`. The 64-bit format avoids collisions and enables efficient range queries (e.g., `WHERE id > last_id`). No hashing is needed.
- How do I customize the bit layout for non-Snowflake IDs?
- Extend the `Bits` base class to define custom bit sequences (e.g., hybrid time+entity-type). Example: Override `getTimestampBits()` or `getWorkerBits()` in a subclass. The package supports Sonyflake and fully custom formats.
- What’s the maximum number of workers/datacenters supported?
- The package limits you to **1024 workers total** (5-bit datacenter ID + 5-bit worker ID). Plan capacity upfront for large-scale deployments. For example, 32 datacenters × 32 workers each = 1024 total. Exceeding this requires a custom resolver.
- How do I test Snowflake ID generation in Laravel?
- Use `Bits::setTestNow()` to mock timestamps for deterministic testing. Avoid Carbon’s global test time quirks. Example: `Bits::setTestNow(now()->addDays(1))` to simulate future IDs. Works with PHPUnit and Pest.
- What happens if servers have unsynchronized clocks (NTP issues)?
- Clock skew causes ID gaps or duplicates. Mitigate this by using a time service (e.g., Chrony/NTP) or a centralized time source (e.g., AWS Time Sync). The package assumes synchronized servers; manual handling is required for unsynchronized environments.
- Are there alternatives to glhd/bits for Laravel?
- Alternatives include `ramsey/uuid` (UUIDs), `vlucas/phpdotenv` (for config), or `spatie/laravel-activitylog` (for auditing). For Snowflake-like IDs, consider `ramsey/snowflake` (PHP port) or `sony/sonyflake` (Node.js). Choose based on your need for time-sortable, distributed IDs.
Weaver
How can I help you explore Laravel packages today?