Globalid Laravel Laravel Package

Getting Started

• Install with composer require tonysm/globalid-laravel, then publish the config (php artisan vendor:publish --tag="globalid-config" — check the package README for the exact tag in 1.5.0, since the locator config shape changed in this release).
• Look at config/globalid.php first. In 1.5.0 the locator registry is the single source of truth: a GID can only be decoded back to a model that has an explicitly registered locator. Read the locators array before writing any code, because an empty/partial registry is now a hard failure rather than a silent fallback.
• Confirm APP_KEY is set in every environment. GIDs are encrypted payloads; a missing or mismatched key means every encoded string from another environment is undecodable.
• First use case: hide auto-increment IDs in a JSON API. Register a locator for Post, then in an ApiResource return 'id' => GlobalId::encode($this), and in the controller accept the GID, decode it, and 404 on failure. That single round-trip exercises encoding, config registration, and decoding — if all three work, the rest of the package is variations on the same theme.

Implementation Patterns

• Encode at the boundary, decode at the boundary. Treat the GID as a transport format only: encode when serialising out (API resources, Inertia props, signed URLs, broadcast payloads), decode as the first thing a controller or form request does. Never store a GID in a database column or use it as a foreign key.
• Route model binding is the highest-leverage integration — bind the GID parameter directly so validation and 404 handling happen before your controller body runs. Keep a manual GlobalId::decode() path for endpoints that take a GID inside a request body rather than the URL.
• Queued jobs and events: pass the GID string, decode inside handle(), and re-fetch the model. This keeps the payload small and avoids serialising a stale Eloquent instance, and it survives the model being updated between dispatch and execution.
• Custom locators for anything that isn't a plain Eloquent model: a uuid-keyed model, a morph aliased model, or a composite key. The locator is where you own the model → id and id → model mapping, so this is also the seam for multi-tenant scoping — resolve the model inside the tenant context in find() rather than globally.
• Pair with policies. A GID is an identifier, not an authorisation token. Decoding a valid GID from another tenant must still hit a policy check; the encryption guarantees opacity, not access control.
• Tests: keep a helper that round-trips encode/decode, and add one explicit test per registered locator asserting an unknown-model GID fails. That test is what catches the 1.5.0 behaviour change for you.

Gotchas and Tips

• 1.5.0 removed the general fallback. Previously an encoded payload naming an unregistered model class could still resolve; now only registered locators are returned. Anything relying on implicit resolution — a model encoded without a locator entry, a polymorphic relation whose type isn't registered — will fail at decode time. Audit GlobalId::encode() call sites against the config before upgrading, and grep for morph maps.
• Encryption key rotation is now supported, so plan for APP_PREVIOUS_KEYS. Decode with the current key list, but remember a re-encode after rotation produces a different string: any GID embedded in a cached response, a previously sent email, or a stored ETag will still decode but won't match a freshly generated one. Compare on decoded class plus primary key, never on the GID string. Also check whether the encoded form is deterministic — if it isn't (random IV), GIDs are unsuitable as cache keys, dedupe keys, or anything requiring stable equality.
• Losing a key is unrecoverable. Old GIDs from a retired key become permanently undecodable, so keep previous keys in the rotation list for at least as long as your longest-lived outbound link (emails, webhooks, shared URLs).
• Debugging decode failures: distinguish three cases — malformed/tampered payload (key mismatch), well-formed payload with no matching locator (config gap), and locator found but model missing (deleted record). Log the exception class, not the raw GID, and return 404 to the client in all three.
• Performance: decoding issues a query. Decoding inside a loop over 50 items is a silent N+1 — decode once, then eager load from the resolved models, or batch-decode before serialising.
• Extension points: the locator classes and the config file are the supported seams. Subclass or replace a locator for custom behaviour (soft-deleted models, scoped lookups) rather than wrapping GlobalId in a service, so route binding and any internal decode paths pick up your logic too.
• GIDs are longer than integers; confirm your URL columns, log truncation, and any client-side regex that assumed a numeric ID actually accommodate them.