Query Bus Bundle Laravel Package

Technical Evaluation

Architecture fit: This package integrates gnugat/quer-bus (a query-bus / CQRS read-side component) into Laravel's service container. The registered tag gnugat_query_bus.query_bus and service gnugat_query_bus.query_matcher indicate a thin Symfony-DI-style bridge: the matcher resolves a query to its handler, and the bus dispatches. This fits applications that already separate reads from writes (CQRS/DDD), but it overlaps with Laravel's native Illuminate\Bus / command bus, so it competes with a built-in rather than filling a gap. Teams not using CQRS get little value; teams using it get a conventional query/handler wiring pattern.

Integration feasibility: Feasible but modestly involved. Adoption requires: (1) pulling gnugat/quer-bus v1.0 as a transitive or explicit dependency, (2) registering the package's service provider (auto-discovery unknown), (3) ensuring the query_bus tag and query_matcher service bind correctly in the container, and (4) defining query classes and handler implementations. There is no evidence of configuration publishing, handler auto-location, or Laravel-version constraints in the release notes—those must be confirmed against the repo before committing.

Technical risk: Elevated for a v1.0.0 release. It is brand new with effectively zero production track record, the package name gnugat/quer-bus appears to be an inconsistent contraction (vs. "query-bus"), and the release notes are terse—no documentation, compatibility matrix, or test-coverage signal. Pinning gnugat/quer-bus v1.0 locks a fresh 1.x API whose surface may still shift. Single-maintainer dependency risk is likely. The Symfony-style tag/service coupling can be brittle if Laravel's container behavior diverges from Symfony's expectations.

Key questions:

• Which PHP and Laravel versions are supported, and is service-provider auto-discovery implemented?
• How are handlers located—manual tagging, auto-scan, or explicit registration? Is there a handler-not-found failure path?
• Does the query bus integrate with Laravel's queue/events, or is it strictly synchronous?
• What is the test coverage, CI status, and maintainer activity for both this package and gnugat/quer-bus?
• Is the quer-bus naming intentional, and does it have a stable release/versioning policy?
• How does this coexist with or replace Illuminate\Bus for the same use cases?

Integration Approach

Stack fit: Sits cleanly inside a Laravel app via the service container. Best fit is a codebase already structured around command/query separation or hexagonal architecture; poor fit for a conventional MVC app that would gain only indirection. It can coexist with Laravel's native bus, but teams should pick one dispatch mechanism per bounded context to avoid two query paths.

Migration path: Greenfield or read-side-only adoption is the low-risk path. For existing apps, introduce it incrementally—start with one or two read queries (e.g., reporting or dashboard lookups), validate the matcher/handler wiring, then expand. Do not attempt a big-bang replacement of existing service/repository calls. If migrating from Illuminate\Bus commands, wrap rather than rewrite to keep rollback cheap.

Compatibility: Verify the pinned gnugat/quer-bus v1.0 against the app's PHP and Laravel versions before adoption. Confirm the tag and service IDs resolve under the app's container configuration (including any deferred providers or cached config). Check for conflicts if the app already registers similarly named tags/services.

Sequencing:

1. Spike in a branch: install, register provider, confirm php artisan about / container resolution of gnugat_query_bus.query_matcher.
2. Implement one query + handler pair with the query_bus tag; assert dispatch and handler resolution in tests.
3. Add failure-path tests (missing handler, misconfigured tag).
4. Establish conventions (naming, namespace, where queries live) and document them.
5. Roll out to a low-traffic read path behind normal CI gates, then broaden.

Operational Impact

Maintenance: Two packages to track (this bridge and gnugat/quer-bus), each with independent releases. Low code surface means low merge burden, but version pinning means every upstream bump needs a compatibility check. Assign an owner; do not let it become an orphan dependency.

Support: Expect thin community support at v1.0—minimal docs and likely a single maintainer. Budget internal ownership of the integration and conventions. Capture decisions (service IDs, tag names, handler layout) in internal docs so the team is not dependent on upstream guidance.

Scaling: The query bus is synchronous by default; throughput is bounded by handler execution, not the bus itself. Read-side scaling therefore depends on handler implementation (indexing, caching), not on this package. If queued/async reads are ever needed, confirm whether the bus supports it or plan a wrapper—do not assume parity with Laravel's queue-backed bus.

Failure modes:

• Handler not found / matcher misconfiguration → runtime exception on dispatch; mitigate with container-resolution tests.
• Tag or service ID mismatch after provider changes or config caching → silent non-resolution; verify under config:cache.
• Version conflict between the bridge and gnugat/quer-bus v1.0 → composer resolution failure or runtime incompatibility.
• Container binding conflicts with existing tags/services of similar names.
• Upstream API drift in a young 1.x line → breakage on minor upgrades; pin and review changelogs.

Ramp-up: Requires team familiarity with CQRS/query-bus concepts and Laravel's container/tagging model—roughly a half-day for an experienced Laravel engineer to be productive, plus time to establish conventions. Engineers without CQRS background will need onboarding or a reference implementation in-repo. Given the v1.0 maturity, plan a short evaluation spike before committing to production use.