Globalid Laravel Laravel Package

Product Decisions This Supports

• Opaque public identifiers vs. raw primary keys. GlobalID lets you hand out signed, tamper-evident references to models (in URLs, API payloads, webhooks) instead of sequential IDs. This is a product-level decision about whether record IDs are guessable/enumerable, and it converts a security debate into a small implementation detail.
• Async and cross-service work as a roadmap enabler. Queued jobs, event payloads, and service-to-service handoffs can pass a model reference that survives retries and re-deploys without leaking database internals — relevant if the roadmap includes splitting out workers, queues, or a second service.
• Security/compliance roadmap (this release's headline). 1.5.0 adds encryption key rotation, which means you can commit to a rotation policy (e.g., annual, or on personnel change) without invalidating already-issued identifiers or in-flight job payloads. That is a concrete control to point at in SOC 2 / ISO-style reviews, and it removes "rotation would break everything" as a reason to defer.
• Build vs. buy. The alternative is a hand-rolled signed-ID / encrypted-ID layer (custom casts, middleware, job serialization hooks). This package is the buy option: small surface area, well-understood pattern (port of Rails' GlobalID), low switching cost. Choose buy unless identifiers must be verified by non-PHP services.
• Tighter resolution semantics (behavioral change in 1.5.0). Lookup now returns only registered locators rather than falling back to a general resolver. Product-wise this trades convenience for predictability: identifier resolution becomes an explicit, auditable list of supported models rather than "anything the framework can find." Good for multi-tenant and polymorphic designs where implicit resolution was a footgun; it is also a breaking change for any product surface currently relying on the fallback, so it needs an upgrade note and an inventory of what was being resolved implicitly.
• Use cases to validate against: shareable permalinks to records, unsubscribe/manage links in email, public API resource references, background job arguments, audit log subject references, signed webhook payloads.

When to Consider This Package

Adopt when most of the following hold:

• You are on Laravel/PHP throughout the read path — verification happens inside the same app or a PHP service.
• Records are referenced outside the request that created them: queued jobs, scheduled tasks, emails, webhooks, public links.
• You want identifiers that are signed and non-guessable but do not want to change your primary keys to UUIDs/ULIDs (no migration, no index churn).
• You have or anticipate a key-management requirement — the 1.5.0 rotation support is the reason to look again if you previously deferred on rotation grounds.
• You can tolerate an explicit registration step for every resolvable model (required as of 1.5.0) and will keep that registry current.

Look elsewhere when:

• The API is consumed by non-PHP clients or services that need to decode/verify references themselves — the format is not a cross-language standard you can rely on.
• Your only need is unguessable IDs: native ULID/UUID keys or Hashids-style approaches are simpler and avoid a dependency.
• The identifier appears on extremely hot paths (high-QPS endpoints) where per-request signing/verification cost is measurable — benchmark before committing.
• Identifiers are already public and non-sensitive (catalog slugs, public content), where opacity buys nothing.
• You need stable identifiers that never change format across a long product lifetime and cannot absorb a resolution-semantics change like the one in 1.5.0.

How to Pitch It (Stakeholders)

For executives: A small, low-risk dependency that stops our public links and API payloads from exposing guessable record IDs. The new release (1.5.0) adds key rotation, so we can adopt a scheduled rotation policy — a control auditors ask about — without breaking links already in the wild or jobs already queued. Cost is a dependency plus a short upgrade task; there is no user-visible change.

For engineering: 1.5.0 is a minor-version release with a breaking behavior change: locator resolution no longer falls back to a general resolver and will only return explicitly registered locators. Before upgrading, audit any code path that relied on implicit resolution and register those models; unregistered references will now fail to resolve (expect exceptions on old payloads). Second change is additive: encryption key rotation, which lets old and new keys coexist so previously issued GlobalIDs still verify while new ones are signed with the current key — wire it into your key management and add a rotation runbook. Budget a half-day for the audit and a regression test around job serialization; the upgrade is otherwise mechanical.