Laravel Eloquent Join Relation Laravel Package

Product Decisions This Supports

• Feature work: eliminating N+1 in join-based list endpoints. Dashboards, search results, admin tables, and API index endpoints frequently join related tables to filter or sort (e.g., sort users by teams.name, filter orders by customers.country). Today those endpoints either drop the relation from the payload or pay for a second query. This package lets the same query return hydrated BelongsTo / HasOne models, so the performance win and the response shape aren't in conflict.
• Build vs. buy. The realistic alternatives are (a) hand-rolled hydration logic in each query/controller, (b) constrained eager loading (with(['author' => fn ($q) => ...])) plus a second round trip, or (c) reshaping the query to avoid joins. A small, single-purpose package replaces (a) — which is the option that accretes the most bespoke, untested code — and beats (b) on query count. It does not replace general eager loading; it's a targeted tool.
• Roadmap scoping. v1.0.0 is deliberately narrow: BelongsTo and HasOne only, with collection and polymorphic relations explicitly out of scope. That maps to a clear adoption boundary — use it for the "detail row" half of your API surface now, and treat HasMany/MorphTo hydration as a dependency to track, not something to plan around.
• API contract decisions. Because missing related rows come back as null on left join, the package makes the "related record absent" case expressible in the payload without a follow-up query. That's a direct input to response-schema and nullability decisions for consumer teams.
• Use cases that fit cleanly: paginated lists sorted/filtered on related columns; search results that must include the related entity inline; validation/reporting queries that already join and currently discard the joined columns; nested display paths like author.team.organization resolved in one round trip.
• Use cases that don't fit: anything needing HasMany, ManyToMany, or polymorphic relations loaded from the same join; write paths; queries where the join is incidental and plain with() would do.

When to Consider This Package

Adopt when most of these hold:

• The query already uses join for filtering, sorting, or validation, and the related data is therefore already in the result set — you're paying for the join and currently throwing the columns away.
• The relations you need are BelongsTo or HasOne, including nested paths (author.team.organization).
• You're on PHP 8.2+ and Laravel 11.x/12.x/13.x.
• The endpoint is read-heavy and query count is a measured concern (SLAs, per-request query budgets, N+1 already flagged in profiling).
• You want the result to behave like normal Eloquent — the stated goal of keeping developer experience close to standard, with ordered nested-path enforcement and protection against fallback lazy loading, is what makes this safe to hand to a team rather than a one-off utility.

Look elsewhere, or wait, when:

• You need HasMany, ManyToMany, or polymorphic relation hydration — explicitly out of scope for this release, and the fallback-lazy-load protection means you'll get an explicit failure rather than silent degradation, which is good but still a blocker.
• A constrained with() plus a second query is acceptable — often it is, and it's the lower-risk, zero-dependency choice.
• You're on PHP < 8.2 or Laravel 10 or below — hard version floor, no backport path described.
• You need a mature, widely deployed dependency. This is a v1.0.0 first release with a narrow scope statement; treat it as an evaluation candidate, not an assumed-stable platform dependency, until you've validated it against your own multi-join queries.

Adoption caveats to carry into review: the package's correctness depends on the join shape matching the declared relation path — misdeclared or reordered nested paths are rejected with explicit exceptions rather than guessed at, so expect to spend a little time on query construction. Existing test coverage is described for advanced multi-join scenarios, which is the right place to look; ask for the repo and verify the left join / null path and the lazy-load guard against your own fixtures before committing.

How to Pitch It (Stakeholders)

For executives (one paragraph): We're evaluating a small Laravel package that removes a common source of database overhead — the extra queries we fire to load related records on list and search screens. It works with queries we already write, so it's an efficiency change rather than a re-architecture: fewer round trips per page load, less custom glue code for engineers to maintain, and no change to the API shape our clients see. Scope is intentionally limited to the most common relation types, on our current PHP and Laravel versions. Risk is low and contained — it's additive, it fails loudly rather than silently when a relation isn't supported, and we can pilot it on one or two high-traffic endpoints before deciding.

For engineering leads: This is the "we already joined, so use it" case. It hydrates BelongsTo and HasOne — including nested paths like author.team.organization — directly from the joined row set, with left join producing null for missing records and nested paths required in declared order (enforced by explicit exceptions). Fallback lazy loading is blocked, so unsupported or misshapen usage surfaces immediately instead of quietly costing us queries. Requires PHP 8.2+, Laravel 11–13. Not a fit for HasMany or polymorphic relations in this release. Proposed next step: pilot on one paginated endpoint that sorts on a related column, confirm query-count reduction and payload parity, then decide on broader use.