- How do I install kra8/laravel-snowflake in a Laravel application?
- Install it with Composer using composer require kra8/laravel-snowflake; the service provider is auto-discovered so no manual registration is needed. Publish the package config with php artisan vendor:publish and set your worker and datacenter IDs through environment variables. Then add the package trait to the models that should use Snowflake primary keys and declare the id column as an unsignedBigInteger primary key in your migrations.
- Which Laravel and PHP versions does kra8/laravel-snowflake support?
- Check the illuminate/support constraint and PHP minimum in the package's composer.json before adopting, since those bounds move between releases. Version 2.5.0 is the release that adds Laravel 13 support, so gate any Laravel 13 upgrade on that version or newer while confirming Laravel 10, 11, and 12 remain inside the constraint. Recent releases are largely dependency bumps, including a Carbon 2.72.6 pin, so verify that pin against any planned Carbon 3 migration.
- How do I configure the worker ID and datacenter ID for Snowflake IDs?
- After publishing the config file, set the worker and datacenter values via environment variables so each emitting process gets a unique combination. These values occupy the fixed bit fields between the timestamp and the sequence, which caps how many distinct values are available. The important operational rule is that no two running processes may share the same worker and datacenter pair, and that uniqueness is your responsibility rather than something the package can enforce.
- How do I use the Snowflake trait on an Eloquent model?
- Add the package trait to the model and create the table with $table->unsignedBigInteger('id')->primary() instead of the default auto-incrementing big integer. The trait assigns the 64-bit ID when the model is created, so IDs exist before the insert and can be used in queued jobs or multi-table transactions. Verify in the source whether you also need to set $incrementing to false or switch $keyType to string, and confirm there is no collision with other packages that override primary key behavior.
- Why do my Snowflake IDs lose precision in JavaScript clients?
- Snowflake IDs are 64-bit integers and exceed JavaScript's Number.MAX_SAFE_INTEGER, so JSON responses that encode them as numbers are silently rounded and clients then query the wrong record. Cast the ID to a string in your API resources and update your OpenAPI schemas and TypeScript types to match. This is the highest-likelihood production incident when adopting the package, so treat string serialization as part of the migration rather than a follow-up fix.
- What happens if two servers generate the same Snowflake ID?
- If two processes share the same worker and datacenter ID and generate an ID in the same millisecond with the same sequence value, the IDs collide. The result is either a primary key conflict on insert or, worse, silent data corruption if the value is written somewhere without a constraint. Nothing in the package prevents this, so worker ID uniqueness per running process is the critical control you must design and monitor.
- How should I assign worker IDs when running on Kubernetes or ECS autoscaling?
- There is no built-in allocator, and a single static environment variable copied across replicas is a well-known footgun under horizontal autoscaling and overlapping blue-green deployments. Practical options are deriving the ID from the pod ordinal in a StatefulSet, leasing an ID from Redis or the database at startup, or hashing the hostname into the configured bit width. Whatever scheme you pick, keep it within the bit budget the config allows and audit it whenever your deployment topology changes.
- Does kra8/laravel-snowflake handle clock rollback or NTP time drift?
- Snowflake correctness depends on a monotonic clock, and an NTP step-back can produce duplicate IDs unless the implementation explicitly guards against it. The package's rollback behavior, whether it throws, waits for the clock to catch up, or silently overflows the sequence, is not documented in the overview and should be read directly from the source before you rely on it. If the guard is weak or absent, that is a risk you own in production.
- Can I switch an existing auto-increment table to Snowflake IDs?
- Not as a drop-in swap. Changing a primary key type cascades to every foreign key that references it and requires a backfill, so the recommended posture is Snowflake for new tables only and leave legacy tables alone. Avoid mixing primary key types within a single relationship chain, and re-verify integer validation rules, route model binding, and cursor pagination assumptions once IDs are strings. Because IDs become creation-ordered, also note the timing and enumeration signal they expose in public URLs.
- How do I generate a Snowflake ID outside Eloquent and how do I test it?
- The package exposes ID generation through its service layer, so you can resolve it from the container and call it directly for queued jobs or non-model writes; confirm the exact method name against the README and source. For testing, apply the trait to a test model with pinned worker and datacenter values and assert uniqueness and rough time ordering across a batch of generated IDs. Keeping worker IDs deterministic in CI avoids flaky collisions between parallel test processes.