Laravel Model Tools Laravel Package

Getting Started

Laravel Model Tools v0.1.0 is a focused utility package for models that need a public UUID-style reference while keeping internal database IDs private. It requires PHP 8.3+ and Laravel 11, 12, or 13.

Start with the package README, then check the published/package configuration for the default reference column name, any model-specific overrides, and route model binding behavior. The migration generator is the next place to look because the trait expects the reference column to exist before models write references.

Minimal setup:

composer require malsanyang/laravel-model-tools:^0.1
php artisan model-tools:reference-migration pages
php artisan migrate

use Illuminate\Database\Eloquent\Model;
use MalSanyang\ModelTools\Concerns\HasReference;

class Page extends Model
{
    use HasReference;
}

A good first use case is a Page model exposed at /pages/{page}: keep the internal id private, expose the UUID reference in URLs/API payloads, and let route model binding resolve by reference. For non-route lookups, use Page::referenceOrFail($reference) in controllers or services where a missing reference should produce a 404-style failure.

Implementation Patterns

• Adopt the trait per model, not globally. Add HasReference to models that are publicly addressable or externally referenced. This keeps the package’s behavior scoped and avoids surprising UUID generation on internal-only tables.
• Generate one migration per table. Run php artisan model-tools:reference-migration <table> for each table that needs a reference column, inspect the generated migration, then migrate. Confirm the generated column is the intended name and has the appropriate unique index for your data.
• Use references at the boundary. Accept and return UUID references in routes, API resources, form requests, and external links. Keep internal IDs for joins, foreign keys, and internal admin queries. API resources should expose reference and hide/omit id.
• Route binding workflow. Configure reference-based route model binding when public routes should resolve by UUID rather than primary key. Define routes normally, e.g. /pages/{page}, and ensure the binding configuration and model’s route key point at the same reference column. Verify 404 behavior for unknown or malformed references.
• Lookup helpers. Use Model::reference($reference) when a missing result is acceptable, and Model::referenceOrFail($reference) when the caller expects a model or a failure. Prefer referenceOrFail() in controller actions that should not continue with null.
• Model-specific column names. Use the package-wide default for most models, and model-specific overrides only where a table already has a differently named public identifier. Keep the migration column, model override, and route-binding configuration aligned.
• Existing records need a backfill plan. For tables with existing rows, add the reference column in a way that allows backfilling, populate references for existing records, then enforce uniqueness/non-null constraints if desired. Do not assume the migration alone gives old rows usable references.
• Optional BaseModel. The package provides an optional base model with HasReference, soft deletes, and datetime casts. Use it only if that inheritance is a good fit; otherwise the trait is the less invasive choice.
• Treat references as immutable. External links, bookmarks, and API clients may store references. Avoid workflows that regenerate them on ordinary updates. If the model is updated frequently, confirm the package’s update behavior and guard against accidental rotation.
• Test the public contract. Add feature tests for route binding by reference, referenceOrFail() 404 behavior, JSON output containing reference but not id, and behavior for soft-deleted records if using the optional BaseModel.

Gotchas and Tips

• v0.1.0 is early. Pin ^0.1 and review the README/changelog before upgrading. Expect the public API and configuration details to evolve more than in a mature package.
• Migration order matters. The reference column must exist before the trait generates and persists references. Deploy the migration before enabling the trait on a model in production.
• Backfill before enforcing constraints. Adding a non-null unique reference column to a populated table can fail or leave existing rows unusable. Prefer a nullable column, backfill, then tighten constraints.
• Confirm update behavior. The release notes say references are generated on create or update. Verify whether an update rotates an existing reference. If it does, avoid mass updates or model saves that could invalidate public links, and consider explicitly preserving the reference where needed.
• Do not mass-assign references from request input. Let the package generate references. Keep reference out of $fillable unless you have a deliberate, controlled use case.
• Keep route binding and column names consistent. A mismatch between the configured reference column, the model-specific override, and the actual database column will produce confusing 404s or SQL errors. Check the generated migration and binding config together.
• Clear cached config after changes. If route binding or column names are configured through Laravel config, run the usual config-cache refresh in deployment after changing package settings.
• Soft deletes change route binding expectations. If using the optional BaseModel with soft deletes, decide whether public routes should resolve trashed models. Use explicit withTrashed() behavior only where intended.
• Package discovery is enabled by default. No manual provider registration should be needed. If your application disables package discovery, register the provider manually and run composer dump-autoload.
• reference() vs referenceOrFail(). Use the first only when null is meaningful; use the second for controller/service paths where a missing model should fail fast.
• Plan redirects for old ID-based URLs. Once public routes switch from IDs to references, old links using numeric IDs will stop resolving unless you add redirects or compatibility handling.
• Inspect generated migrations before running them. Especially on large tables, confirm index creation and column nullability match your deployment strategy.