Architect Laravel Package

Technical Evaluation

Architecture fit. Architect targets the layer between Eloquent models and JSON responses—the same stratum Laravel's native JsonResource/ResourceCollection occupy, and where Spatie's laravel-query-builder and JSON:API packages compete. Its premise—declare relationships on a resource schema and resolve them dynamically from request parameters (e.g. ?include=posts.comments)—is a legitimate pattern for read-heavy REST APIs where clients need variable graph depth. Fit is good only if the product genuinely needs client-driven compound documents; if relationships are fixed per endpoint, native resources are simpler and dependency-free. The package presumes an Eloquent-centric domain model and conventional relationship definitions; anything using raw query builders, non-Eloquent repositories, or DTOs will fight it.

Integration feasibility. Integration is technically low-effort in a Laravel app—composer install, define schema classes, wire controllers—but the real work is governance, not code: establishing an allowlist of includable relationships, enforcing per-relationship authorization, and constraining nesting depth. The package defines the mechanism, not the policy. Expect to write thin adapter code and custom gates regardless.

Technical risk. This is the dominant concern. 38 stars and zero dependents means effectively no production validation signal in the ecosystem. Single-maintainer (esbenp) provenance is a bus-factor-1 risk, though the January 2025 release suggests the maintainer is still active. The codebase is small enough to audit and fork—mitigating but not eliminating abandonment risk. Secondary risks: unknown Laravel/PHP version ceilings in composer.json, silent behavioral changes across majors, and conceptual overlap with native API Resources that can produce double transformation or confusing output if both are used on the same endpoint.

Key questions to resolve before adoption.

• What Laravel and PHP versions are supported, and what is the maintainer's stated support policy?
• Does include resolution eager-load relationships, or does it lazy-load per item (N+1)?
• How are unknown/disallowed include parameters handled—exception, silent drop, or 400?
• Is there protection against circular or arbitrarily deep include chains?
• Does it compose with native JsonResource or replace it entirely?
• Is relationship-level authorization hookable, or must we pre-filter the schema?

Integration Approach

Stack fit. Best suited to Laravel 10/11 services with Eloquent models, a conventional app/Http/Resources layer, and REST clients that benefit from sparse, client-selected relationship graphs (mobile apps, aggregator front-ends, partner APIs). Poor fit for GraphQL backends (overlapping capability), JSON:API-strict contracts (use a JSON:API package instead), or services where response shape is fixed and cacheable per route.

Migration path. Adopt per-endpoint, not package-wide. Introduce Architect behind a thin internal abstraction (e.g. an ApiPresenter interface) so the underlying mechanism can be swapped for Spatie QueryBuilder or native resources later without touching controllers. Run it in parallel with existing resources on one low-risk read endpoint, diff the outputs, and only then expand. Do not mix Architect and native JsonResource on the same response path—pick one per endpoint.

Compatibility. Verify composer.json constraints against your Laravel minor version and PHP runtime before anything else; a package this small is unlikely to have a broad CI matrix. Check for conflicts with any existing query-parameter middleware, pagination wrapper, or response-formatter already in the stack. If you use Laravel's Model::preventLazyLoading(), confirm Architect's include resolution survives it.

Sequencing.

1. Spike: install in a sandbox, reproduce a nested-include endpoint, capture query counts and response payloads.
2. Audit the source (~small) for recursion limits, authorization hooks, and eager-loading behavior.
3. Define the include allowlist and per-relationship policy gates in application code—not in the package.
4. Pilot on one read-only endpoint behind a feature flag with output diffing against the incumbent resource.
5. Instrument query counts and latency; gate rollout on parity.
6. Decide fork-vs-depend based on the audit; if the surface area you use is small, vendoring the relevant logic may cost less than the dependency.

Operational Impact

Maintenance. You are effectively adopting a dependency you may have to maintain. Budget for periodic source review at each Laravel major upgrade and a contingency plan (fork, or replace with Spatie QueryBuilder's allowedIncludes) if the package stalls. On the positive side, the small footprint makes a fork tractable—days, not weeks—which materially lowers the true cost of abandonment.

Support. No commercial support, no meaningful community, no Stack Overflow corpus. Internal documentation and a named owner are mandatory. Knowledge will live with whoever performs the spike; that must be written down, not tribal.

Scaling. Two axes. Request-side: client-selected includes are an amplification vector—?include= chains can inflate payload size and query breadth, so enforce depth limits, include allowlists, and response-size caps at the edge. Data-side: if include resolution is not eager-loaded, expect N+1 queries under real cardinality; measure with a representative dataset, not a seeded 10-row fixture. Cacheability degrades because the same route yields many response shapes—plan cache-key strategy or restrict includes on hot paths.

Failure modes. Anticipated: unknown include → 500 instead of 400 (verify and wrap); circular or deep includes → recursion/timeout; unauthorized relationship exposure → data leak if policy is not enforced outside the package; lazy-loading exceptions if strict mode is enabled; silent output divergence if Architect and native resources coexist. Each needs a guardrail in application code, not reliance on package defaults.

Ramp-up. Low for Laravel developers—the mental model mirrors native resources and the API surface is small; a competent team reaches productivity in under a day. The learning cost sits in the operational semantics (include policy, authorization, performance), not the API. Given zero dependents, expect to be an early production user and to discover undocumented edges yourself; factor that into the estimate rather than treating it as a drop-in.