Custom Relation Laravel Package

Product Decisions This Supports

• Feature scoping for permission/visibility features. Any roadmap item phrased as "show users what they can access" — ACL chains, inherited permissions, org-hierarchy rollups, multi-tier entitlements — usually hides a multi-hop join. This package makes that a one-class decision rather than a bespoke query buried in a controller.
• Build vs. buy on the "custom query" question. The realistic alternative is a hasManyThrough, a manual join in a repository method, or adopting a full permissions package. This package is a fourth, lighter option: keep Eloquent semantics, no new data model, no vendor lock-in — but accept that you own the join logic.
• Adoption decision: additive, not a migration. The right product framing is "use for new relation call sites only." That makes it a low-risk experiment with a clean kill switch: stop writing new CustomRelation classes and the existing code still works.
• Scope discipline for the permissions domain. It clarifies an important product boundary — if the roadmap needs whereHas, withCount, constrained eager loading, or paginated relation results, this tool is off the table and the roadmap must budget for a proper query layer or a vendor permissions package instead.
• Sequencing the licensing gate as a milestone. Because the license reports NOASSERTION, the product plan must place legal clearance before engineering spikes. This is a real calendar dependency, not a formality, and should be tracked as such.
• Defer-or-fork contingency planning. With 18 stars, zero dependents, and single-maintainer risk, a product decision must be made up front: adopt-with-fork-plan, or don't adopt. The small footprint makes an internal fork genuinely viable, which is a legitimate "buy" variant here.

When to Consider This Package

Consider it when:

• The relationship you need is a genuine multi-hop chain that hasManyThrough and pivot belongsToMany cannot express cleanly — the README's User → Role → Permission ACL traversal is the canonical case.
• You need one or two such relations, not fifteen. Cost scales linearly per relation because each is hand-written logic.
• Eager loading is a requirement and you are willing to write a reviewed addEagerConstraints / match implementation rather than cargo-culting the README.
• Your stack is a Laravel 10–13 monolith or modular app with a first-party relational ACL layer.
• The relation is not on a hot request path, or you can cache materialized results.
• Legal has cleared the license in writing.

Look elsewhere when:

• The license cannot be cleared. This is a hard stop with no workaround.
• The relation will be queried with whereHas, has, withCount, constrained with(['x' => fn ($q) => ...]), or pagination. These are unsupported or untested, and this is the most likely path from "nice idea" to "rewrite."
• You are replacing working hasManyThrough/pivot relations rather than covering the residue they cannot express.
• The team already standardizes on a permissions vendor package (e.g. Spatie Laravel-Permission) — adding this creates two ways to ask the same question.
• You need a vendor, an SLA, a security disclosure path, or broad community validation. This is an 18-star, single-maintainer project.
• The app lags on an older Laravel major — the release history shows rolling drops of PHP and Laravel versions, so an older LTS may already be unsupported.
• The relation sits on a hot request path and the reference match() implementation (per-parent filtering over a fully hydrated collection) would be O(parents × results) in PHP.

How to Pitch It (Stakeholders)

To executives: This is a small, cheap, reversible tool that lets us ship "who can see what" features without buying or building a permissions platform. It costs a day to evaluate and can be removed model-by-model if it disappoints. Two caveats need executive awareness: the open-source license is currently ambiguous and must clear legal before we use it, and the project is maintained by effectively one person with no support guarantee — so we should only adopt it with a named owner for a fallback fork. Total exposure is low because the package is a thin convention layer, not infrastructure.

To engineering: It fills a real gap — relationships requiring a multi-hop join with bespoke filtering that Eloquent's native relations cannot express. Integration is a trait on one model plus one class per relation, with full eager-loading support and an Artisan generator. The trade-offs are explicit: no whereHas, withCount, or constrained eager loading; the README's match() example is a performance and correctness hazard if copied verbatim, so we write and review our own reference implementation; and it hooks Laravel's internal relation lifecycle, which is stable but not a public contract. Proposed plan: legal clearance first, then a one-relation spike on a single model, route only new call sites through it, and prove equivalence against the existing query with a fixed fixture set before replacing anything. Pin the version, commit the lockfile, and add it to the framework-upgrade checklist.