Eager Load Pivot Relations Laravel Package

Product Decisions This Supports

• Build vs. buy for N:M domain models. Many products model rich join tables (memberships with roles, order line items with supplier terms, enrollments with grades). Laravel's default many-to-many handling treats the pivot as inert data; custom Pivot models can declare relations but cannot eager load them. This package closes that gap, so a product team can keep a normalized join-table model instead of denormalizing or hand-rolling with() joins.
• Performance/roadmap scoping for N+1 remediation. If the product surfaces list views over pivot-bound data (e.g., a roster showing each membership's plan and each plan's owner), this is a direct lever for cutting query counts without a schema rewrite. It informs whether a "list view performance" epic is a one-sprint package adoption or a multi-sprint data-model change.
• Feature feasibility for admin/reporting surfaces. Eager loading nested pivot relations is the difference between an admin table being shippable and being deferred. This supports go/no-go on internal tooling and export features that traverse join tables.
• Use cases that fit well: SaaS multi-tenancy where membership rows carry their own relations; e-commerce line items referencing catalog objects; LMS enrollment → cohort → instructor chains; any domain where the join table has graduated into a first-class entity.
• Use cases that do not fit: pure lookup/association tables with no behavior, or models where the join table already has an Eloquent model with its own primary key (then model it as a first-class entity and avoid pivot semantics entirely).

When to Consider This Package

• Adopt when: you already use custom Pivot classes that declare belongsTo/hasMany relations, you are hitting N+1 queries on collection endpoints, and you want to avoid restructuring the schema or replacing Eloquent relationships with manual query builders.
• Adopt when: the affected code path is read-heavy and latency-sensitive, and the alternative (hand-written JOINs or post-query hydration) would leak persistence concerns into controllers or resources.
• Treat as a spike, not a commitment: the package is at 0.3.0 — pre-1.0, no stability guarantee, small surface area of maintainership, and the only release artifact available is a pointer to a pull request rather than a changelog with explicit breaking-change notes. Any adoption should be gated behind an internal abstraction (a repository/scope wrapper) so removal is a one-file change.
• Look elsewhere or build in-house when: you need guaranteed long-term support, your organization requires a maintained 1.x+ dependency, or your pivot relations are shallow enough that a single explicit ->with() on the parent query plus a post-hydration pass is sufficient. Also look elsewhere if you need eager loading on polymorphic pivot relations or through-tables beyond what this package documents.
• Diligence items before adoption: confirm PHP/Laravel version support against your runtime, review PR #11 for behavioral or signature changes (0.x minors routinely break), check test coverage, and verify the maintainer's responsiveness/commit cadence.

How to Pitch It (Stakeholders)

Executives — one line: A small, free, open-source Laravel add-on that removes a class of database performance problems in our list and reporting screens, at the cost of one dependency and a modest, reversible integration effort.

Engineering — the substance: Laravel lets a custom pivot model declare relationships but does not eager load them, which forces either N+1 queries or manual join/hydration code on every collection that renders join-table data. This package adds the missing eager-loading behavior so we can keep a normalized schema and idiomatic Eloquent. The trade-off is maturity: it is a 0.x release from a single-maintainer project, and the v0.3.0 notes are a PR link rather than a curated changelog. Recommendation is to adopt behind our own thin wrapper — an interface or scope that owns the with() call sites — so we get the query-count win now and can swap the implementation out without touching domain code. Budget roughly a day for the spike, a day for the wrapper plus tests, and a query-count assertion in CI to prove the gain and catch regressions on future upgrades.