Resource Index Link Laravel Package

Getting Started

Start by upgrading to v1.0.5 and checking the package’s resource registration/config area for the new resource-key option. The default behavior remains id, so existing resources should continue to work unchanged.

First use case: expose a resource whose public identifier is a UUID or slug instead of the primary key. Register that resource with the alternate key, ensure the underlying model can resolve by that key, and verify both successful lookup and 404 behavior.

Where to look first:

• The resource class/config entry where keys are declared.
• Route definitions or implicit route-model binding setup.
• The model’s route key behavior, if the package delegates lookup to Eloquent.
• The response payload/resource links, to confirm the alternate key is used consistently.

Implementation Patterns

• Keep id as the default. Only opt into alternate keys for resources that need stable public identifiers.
• Configure per resource. Prefer setting the key on the specific resource rather than changing a global default, unless all resources share the same key strategy.
• Align model and resource keys. If routing/lookup uses Eloquent binding, make sure the model’s route key matches the configured resource key.
• Use UUIDs/slugs for public APIs. Keep numeric primary keys internal and expose the alternate key in URLs and resource payloads.
• Validate uniqueness. Alternate keys must be unique and indexed before using them for resource lookup.
• Update links and references. Any generated URLs, relationship links, or API clients that expect id must be updated to use the configured key.
• Test mixed resources. It is valid to have some resources keyed by id and others by uuid or slug; cover both in integration tests.

Typical flow:

1. Add or identify the alternate key column.
2. Backfill and add a unique index.
3. Configure the resource key.
4. Ensure route binding/lookup resolves by that key.
5. Update tests and API consumers.

Gotchas and Tips

• No breaking change expected. v1.0.5 adds capability; id remains the standard default.
• Do not confuse primary key with public resource key. The database can still use id while the API exposes uuid.
• Route binding is the common failure point. If implicit binding still resolves by id, set the model’s route key or bind explicitly.
• Watch type assumptions. UUIDs and slugs are strings; avoid casting or validating them as integers.
• Clear config/cache after changes. Run php artisan config:clear and relevant cache clears when toggling resource-key configuration.
• Test 404s and invalid keys. Confirm malformed or missing alternate keys return the expected not-found response.
• Check serialization. Ensure resource responses, links, and nested references use the configured key consistently.
• Debug with route parameters and model resolution. Inspect the bound route parameter, the model’s route key, and the final resource payload when lookups behave unexpectedly.
• Extension point: use the alternate-key support as the boundary for public identifiers; keep internal joins and foreign keys on the primary key unless intentionally exposing them.