- How do I eager load relations defined on a pivot model in Laravel Eloquent?
- This package extends Eloquent's BelongsToMany handling so you can traverse into relations on the pivot model using normal dot notation, for example with('roles.pivot.permissions') instead of only with('roles'). Without it, accessing nested pivot data inside a loop triggers a separate query per pivot row. You register the package's trait or builder methods on the affected models, then update your with() calls. The syntax stays idiomatic Eloquent, so no custom query API is required at call sites.
- How do I install ajcastro/eager-load-pivot-relations?
- Install it with Composer using composer require ajcastro/eager-load-pivot-relations. The package follows standard Laravel conventions, so a service provider and a trait or query builder macro are registered automatically or applied per model. Because the current release is 0.3.0 and pre-1.0, pin it exactly rather than with a caret constraint. Confirm the declared Laravel and PHP constraints in the package's composer.json against your runtime before committing.
- Which Laravel and PHP versions does this package support?
- The package's composer.json is the authoritative source, and it should be checked against your pinned framework version rather than assumed. Packages of this type typically track the two most recent Laravel majors, but that is an expectation, not a guarantee here. Because the v0.3.0 release notes are a bare link to a pull request with no explicit support matrix, verify compatibility directly. Test on a staging branch against your exact Laravel and PHP versions before upgrading.
- What problem does eager loading pivot relations actually solve?
- It removes N+1 query patterns that occur when you load a many-to-many relation and then access attributes or relations hanging off the pivot record. Typical cases include role assignments with their own metadata, membership audit fields, or order-line options stored on the pivot. If your pivots are pure join tables with no relations of their own, the package adds dependency surface for no measurable benefit. It pays off only when the domain genuinely models data on the pivot.
- How do I use this with a custom pivot model such as role_user?
- Define your pivot as a real model using using() or the older pivot() approach on the BelongsToMany relation, then add the package's trait to that pivot model. Once the trait is in place, relations declared on the pivot can be eager loaded through the parent query with dot notation. Start with one high-traffic read path to validate behaviour and query counts before converting other call sites. Rollback is cheap if you keep package-specific APIs out of your application code.
- Does it support load() and loadMissing() on already-hydrated models, or only with() at query time?
- The documentation and release notes do not clearly state whether lazy eager loading via load() and loadMissing() works the same as with() at query time. This matters because it determines how much call-site churn you face, especially if models are hydrated elsewhere before relations are requested. Spike both paths in a staging branch and assert query counts for each. If only with() is supported, scope the migration to query-time loading and leave existing lazy loads alone.
- Is v0.3.0 safe to use in production?
- It is usable but must be treated as pre-1.0, since semver allows breaking changes in minor bumps until a 1.0 release. The v0.3.0 release notes are a bare link to a pull request with no changelog, no migration notes, and no backward-compatibility statement, so you cannot tell from the release whether method signatures or supported Laravel versions changed. Pin exactly to 0.3.0 and review the diff before any upgrade. Run it behind a feature branch first rather than as a big-bang refactor.
- How do I test that the package actually removes N+1 queries?
- Write tests that assert query counts on the endpoints you convert, using DB::listen or a query-count assertion helper in your test suite. Run the assertion before and after adding the package so you have a baseline; without it, the performance benefit is unverifiable. Cover the pivot variants you actually use, such as custom pivot models and nested pivot relations. Keep those tests in CI so future upgrades cannot silently reintroduce the N+1.
- Does it handle morph-pivot and nested pivot relations?
- Nested pivot relations are the core use case, so chaining through a pivot to a further relation is the expected pattern. Support for morph-pivot variants is less clearly documented and should be verified in the repository's test suite before you rely on it. Check whether tests cover custom pivot models, morph pivots, and nested pivot loads, and check CI status. If a variant you need is untested, treat it as unsupported until you prove otherwise.
- What are the risks of depending on a single-author pre-1.0 package like this?
- Maintenance is concentrated in one author with no evident corporate backing, so bus-factor risk is material, and eager-loading internals such as Relation and eagerLoadRelations change between Laravel majors. The package is a narrow, low-coupling library-level concern, which keeps exit cost low. A reasonable mitigation is to vendor a small trait of your own if the package is abandoned, since the behaviour is only a few dozen lines. Avoid spreading package-specific APIs across your codebase so a composer remove plus reverting use statements is enough to roll back.