Api Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Hypermedia-Driven REST & GraphQL: The package remains a strong fit for API-first Laravel services needing HATEOAS (Hydra/JSON-LD) and GraphQL from a single resource declaration. v5.0.4 strengthens the metadata layer that both surfaces share (operation class names, parameter precedence, GraphQL QueryCollection constructor propagation), which reduces drift between REST and GraphQL contracts.
• Laravel Integration: v5.0.4 adds another Laravel-targeted fix — fix(laravel): accept null on an optional belongsTo (#8666, first-time contributor) — plus Laravel test-suite work (createOne() for the for() relation, #8718). This is now the fourth consecutive patch landing Laravel-specific fixes, which materially supports the "feasible, not first-class" position.
• Open Standards Compliance: v5.0.4 tightens JSON Schema/OpenAPI fidelity across several axes: mixed now emits an empty schema (#8670), intersection types use allOf (#8653), gen_id nesting follows the property (#8644), nested resources respect the output DTO (#8652), and operation groups are retained in context (#8643). For teams generating clients from OpenAPI, contract accuracy improves noticeably.
• Extensibility: The metadata builder is now more predictable — Put::withAllowCreate() and Link::withFromProperty() return new instances (#8685), defaults using can* getters are applied (#8691), queryParameterValidationEnabled is preserved on ApiResource (#8692), the parameter provider is no longer overridden by the filter provider (#8689), and contentNegotiation is copied in withOperation() (#8694). Net effect: custom filters/serializers configured via immutable builders should stop being silently dropped.
• Validation Model: Add support for GroupSequence (#8645) plus 422 responses for backed enum errors (#8656) and empty scalar params (#8675) give a more coherent, standards-aligned error surface — but change what clients receive.

Integration Feasibility

• Laravel Compatibility: Eloquent support continues to improve (optional belongsTo nullability, relation test coverage), but Symfony-specific services (PropertyInfo, EventDispatcher) still require manual overrides. Treat the Laravel provider as supported-but-thin, not parity.
• Security Semantics: The v5.0.2 change authorizing non-paginated collections against the resource class still stands and is not reverted in v5.0.4 — re-audit remains mandatory. No new authorization semantics in this release.
• Metadata Strictness (relaxed): The v5.0.2 hard error for parameter attributes referencing undeclared operations is now narrowed — fix(metadata): allow GraphQL operations in parameter attributes on properties (#8621) means GraphQL operations are permitted, and #8624 additionally accepts operation class names (not just identifiers). Resources that failed the v5.0.2 smoke test may now pass; conversely, class-name references introduce a new typo/refactor surface that static analysis won't catch.
• Parameter Precedence: #8623 establishes that operation parameters take precedence over property parameter attributes. Any resource relying on the previous (implicit) resolution order may change behavior without an error — this is a silent semantic change, unlike the v5.0.2 hard fail.
• ORM Support: Doctrine fixes matter even for Eloquent users because API Platform routes through Doctrine DBAL/ORM metadata: read the column default option with doctrine/orm 3 (#8705), accept SortDirection enum in ordering (#8662), use ON for arbitrary join in links (#8672), left join nested props in OrFilter (#8674), accept resolved resources in links (#8687), put-create under a slug parent link (#8688), and portable LIKE escape chars (#8671). Nested-property filtering and slug-parent writes were previously unreliable.
• Long-Running Workers: reset the skolem IRI converter between requests (#8681) and reset the Mercure publisher between requests (#8684) confirm per-request state bleed was real in the Symfony bridge. If we run Laravel Octane/RoadRunner/Swoole, we must verify equivalent reset behavior in the Laravel provider — this is now a first-order integration question, not an optimization.
• Performance Overhead: Unchanged — JSON-LD/Hydra metadata cost and IriConverter/metadata caching still require tuning; the v5.0.2 HTTP-cache tag wiring remains the de-risking factor.

Technical Risk

Key Questions

1. ORM Strategy: How will we handle Eloquent-specific features (accessors, mutators, query scopes) under API Platform's Doctrine-centric metadata layer, now that ORM 3 column defaults and SortDirection ordering are supported?
2. GraphQL vs. REST: Will we merge or separate routes, and do any resources now declare GraphQL operations in property parameter attributes (legal as of #8621)? Do we standardize on operation class names (#8624) over string identifiers?
3. Configuration Precedence: Which resources define parameters at both operation and property level, and are we comfortable with operation-level winning (#8623)? Where do immutable builders (withAllowCreate, withFromProperty) get chained?
4. Caching: Which backend (Redis, file) serves IriConverter, metadata, and HTTP cache tags, and does the collection purge cover every collection operation?
5. Authorization: Are all non-paginated collection operations covered by voters/policies (v5.0.2 semantics, unchanged in v5.0.4)?
6. Error Contract: Do our clients and SDKs handle 422 for empty scalar params and enum validation failures, and have we removed reliance on PartialDenormalizationException::getErrors()?
7. Runtime Model: Are we deploying under Octane/RoadRunner? If so, has per-request reset of skolem IRI converter and Mercure publisher equivalents been verified in the Laravel provider?
8. Upgrade Gate: Re-run the v5.0.2 hard-error sweep — some resources may now be valid — and add a precedence + 422 contract test to the CI gate.

Integration Approach

Stack Fit

• Laravel + API Platform Core:
  • REST: Hydra/JSON-LD for self-descriptive APIs; JSON Schema output is now materially more accurate for unions/intersections/nested DTOs.
  • GraphQL: API Platform's GraphQL layer with custom query args; #8693 fixes stateOptions/map propagation into the QueryCollection parent constructor, so state-provider-backed collections should behave consistently across REST and GraphQL.
  • Authentication: Laravel Sanctum/Passport via API Platform security extensions — unchanged.
  • Validation: Prefer state providers/DTOs; GroupSequence is now available for ordered constraint evaluation (e.g., validate identity before business rules).
• Avoid Conflicts:
  • Routing: Keep API Platform's route loader isolated from Laravel's default routes; prefix GraphQL (e.g., /api/graphql).
  • Middleware: Verify CORS, auth, rate-limiting, and HTTP cache tag middleware ordering; confirm per-request state reset if running under Octane.
  • Error Handling: Align the exception handler so Problem Details responses carry the new 422 semantics consistently.

Migration Path

1. Phase 0: Pin & Baseline
   • Pin v5.0.4 (supersedes the previously assessed v5.0.2). Re-run the resource/route smoke test: the v5.0.2 hard-fail gate is now relaxed, so previously failing resources should be re-validated rather than assumed fixed.
   • Capture a baseline of effective operation parameters per resource to diff against post-upgrade precedence (#8623).
2. Phase 1: REST API (Hydra/JSON-LD)
   • Configure Eloquent entities as @ApiResource; test CRUD, pagination, filtering — including nested-property OrFilter and slug-parent put-create (#8688), both fixed in this release.
   • Regenerate OpenAPI and diff: expect changes for mixed, intersection types, nested gen_id, nested output DTOs, and array query params.
   • Add explicit 422 assertions for empty scalar params and backed enums.
3. Phase 2: GraphQL Integration
   • Enable GraphQL; test queries/mutations, custom query args, and any resources using GraphQL operations in property parameter attributes.
   • Validate QueryCollection state options/mapping (#8693) and collection-level readableLink/writableLink on non-resource classes (#8706).
4. Phase 3: Advanced Features
   • Implement custom filters (UuidFilter, ComparisonFilter); confirm the filter provider no longer overrides the parameter provider (#8689) and that generated filter classes are clean.
   • Adopt GroupSequence where multi-stage validation applies.
   • Optimize caching: Redis for IriConverter, metadata, and HTTP cache tags; confirm collection purges fan out to every collection operation.
5. Phase 4: Runtime Hardening
   • Decide on Octane vs. FPM. If Octane, add a soak test that exercises two sequential requests with different resources to catch IRI-converter / publisher state bleed.

Compatibility

Sequencing

1. Core Setup: Install the 5.0.4 patch line; configure Eloquent @ApiResource classes.
2. Contract & Precedence Check: Snapshot effective parameters per resource; diff after upgrade to catch operation-over-property precedence (#8623) and any newly legal GraphQL parameter attributes (#8621).
3. REST Validation: CRUD, filtering (nested OrFilter, portable LIKE escaping), pagination, non-paginated collection authz, and the new 422 paths.
4. GraphQL Onboarding: Schema generation, custom query args, QueryCollection state mapping, link readability/writability on collection members.
5. Performance & Caching: Benchmark serialization; Redis for IRI/metadata; verify HTTP cache tags and collection purge semantics; re-baseline OpenAPI-driven client generation.
6. Security & Runtime Hardening: Re-audit collection policies; test rate limiting; run the Octane soak test if applicable.

Operational Impact

Maintenance

• Version Line: Target v5.0.4 (previous assessment: v5.0.2). The branch shipped v5.0.3 → v5.0.4 with ~35 PRs in one cycle — a fast-moving but actively maintained line. Plan a monthly patch cadence with a dedicated upgrade ticket per bump.
• Dependency Updates: Laravel and Doctrine ORM 3 compatibility continues to be patched upstream (column default option, SortDirection enum), reducing local overlays. Symfony-only fixes remain the majority by volume.
• Bug Fixes: A large share of this release is metadata correctness (immutability, precedence, defaults, provider precedence) — these were silent misconfigurations, so previous behavior may not have been what our annotations declared. Treat the upgrade as a behavioral audit, not just a version bump.
• Documentation: Still Symfony-first; Laravel guidance remains thin. Contribute back the belongsTo nullability pattern and Octane findings if we validate them.
• Test Suite: PHPUnit 13 alignment (ApiTestCase import, Hydra resolver stubs) is now handled upstream — remove local shims.

Support

• Community: Active PR flow with repeat Laravel contributors plus a second consecutive release with a first-time contributor (#8666). Laravel-adjacent fixes are being reviewed and merged, not parked.
• Vendor Lock-in: Low (MIT), but the Symfony-shaped metadata/config model means deep customization stays portable-but-not-free.
• Debugging: debug:api for metadata inspection; Laravel tinker for Eloquent/API Platform interaction. New wrinkle: when a parameter value looks wrong, check provider precedence (filter vs. parameter, #8689) and operation vs. property precedence (#8623) before assuming a bug.
• Cache Warmup: Symfony-corrected cache warmup still has no direct Laravel equivalent — clear Laravel caches explicitly after every deploy.

Scaling

• Performance Bottlenecks: JSON-LD/Hydra metadata overhead unchanged; consider disabling for high-throughput endpoints. GraphQL depth limiting remains mandatory. Re-benchmark after JSON Schema changes (allOf for intersections, empty schema for mixed) since schema generation cost is startup-time but payload shape affects serialization.
• Horizontal Scaling: Stateless design suits Forge/Vapor; pool database connections. Octane users must confirm per-request reset of IRI converter and any publisher/mercure services, or accept state-bleed risk.
• Caching Strategies: Redis for IriConverter, metadata, and HTTP cache tags; OPcache for serializer. The collection-wide purge fix (v5.0.2) plus resolved-resource link handling (#8687) reduce stale-link risk under load.

Failure Modes