Graphql Bundle Laravel Package

Technical Evaluation

Architecture fit. The release notes describe a package that is Symfony-first, not Laravel-first: it references mercure-bundle ^0.2, a custom App namespace for Symfony ^4 applications, and resolves filters "from services using class name as service ID." In a Laravel codebase this is a foreign DI model — Laravel's container auto-resolves by type-hint, not by class-name-as-service-ID. The filtering/ordering capabilities (custom filters, orderBy resolvers) map conceptually onto Eloquent query scopes, but the integration is an adapter, not a drop-in. Treat this as "a PHP library with Symfony coupling," not "a Laravel package."

Integration feasibility. The v1.5.0 feature set splits cleanly into three workstreams of differing cost:

• Low cost / high value: enum comparison in custom filters, multi-value string filtering via values in StringComparisonExpression, custom orderBy resolvers. These are query-layer concerns that sit naturally behind Laravel API resources and can be wrapped.
• Configuration-only: disabling subscriptions via configuration — an immediate risk-reduction win.
• High cost / uncertain value: Mercure subscriptions. This is a push transport (SSE/hub) with no Laravel-native equivalent; it introduces a new runtime service, not just a dependency.

Technical risk.

• mercure-bundle ^0.2 is a pre-1.0 dependency. Its public API is explicitly unstable; a patch bump upstream can break us.
• Symfony ^4 is end-of-life. The "custom App namespace" support is backward-compatibility work for a dead platform, and tells us where the maintainers' install base sits — not where ours does.
• Enum comparison implies a PHP 8.1+ floor. Not confirmed in the notes, and not confirmed against our runtime.
• Multi-value string filtering changes query-string semantics; unclear whether single-value clients remain valid.

Key questions.

1. What is the minimum PHP version for v1.5.0, and do we meet it?
2. Is Mercure required or optional? If subscriptions default to enabled, what happens on a Laravel app with no hub configured?
3. Does the "custom resolver" for orderBy accept an arbitrary callable/class, or is it bound to Symfony service lookup? This determines whether we can back it with Eloquent.
4. Is StringComparisonExpression.values additive (single-value still accepted) or a replacement?
5. Is there a supported path for non-Symfony containers, or is that entirely on us?
6. Who owns the upstream project's release cadence, and is there a security-response process?

Integration Approach

Stack fit. Do not attempt to adopt this as a framework package inside Laravel. Adopt it behind a seam: a single internal service that owns filter/order/serialization translation, so the Symfony coupling is contained in one directory and can be swapped if upstream stalls.

Migration path. This is a greenfield adoption with no prior assessment, so there is no migration — there is a decision. Recommend an incremental, reversible adoption:

1. Configuration audit and hardening (subscriptions disabled unless a hub exists).
2. Compatibility spike — PHP version, enum availability, dependency graph against our existing composer.lock.
3. Query-layer features only (enum filters, multi-value strings, orderBy resolver) behind feature flags.
4. Mercure subscriptions as a separate, independently justified initiative.

Compatibility. Three constraints to verify before committing: PHP 8.1+ for enums; Symfony ^4 constraints that may conflict with our locked transitive dependencies; mercure-bundle ^0.2 plus a running Mercure hub (JWT signing, CORS, transport config). Run composer why-not against the current lockfile as a gate.

Sequencing. Filters first (contained, testable, revertible). Mercure last, and only with a concrete product requirement for server-push. Doing subscriptions first inverts the risk profile — you take on a pre-1.0 dependency and a new runtime service to get features you may not need.

Operational Impact

Maintenance. The pre-1.0 Mercure dependency is the dominant long-term cost: pin exact versions, avoid ^ on mercure-bundle, and track upstream releases manually. The Symfony ^4 compatibility work suggests the project's maintenance energy is partly spent on a platform we don't run — a soft signal on roadmap alignment.

Support. Our team's expertise is Laravel, not Symfony bundles and service tags. The class-name-as-service-ID and custom-resolver features are exactly the kind of thing that looks trivial and consumes a day of debugging without a Symfony mental model. Budget an owner and a written integration note.

Scaling. Mercure adds a new operational component and a new failure domain: a hub process, connection limits, SSE/WebSocket behavior through load balancers and proxies, idle-connection timeouts, and JWT rotation. That is a real infrastructure line item, not a library import.

Failure modes to watch.

• Enum type mismatch → 500s on filter endpoints, likely only discovered in integration.
• Multi-value parsing → silent behavioral change for existing single-value clients; no error, just different results.
• Misconfigured orderBy resolver → ordering silently ignored, producing plausible-but-wrong list output.
• Subscriptions enabled by default when no hub is configured → failures at connection time rather than boot time.
• Feature-flag drift → some environments with the new filter semantics, others without.

Ramp-up. Roughly one sprint for the query-layer features including the compatibility spike; a separate, larger effort for Mercure with infra, security, and client workstreams. Recommend the config flag to disable subscriptions be set on day one, so the optional surface cannot be reached accidentally while the team is still ramping.