Architect Laravel Package

Product Decisions This Supports

• API response contract design. The package lets you declare resource structures and their relationships once, then shape responses dynamically (e.g. a client asking for ?include=author,comments). That directly supports the roadmap question: do we expose a flexible include/sparse-field API surface on v1, or keep fixed endpoints? This is a one-way door for public APIs — the package makes the flexible option cheap to prototype before you commit.
• Payload and performance budgets. Dynamic inclusion means mobile clients fetch exactly the graph they need instead of over-fetching nested relations or making three round trips. That is a measurable product decision: bytes per response, request count per screen, and time-to-first-render on low-bandwidth segments.
• Feature vs. platform sequencing. Rather than hand-rolling serializers per endpoint, resource definitions are shared. This affects how you sequence endpoint delivery: adding a new relation becomes a config change rather than a new transformer + controller + test suite, so you can staff fewer engineers per endpoint and shift capacity to product features.
• Build vs. buy for the serialization layer. The realistic comparison set is Laravel's native API Resources (zero dependency, verbose for dynamic includes), spatie/laravel-query-builder (filtering/sorting/includes, far larger adoption), Fractal (mature, more ceremony), and laravel-json-api (full spec compliance). Use this package as a cheap spike to validate the requirement before choosing the durable dependency.
• Internal-tool and BFF use cases. Best fit is a backend-for-frontend or internal API where one team owns both producer and consumer, contracts can change weekly, and no external party depends on schema stability.
• Maintenance-risk budgeting. With 38 stars, 0 dependents, and a low opportunity score, the honest decision this supports is a risk acceptance decision: who owns the fork, and what is the migration cost if the maintainer stops releasing? A recent release (Jan 2025) shows it isn't dead, but one maintainer with no downstream ecosystem is a single point of failure you should name in the ADR.

When to Consider This Package

Adopt (or, more likely, pilot) when:

• You already ship a Laravel API and the pain is specifically related-resource inclusion — not filtering, sorting, pagination, or auth.
• You want JSON:API-style includes without adopting the full JSON:API specification, media types, and error-object rules.
• The consuming clients are first-party (your own web/mobile app, a BFF), so you can evolve response shapes without a deprecation policy.
• Your team is small enough that "one place to define a resource graph" beats per-endpoint transformers in cognitive load, and you can afford to vendor the package into your repo.
• You're running a 1–2 week spike to decide between a dynamic-include contract and fixed endpoints — this package gets you to a testable API faster than writing the serializer yourself.

Look elsewhere when:

• Public or partner-facing API. You need spec compliance, versioning guarantees, and generated docs → laravel-json-api or a hand-rolled, explicitly versioned contract.
• You need query features beyond includes. Filtering, sorting, field selection, pagination conventions → spatie/laravel-query-builder is the safer, more-adopted building block.
• Procurement or long-term support matters. Zero dependents means no ecosystem validation; if your org requires vendor viability, this fails the bar. Plan to fork with an internal owner or don't adopt.
• Large or distributed engineering org. Onboarding cost of a niche abstraction with thin docs exceeds the savings; native API Resources plus a small internal convention will be cheaper to explain.
• The real requirement is performance. If the goal is fewer queries, with()/load() and query profiling solve it; you don't need a serializer abstraction to fix N+1.

How to Pitch It (Stakeholders)

For executives (one paragraph). We have a recurring cost every time we expose a new API endpoint or a new related object: engineers write bespoke response-shaping code and clients over-fetch or make extra calls. This package is a small, MIT-licensed Laravel library that lets us describe resource relationships in one place and let clients request only the relations they need. It's cheap to trial and could let us ship endpoint variations without new backend code, which shows up as reduced payload size and fewer client round trips. The caveat is adoption: it has a small community and a single maintainer, so I'd recommend a two-week spike against our real endpoints, not a commitment — and we should compare it head-to-head with Laravel's built-in resources plus spatie/laravel-query-builder before choosing.

For engineering (the asks). Treat this as a spike, not an adoption. Deliverable: one representative endpoint (nested relation, two client variants) implemented with this package, plus a written comparison against native API Resources and spatie/laravel-query-builder on lines of code, query count, and onboarding time for someone who hasn't seen it. Explicitly answer: does it handle eager loading of requested includes without N+1, and what happens on an unknown include? Then decide: adopt, fork-and-own, or fold the requirement into the package we already have.