Query Bus Bundle Laravel Package

Getting Started

1. Require the package (composer require gnugat/quer-bus) and let Laravel auto-discover the service provider. If auto-discovery is disabled, register Gnugat\QueryBus\QueryBusServiceProvider manually in config/app.php.
2. Look first at the package's service provider and any published config (php artisan vendor:publish --tag=query_bus_config if available). The two container entries to note are:
   • gnugat_query_bus.query_bus – the query bus service
   • gnugat_query_bus.query_matcher – the service that maps a query to its handler
3. First use case: create a simple query DTO and handler, tag the handler with gnugat_query_bus.query_bus, then inject the query bus into a controller and call $bus->dispatch(new MyQuery(...)). Start with a single query/handler pair to confirm the tag-to-handler wiring works before adding more.

Implementation Patterns

• Query/HQndler pair: Define an immutable query class (public readonly properties) and a handler class with an __invoke method. Tag the handler with gnugat_query_bus.query_bus in a service provider using $this->app->tag([MyHandler::class], 'gnugat_query_bus.query_bus').
• Constructor injection: Inject the query bus by its container ID (gnugat_query_bus.query_bus) or, if the package exposes an interface, type-hint that interface and bind it in a provider.
• Controller usage: Keep controllers thin—build the query, dispatch it, return the result. For example:

  public function show(QueryBus $bus, int $id): JsonResponse
  {
      return response()->json($bus->dispatch(new GetUserQuery($id)));
  }
  

• Matcher customization: The gnugat_query_bus.query_matcher service is the extension point for custom query-to-handler resolution. Replace or decorate it in a service provider if you need conventions (e.g. FooQuery → FooHandler) instead of explicit tagging.
• Commands and jobs: Inject the same query bus into console commands, queued jobs, and listeners. This keeps read operations consistent across entry points.
• Testing: In feature tests, resolve the query bus from the container and assert handler outputs. For unit tests, mock the bus or use an in-memory matcher. Tagged handlers can be verified with app()->tagged('gnugat_query_bus.query_bus').
• Middleware-like concerns: If the bus supports middleware or decorators, wrap the query bus service to add validation, authorization, logging, or caching without touching handlers.

Gotchas and Tips

• Exact tag name: The tag is gnugat_query_bus.query_bus, not query_bus or a class name. A typo silently leaves the handler unregistered, and dispatching will fail at runtime.
• Manual tagging required: Laravel does not auto-tag handlers based on interfaces. Register every handler explicitly in a service provider, or build a convention-based registration loop with $this->app->tag($handlers, 'gnugat_query_bus.query_bus').
• Matcher resolution order: If multiple handlers match a query (or none), the matcher's behavior matters. Inspect gnugat_query_bus.query_matcher and add guard clauses or custom resolution logic early.
• Container caching: After adding tags, run php artisan optimize:clear and re-cache (php artisan optimize) in production. Stale compiled containers are a common cause of "handler not found" errors.
• Debugging: Use php artisan tinker and app()->tagged('gnugat_query_bus.query_bus') to list registered handlers. app()->make('gnugat_query_bus.query_bus') confirms the bus resolves. For deeper inspection, bind a decorator that logs every dispatch.
• Version discipline: This is v1.0.0 of gnugat/quer-bus, so expect semver stability going forward. The container IDs and tag name are now public contracts—avoid relying on internal classes until they are documented.
• Laravel vs. framework-agnostic wiring: The service names use a Symfony-style dot notation. In Laravel this works, but the package may not integrate with Laravel's contextual binding or #[Tag] attributes. Prefer explicit provider registration over guessing.
• Error handling: The bus likely throws a specific exception when no handler is found. Catch or convert it at the boundary (e.g. HTTP 500 → 422) if dispatching user-influenced queries.