Engine Api Handler Laravel Package

Product Decisions This Supports

• Upgrade vs. stay on v4: v5.0.2 is a breaking release (PHP ^8.2, Laravel 10–12, betalabs/laravel-api-handler ^5.0). This directly supports a decision to schedule a migration window for active products versus freezing older apps on v4.x.
• Platform modernization roadmap: PHP 8.5 readiness and Laravel 12 targeting support planning for the next 12–18 months, reducing future forced upgrades.
• Build vs. buy for API list endpoints: The package now includes tested filtering, sorting, joins, polymorphic joins, relation-based filters, and meta counts. This is evidence to avoid building a custom query-parameter layer for admin panels, internal tools, and SaaS list APIs.
• Reliability investment: Fixes for MySQL HY093 bindings, BelongsTo joins, OR filter behavior, and null filters reduce production defects in tenant-aware and multi-filter list views.
• Dependency simplification: Removal of direct nesbot/carbon and symfony/http-foundation dependencies (now inherited from Laravel) supports a cleaner dependency policy and reduces version-conflict risk.
• Behavioral correctness decisions: OR filters with multiple values and campo-not=null now work as intended. Product teams must review any list screens that relied on the old broken behavior, because result sets may shrink.
• Quality gate decision: New test suite (21 tests, 99.2% line coverage, 100% method coverage) and GitHub Actions PR checks support adopting this as a maintained dependency rather than a liability.

When to Consider This Package

Consider adoption when:

• Your application is on Laravel 10, 11, or 12 and PHP 8.2–8.5.
• You need declarative, query-string-driven filtering, sorting, field selection, joins (including polymorphic and BelongsTo), and meta counts for Eloquent list endpoints.
• You are building or maintaining admin panels, internal tools, multi-tenant SaaS APIs, or data-heavy list views where consistent API query semantics matter.
• You want to avoid maintaining a custom filter/sort/join parser and prefer a package with a recent test suite and CI.
• You can absorb the v5 breaking changes, including the required laravel-api-handler ^5.0 upgrade and behavioral changes to OR filters and null filters.

Look elsewhere or delay when:

• You are on PHP below 8.2 or Laravel below 10; stay on v4.x.
• Your list endpoints rely on highly custom query building that would conflict with the package’s abstractions.
• You cannot accept the corrected filter behavior—especially OR filters with multiple values and campo-not=null—because existing screens or exports depend on the previous broken results.
• You need compatibility with older Laravel versions or cannot add the required laravel-api-handler dependency.
• Your team has no capacity to validate list endpoints after upgrading and would prefer to defer until a larger platform upgrade.

How to Pitch It (Stakeholders)

For executives: This release modernizes the package for PHP 8.5 and Laravel 12, fixes several production-impacting bugs in filtering and joins, and adds a real test suite with CI. It reduces long-term maintenance risk and lets teams avoid building custom API query logic. The trade-off is a breaking upgrade that requires a planned migration; older apps can remain on v4.x. Recommend treating v5 as the strategic version for active products and budgeting a short validation pass for list-heavy screens.

For engineering: v5.0.2 is a maintenance and correctness release. It replaces removed Laravel helpers with Arr/Str, removes the deprecated Input facade, fixes nullable parameters, and drops direct Carbon/Symfony HTTP Foundation dependencies. It fixes real bugs: MySQL HY093 from stale JOIN/ORDER BY bindings in ModelCountMetaProvider, a broken BelongsTo join using getOwnerKey() instead of getOwnerKeyName(), inverted campo-not=null behavior, dropped OR-filter values, and missing polymorphic join aliases in Sort. The new test suite covers handlers, parsers, joins, and counters. Migration risk is moderate: require PHP ^8.2, Laravel 10+, and laravel-api-handler ^5.0; audit OR-filter and null-filter list endpoints because corrected behavior may return fewer records.