Laravel Merged Relations Laravel Package

Product Decisions This Supports

• Saying yes to "one unified list" surfaces without a schema migration. The recurring product ask — activity timeline, account-wide audit view, cross-type moderation queue, unified inbox — implies a single chronologically ordered, paginated feed drawn from several tables. Merged relations reframe that from a data-model project (polymorphic activities table, dual-writes, backfill, reconciliation jobs) into a contained feature build. That is the core decision this package unlocks: ship the user-facing surface now, defer the denormalization question on your terms.
• Build vs. buy on the read layer. The alternative is hand-rolled UNION query-builder code that must independently re-implement eager loading, withCount, whereHas, and pagination semantics — a reliable source of subtly wrong results and quiet performance regressions. This is a narrow, single-purpose dependency (one trait, standard Eloquent relations) that typically displaces hundreds of lines of fragile custom query code. Default position: adopt, wrapped behind an internal interface. The 185 stars reflect a specialist tool rather than a weak one — the maintainer is a recognized name in the Laravel ecosystem, and this sits in a family of well-regarded Eloquent extensions.
• A deliberate, time-boxed deferral of premature denormalization. Adopting this package is an option-value decision worth recording in architecture review: it buys roadmap time while keeping domain tables clean. Pair it with an explicit written trigger — a row-count threshold, a latency SLO breach, or a second consumer needing the same merged feed — that would reopen the migration question.
• Roadmap signal from v1.11. Laravel 13 support shipped as a compatibility-only release: no API changes, no deprecations, no new behavior. Read that as maintenance-mode maturity — low churn, responsive maintainer, one fewer blocker on the framework-upgrade critical path. Useful counter-evidence when the dependency is characterized as a liability rather than a lever.
• Use cases that map cleanly: unified activity/timeline feeds, moderation and review queues spanning multiple content types, search results with cross-type chronological sorting, admin "all records for this account" screens, notification and mention aggregation, and any reporting list where sort and pagination must be correct across sources.
• What it does not decide for you. This is a read/query-layer tool with no write path. It does not replace a search index for cross-store merging, and it is not an analytics or aggregation engine. Frame it as buying time on the read side, not as the permanent answer to the data model.

When to Consider This Package

Adopt when:

• The entities to combine live in separate tables/models behind separate relations, and users expect them in one ordered, paginated list.
• Sorting, filtering, or pagination must happen in SQL — the result set is too large or too dynamic to hydrate and merge in PHP without breaking pagination correctness.
• The merged result must behave like a normal Eloquent relation (eager loading, withCount, existence checks, nested merging) so existing policies, scopes, and query patterns keep working unchanged.
• A polymorphic or denormalized table is off the table for legacy-schema, data-integrity, or migration-cost reasons.
• You can absorb a small, single-maintainer dependency on the read path, isolated behind a named query object or repository so it stays swappable.
• There is a named, funded requirement behind it — not a speculative "this might be useful."

Look elsewhere when:

• You need writes through the merged relation — this is query-layer only.
• The per-request dataset is small and bounded; merging collections in PHP is simpler and cheaper.
• Sources span multiple database connections or non-relational stores — merge upstream in a search index or warehouse.
• The requirement is heavy aggregation or cross-source reporting; database views, materialized tables, or an analytics store are the better answer.
• You require formal vendor support or have low tolerance for single-maintainer dependencies. If you proceed anyway: internal interface, pinned minor version, one integration test per merged relation.
• You are already committed to a unified activity table — the package then becomes redundant complexity.

Upgrade note for v1.11: constraint-widening patch only. Confirm composer.json allows v1.11, verify the PHP floor implied by Laravel 13 against your runtime images, and run merged-relation integration tests on the upgrade branch. The package sits close to Eloquent internals, so it is in the blast radius of every Laravel major — put it on the framework-upgrade checklist so the next bump is anticipated rather than discovered. (Also confirm the rest of the dependency tree is Laravel 13-ready; the package being ready does not make the stack ready.)

How to Pitch It (Stakeholders)

For executives: This is a small, focused library that lets us ship "see everything in one place" experiences — unified feeds, cross-type moderation queues, account-wide activity views — without a risky data migration or a new denormalized table. It converts what looks like a multi-week schema-and-backfill project into a contained feature build, and it protects the roadmap from an expensive bet on denormalization we may not need yet. The v1.11 release is a pure Laravel 13 compatibility update, signaling active maintenance and removing a potential blocker from our framework upgrade. The residual risk is dependency concentration on a single maintainer, which we contain by isolating the package behind an internal interface so it can be replaced without touching product code. Cost of adoption is roughly a one-day spike plus tests — not a program of work.

For engineering: One trait, standard Eloquent relations. Merged relations support where, orderBy, paginate, eager loading, and withCount, so existing query patterns and authorization policies keep working unchanged. No migrations, no published config, no service bindings — opt-in per model. v1.11 adds Laravel 13 support with no API changes and no deprecations, making it a low-risk bump; the only action is validating the Composer constraint and running per-relation integration tests against Laravel 13. Recommended guardrails: wrap each merged relation in a named query object or repository so the package stays an implementation detail of the read layer rather than a public API of the domain; keep constituent relations clean and independently usable, with all filtering in one place; add tests asserting row-level correctness, ordering, and pagination boundaries — silently plausible-but-wrong SQL is the failure mode to guard against; capture EXPLAIN plans on production-sized data and watch for N+1s and query-plan regressions on high-traffic paths; pin the minor version; and document why each merged relation exists and what it replaced, or a future maintainer won't know whether it's safe to delete.