Laravel Eloquent Extended Laravel Package

Getting Started

1. Install and pin:

   composer require soyhuce/laravel-eloquent-extended:^1.8
   

   1.8.0 is a compatibility release: the only functional signal is that the test suite now runs against Laravel 12. There are no new APIs and no breaking changes — the dependabot PR (fetch-metadata 2.2.0 → 2.3.0) is CI-only. If you are still on Laravel 9/10/11, nothing forces an upgrade; if you are planning a Laravel 12 move, this release is the one to target.
2. Confirm your constraints line up before touching code: check composer.json in the package for the illuminate/* and php ranges, then composer why-not soyhuce/laravel-eloquent-extended 1.8.0 in your app to see whether anything blocks it.
3. Where to look first, in this order:
   • README.md — the feature table is the source of truth for what is actually exposed; the package ships more than the changelog will ever tell you.
   • src/ — most of the surface area is traits and query-builder macros, so a grep -r "trait " src/ gives you the opt-in points in about ten seconds.
   • tests/ — the package's own test suite is the best usage documentation; each test is a working example you can paste into a tinker session.
4. First use case: pick the single noisiest model in your app (the one with the most repeated scopes/query plumbing) and apply the package's trait to it behind a short-lived branch. Run your existing suite — if everything stays green, you have a safe adoption path. Do not retrofit every model in one PR.

Implementation Patterns

• Opt in per model, not globally. Create or reuse an App\Models\BaseModel that uses the package trait and extends Illuminate\Database\Eloquent\Model, then let models inherit. This keeps the blast radius to one file and makes it trivial to revert.
• Treat it as an additive layer over the query builder. The value is in shortening repeated chains (scopes, casting helpers, find-or-fail variants). Adopt it where you would otherwise write a private scope or a repository method — not as a replacement for your domain-level query objects.
• Upgrade in a two-step rhythm: composer update soyhuce/laravel-eloquent-extended --with-all-dependencies in isolation, run the suite, then fold it into the framework upgrade. Because 1.8.0 only widens framework support, it is a safe "free" upgrade to land before a Laravel 12 migration so the package is not the thing blocking you.
• Mirror the package's CI matrix locally. Its Laravel 12 job is what gives you the compatibility guarantee; if your app still runs Laravel 10 in CI, add a matrix entry on 12 with the package at ^1.8 before you migrate production.
• Static analysis is part of the integration. Eloquent extensions usually confuse Larastan/PHPStan because return types widen on the builder. Add the package to your phpstan.neon ignoreErrors or stub list, and run analysis in the same PR that introduces the trait so the baseline does not drift.
• Test with factories plus query assertions. Because behaviour lives in the builder layer, assert on generated SQL (->toSql() / DB::listen) for at least one test per adopted helper — this is what catches silent changes on the next minor bump.

Gotchas and Tips

• Trait conflicts are the #1 failure mode. Packages like spatie/laravel-sluggable, wildside/userstamps, or your own BaseModel traits frequently override the same Eloquent methods. PHP resolves same-named trait methods by declaration order with no warning; use insteadof/as explicitly, and put the package trait in a predictable position.
• Method-name collisions with your own macros. If you already registered Builder::macro() helpers with the same name, whichever registers last wins and the failure looks like a logic bug, not a conflict. Grep your AppServiceProvider before adopting.
• A patch/minor bump does not mean "no runtime change." 1.8.0 is effectively CI + dependabot, but the changelog is generated from PR titles, so framework-constraint changes may be invisible. Diff composer.json between 1.7.1 and 1.8.0 — that is the real compatibility contract.
• Octane / long-running workers. Caches or static state inside Eloquent extension packages can leak between requests. After upgrading, smoke-test under Octane (or php artisan octane:start --watch) rather than only under php artisan serve.
• Debugging: when a helper returns something unexpected, drop to Model::query()->toSql() and getBindings() before reading package source; nine times out of ten the scopes interact in an order you did not expect.
• Extension points before forking. Eloquent's Builder::macro, custom casts, and Model::resolveRelationUsing usually cover what you would otherwise patch into the package. Only fork if you need to change behaviour of an existing method.
• Pin to ^1.8 and read the package source for anything undocumented. This package's README lags the code; the src/ tree is small enough to read in a sitting and is more reliable than guessing at method signatures.
• Upgrade cadence: watch for the next release after a new Laravel major — the pattern here (tests-only bump to support a new framework version) means compatibility tends to lag the framework by one minor. Budget for that in your migration timeline.