Engine Api Handler Laravel Package

Technical Evaluation

Architecture fit: This package sits in the API presentation layer: it parses query-string conventions (filters, sorts, joins, eager loads, envelopes, count metadata) and maps them onto Eloquent builders. It fits Laravel services that expose index/list endpoints and want a consistent, declarative contract instead of hand-rolled request parsing. The conventions are opinionated (_filter-approach, campo-not=null, Base-Model-Total), so it is a better fit for greenfield or standardized APIs than for endpoints with bespoke query semantics. It is coupled to betalabs/laravel-api-handler ^5.0, so the integration is really a two-package baseline.

Integration feasibility: Feasible for applications on PHP 8.2+ and Laravel 10–12. The main integration work is not wiring the package but validating two things: (1) transitive dependency assumptions, because nesbot/carbon and symfony/http-foundation are no longer declared directly; and (2) behavioral compatibility of filters. The release explicitly changes filter results for OR multi-value filters and campo-not=null, which can silently reduce result sets. That is an integration risk, not an installation risk.

Technical risk: Medium. Installation is straightforward; behavioral change is the risk. The package fixes real correctness bugs — MySQL HY093 on joined/count queries, BelongsTo owner key usage, polymorphic join aliases in sort, null-relation count handling — but consumers may depend on the old broken behavior. The test suite is new and strong on paper (21 tests, 99.2% line coverage, 100% method coverage, GitHub Actions on PR), but 21 tests is still a small suite relative to the filter/join/sort surface area. PHP 8.5 is listed as the test target while many production estates lag; verify your runtime, CI images, and extension compatibility before treating 8.5 as a supported deployment target.

Key questions: Which services and endpoints still use v4.x, and which query patterns do their clients send? Are any clients using OR filters with multiple values or -not=null in ways that will change result counts? Do any applications rely on nesbot/carbon or symfony/http-foundation being pulled in transitively? Is PHP 8.5 actually in production, or only in CI? What is the support window for Laravel 10 and 11 in this package? Who owns the coordinated laravel-api-handler upgrade, and is there an internal compatibility matrix?

Integration Approach

Stack fit: Best fit is a Laravel 10–12 application or service family already using Eloquent and exposing JSON list endpoints. It is a library, not infrastructure — there is no service to operate, but it becomes part of the API contract. Teams standardizing pagination, filtering, sorting, and count headers across multiple endpoints will get more leverage than teams with one-off query logic.

Migration path: Keep legacy applications on 4.x. For forward-compatible applications, bump PHP to ^8.2, Laravel to 10+, and betalabs/laravel-api-handler to ^5.0 alongside this package. Audit composer.json for implicit reliance on nesbot/carbon and symfony/http-foundation and declare them explicitly where needed. Then treat the filter fixes as a behavior migration: write endpoint-level contract tests before upgrading, compare responses against v4.x on representative data, and only then roll forward.

Compatibility: PHP 8.2–8.5, Laravel 10–12, PHPUnit 10.5/11, Orchestra Testbench 8–10. Applications below PHP 8.2 or Laravel 10 cannot use v5 and should stay on v4.x. CI should test the actual production PHP/Laravel pair, not only the 8.5/12 target. The two-package constraint with laravel-api-handler ^5.0 means version alignment must be handled in the same change.

Sequencing: 1) Inventory endpoints and query-string patterns, especially OR filters and -not=null. 2) Add contract tests around filters, sorts, joins, polymorphic joins, count headers, and envelope shape. 3) Upgrade one canary service. 4) Diff responses against v4.x for changed filter semantics. 5) Roll out to remaining services. 6) Update client-facing API documentation to explain corrected filter behavior. 7) Only after that, validate PHP 8.5 in staging before production.

Operational Impact

Maintenance: The package reduces bespoke list-endpoint code, but it adds a dependency with a coordinated major upgrade (laravel-api-handler ^5.0) and a behavioral change surface. Composer constraint hygiene becomes important because direct dependency declarations were removed. The README improvements and new test suite lower ongoing maintenance cost, but the small test count means your own endpoint regression tests still carry weight.

Support: The v5 line requires PHP 8.2+ and Laravel 10+; v4 remains the path for older applications. Publish an internal support note covering which services are on which major, and make the upgrade ownership explicit. The GitHub Actions PR test run is a useful quality signal, but it does not replace monitoring issue response, release cadence, and compatibility with future Laravel releases.

Scaling: This is a query-construction layer, so scaling is dominated by database performance and Eloquent query shape. The HY093 fix removes a real MySQL failure mode on joined listings, which improves reliability. ModelCountMetaProvider count queries can still be expensive on large joined datasets; consider caching, disabling counts on high-traffic endpoints, or limiting count use to admin surfaces. The corrected OR filters may return fewer records, which changes pagination and downstream aggregation behavior.

Failure modes: The highest-risk failure is silent result-set change from corrected filter semantics — clients may see fewer records or different pagination. Second is a missing transitive dependency after the Carbon/Symfony declaration change. Third is count-header drift or failure on complex joins, though null-relation handling is now graceful. Fourth is join alias or owner-key behavior in polymorphic and BelongsTo joins; the fixes are welcome but should be covered by your own tests. Fifth is a runtime mismatch if production PHP lags the 8.5 test target.

Ramp-up: Low for Laravel developers familiar with Eloquent. The main learning curve is the query-parameter conventions, filter approaches, and count-header semantics. Budget roughly half a day for a developer to read the README and test suite, plus endpoint-specific regression time. A short enablement session with before/after examples of the corrected OR and -not=null behavior will prevent client confusion and reduce support load.