Laravel Eloquent Plus Laravel Package

Getting Started

• Install with an explicit constraint (composer require dev-toolbelt/laravel-eloquent-plus:^1.4) rather than *, so the minor bump from 1.3.2 is deliberate. Laravel package discovery should register the service provider automatically; check for a publishable config (php artisan vendor:publish --provider="DevToolbelt\...") before you write any code.
• Where to look first: the 1.4.0 release notes are only a compare link (1.3.2...1.4.0), which tells you nothing about behaviour. Treat the diff itself as the documentation — skim changed source files for anything touching query building, model hydration, or serialization, then read the README section for the feature you intend to use. Do this before, not after, you wire it into a model.
• First use case: pick one small, well-tested model and apply the package's trait/base-model to it only. Run your existing test suite plus a manual ->toSql() / ->toRawSql() check on the queries that model produces. If the generated SQL is identical to what you had before, the package is safe to widen; if it isn't, you've found the 1.4.0 behaviour change on a model that has coverage.

Implementation Patterns

• Adopt behind your own base model. Have App\Models\BaseModel extend the package's model (or use its trait), and let all domain models extend yours. This gives you a single file to edit when the package changes behaviour, and a single file to revert if 1.4.x turns out to be a bad fit.
• Keep package calls in the query layer, not the controllers. Scopes, custom builders, and eager-load helpers compose well inside repositories/actions; sprinkled through controllers they become untraceable when a query starts behaving differently after an upgrade.
• Canary-then-rollout. Apply to one model, then one bounded feature (e.g. a reporting endpoint), then the rest. Because the changelog is opaque, your rollout plan is your risk management.
• Pair with guardrails you already have. Model::preventLazyLoading() and Model::preventSilentlyDiscardingAttributes() in non-production catch the two failure modes these packages most often introduce: masked N+1s and silently ignored mass-assignment changes.
• Test against factories, not fixtures. If the package alters hydration, casts, or toArray(), factory-built models exercised through real assertions surface it faster than seeded data.
• Log query counts around adoption. A DB::listen counter or Debugbar snapshot before/after on your heaviest endpoint is the cheapest regression test for "did 1.4.0 change how many queries this runs?"

Gotchas and Tips

• The changelog is a black box. A bare compare link on a minor bump is not a promise of "no breaking changes" — for Eloquent-extension packages, minor versions routinely change generated SQL, eager-load strategy, or serialization output while still being semver-legal. Diff src/ yourself or pin to 1.3.2 until you have.
• Global side effects are the real risk. Traits and base models apply everywhere they're used, including inside queued jobs, console commands, and third-party packages that touch your models. Behaviour you validate in a request may still differ in a worker — test one job path too.
• Watch these specific surfaces: soft deletes and global scopes interacting with package-added constraints; toArray()/toJson() shape changes breaking API contracts; chunked/bulk operations changing transaction or memory behaviour; and any change to how relations are named or resolved.
• Debugging recipe: reduce to Model::query()->toRawSql(), run EXPLAIN on it, and compare against the same query on 1.3.2. If the SQL moved, the package is the cause and no amount of application-layer debugging will help.
• Extension points to prefer: register behaviour as local scopes and macros on your own base model rather than editing vendored code, and route any package config through the published config file so it's visible in review. Custom casts are usually the cleanest integration seam if you need package-style behaviour without the base-model inheritance.
• Keep a rollback path. Pin the exact version in composer.json, commit the lockfile change separately from any code that adopts 1.4.0 features, and know that composer require ...:1.3.2 is a one-command revert.