Flaky Laravel Package

Getting Started

This is a pre-1.0 package (0.0.6), so treat the public API as unstable and pin the exact version in composer.json ("vendor/package": "0.0.6") rather than using a caret constraint until you've read the changelog for each bump.

Minimal setup:

1. composer require vendor/package and, if the package ships one, php artisan vendor:publish --tag=package-config to get the config file into config/. Check config/package.php for the encoder/alphabet/epoch-style settings before touching code.
2. Look first at the package's service provider to see what is bound into the container (typically a generator/encoder singleton) and whether a facade alias is registered. That tells you whether to inject an interface or resolve the concrete class.
3. First use case: wrap it behind your own thin service or cast so the package's class names don't leak into controllers. A typical first win is a HasPublicId trait or an IdCast on an Eloquent model, so $model->public_id is generated automatically and route model binding works via getRouteKeyName().

Given the 0.0.6 rewrite of the encoding internals, your very first task on a fresh install is a smoke test: generate an ID, decode it, assert round-trip, and assert the output shape (length, character set) matches what your database columns and front-end validation expect.

Implementation Patterns

Wrap, don't sprinkle. Keep package calls in one place — a PublicIdGenerator service bound in your own provider — and inject that everywhere else. With an internal rewrite landing at 0.0.6, a single seam means a one-file change if the API shifts again in 0.1.0.

Eloquent casting. Use a custom cast or model booted() hook to populate the encoded column on creating. Prefer generating on the model rather than in the database so the value is available before the row is persisted (needed for events, jobs, and URLs built in the same request).

Route model binding. If the encoded value differs from the primary key, override getRouteKeyName() to the encoded column and keep the numeric/ULID key internal. Add a global scope or explicit where on the encoded column so unauthenticated lookups return 404 rather than a type error on decode failure.

Batch generation. The 0.0.6 distribution change targets high-volume generation. If you are bulk-inserting (imports, seeders, event fan-out), generate IDs in a loop and insert in chunks; do not assume the values are monotonic or sortable. insert() bypasses model events, so generate IDs explicitly in the array payload rather than relying on the cast.

Queues and long-running workers. Because the rewrite changes internal state handling, restart queue workers (php artisan queue:restart) and Horizon after deploying, and clear config/route caches. If the generator was previously resolved once as a singleton with internal counters, confirm that repeated make() calls in a daemon don't repeat values across jobs.

Testing. Never assert on a literal generated ID — the 0.0.6 distribution change makes exact values unstable across versions. Assert on round-trip decode, uniqueness across N generations (a collect(range(1, 10_000))->unique() check is cheap and directly exercises the collision fix), and character-set validity.

Gotchas and Tips

• IDs generated before 0.0.6 may not decode with it. The encoding process was rewritten, so verify backwards compatibility against a fixture of pre-upgrade IDs. If encoding is not stable, you need a migration strategy: keep the old column, decode with a pinned old version, or backfill new identifiers.
• Do not assume the ID format is stable. Length, alphabet, and distribution changed in this release. Any DB column sized to the old length, front-end regex, or log parser matching a prefix needs re-checking. Size columns generously (string(255) or a length you control) rather than exactly.
• The collision improvement is probabilistic, not a guarantee. The release notes reduce the possibility of collisions; that is not the same as enforcement. Keep a unique index on the encoded column and handle QueryException on duplicate key by regenerating, especially under load.
• Not a security primitive. Encoded IDs should not be treated as unguessable capability tokens. Keep authorization checks; if the package offers obfuscation, remember that's not encryption.
• Distribution changes can break "random-looking" expectations. If anything downstream (rate limiting, sharding, cache-key bucketing) assumed an even spread of leading characters, re-verify. The new distribution is tuned for collision resistance under bursts, which is not necessarily uniform.
• Config caching bites. After changing config or upgrading, run php artisan config:clear && php artisan config:cache. A stale cached config referencing a renamed encoder option is the most common post-upgrade failure mode in pre-1.0 packages.
• Debugging decode failures. Wrap decode calls and log both the input and the exception; a silent null returned for a malformed ID will surface much later as a confusing 404. Fail loudly in non-production.
• Extension points. Before the API settles, prefer composition (your own generator class that delegates to the package) over extending the package's classes — subclassing internals across a rewrite is where upgrades break. If the package exposes a driver/encoder contract, bind your implementation in a service provider instead of editing vendor config.
• Treat every 0.0.x bump as potentially breaking. Read the diff of the service provider and config file, not just the release notes, and keep a small integration test suite covering round-trip, uniqueness, and route binding so an upgrade fails in CI rather than in production.