Laravel Api Handler Laravel Package

Product Decisions This Supports

• Build vs. buy (adopt vs. hand-roll). This release materially strengthens the "buy" case: the package now has a real, CI-gated test suite (58 tests, 99.7% line / 100% method coverage) covering filters, sorting, pagination, nested _fields/_with, all relation types, fulltext search, and counters. The "we could write our own query-param parser in a sprint" argument is weaker when a maintained, tested implementation already encodes our conventions.
• Platform upgrade roadmap. v5.0.0 is the dependency ticket that unblocks PHP 8.5 / Laravel 12. Treat it as a paired workstream with the framework bump — not as a standalone feature — and schedule it in the same release train. It also drops the ancient master (2023) line and the Laravel <5.8 compatibility branches, so the maintained line is now unambiguous.
• API contract surface. One breaking change is client-visible: _with on an unsupported relation now returns an ApiHandlerException (400) instead of terminating the request with HTTP 200 and the text "Relation type not supported!". That is a correctness win but a behavior change for integrators — it should drive a decision on API versioning, changelog/notice to API consumers, and an audit of which relations our endpoints expose.
• Supported-capability commitments. Because nested _fields/_with, all relation types (including polymorphic), fulltext search, and counters (including GROUP BY) are now explicitly tested, we can commit to them in public API docs and partner SLAs rather than describing them as "best effort."
• Defect backlog cleanup. Two fixes remove known production-class failures: CountMetaProvider no longer leaks ORDER BY bindings into the count query (previously produced HY093 on MySQL — i.e., wrong/erroring counts on sorted, paginated result sets), and native fulltext search without _fields no longer throws a TypeError (count(null)) on PHP 8. Both are reliability items we can close rather than staff.
• Vendor-risk tracking. CI on every PR lowers the cost of future adoption decisions and shortens security/upgrade review cycles; conversely, apps pinned to v4.x are now on a branch with a stale upstream, which is a risk to record on the roadmap.

When to Consider This Package

Adopt when:

• The app is on PHP 8.2+ and Laravel 10–12 (target Laravel 12) and exposes a REST/JSON API over Eloquent.
• You want declarative query conventions — filtering, sorting, pagination, sparse fieldsets (_fields), relation includes (_with), fulltext search, and count metadata — instead of bespoke request parsing in every controller.
• You are already planning the PHP 8.5 / Laravel 12 upgrade; the migration cost is then largely absorbed.
• You need polymorphic relation includes and want deterministic 4xx errors rather than process-level failures.

Look elsewhere when:

• The app is locked to PHP ≤8.1 or Laravel ≤9. v4.x still exists but is an unmaintained branch — that is a deliberate risk acceptance, not a neutral choice.
• Any client currently depends on the old _with behavior (HTTP 200 with a plain-text body) or on relation types the package rejects; you would need a compatibility shim or a versioned endpoint first.
• You need raw SQL passthrough, GraphQL, or query semantics this package's parameter vocabulary doesn't express.
• The API contract cannot tolerate a single upstream maintainer's release cadence — in that case, fork with a pinned internal owner, or build in-house.
• No prior assessment exists, so treat v5.0.0 as the baseline and set a review trigger on the next major.

How to Pitch It (Stakeholders)

For executives: A maintenance upgrade to a core API dependency that keeps us on the supported PHP/Laravel path and clears two real bugs — incorrect result counts on sorted, paginated data and crashes on fulltext searches. Cost is a bounded migration inside the framework upgrade we already planned, not a feature build. Risk is contained by a new 58-test suite at 99.7% coverage that runs automatically on every pull request.

For engineering: v5.0.0 rebases on v4.0.2 and requires PHP ^8.2 and Laravel 10–12 (illuminate/* ^10 || ^11 || ^12). Three breaking changes: the PHP/Laravel floors; _with on unsupported relations raising ApiHandlerException (400) instead of die(); and removal of the Laravel <5.8 compatibility branches. Also fixed: CountMetaProvider clearing ORDER BY bindings (HY093), and native fulltext search without _fields (TypeError on PHP 8). Dead Travis config and the non-running legacy tests are gone, replaced by PHPUnit 10.5/11 + Orchestra Testbench 8–10; README now documents requirements, manual provider registration, and how to run tests. Action items: audit every endpoint's _with relation types, update the integrator changelog and API docs for the 400 behavior, and land the upgrade in the same window as the framework bump.