P Service Bus Symfony Bundle Laravel Package

Getting Started

Before anything else: this is a Symfony bundle, not a Laravel package. There is no composer require + auto-discovery path that binds buses and handlers into Laravel's container. Treat the bundle as reference material, and treat gdx/p-service-bus (the underlying core library) as the only thing you might pull into a Laravel app — and only if you're prepared to write the wiring yourself.

If you're evaluating it in a Symfony context (to learn the vocabulary):

1. composer require gdx/p-service-bus-symfony-bundle in a Symfony skeleton.
2. Register the bundle in config/bundles.php.
3. Publish the config: php bin/console config:dump-reference p_service_bus.
4. Define a message class (a plain PHP object) and a handler class with a __invoke() method.
5. Register the handler via attribute or services.yaml tag, then inject the bus into a controller and dispatch($message).
6. Confirm registration with the bundle's debug/console command (debug:* for handlers) — this is the fastest way to see what the compiler pass actually wired.

If you're a Laravel developer (the realistic case):

1. Do the composer spike first: composer require gdx/p-service-bus --dry-run against your actual skeleton. Watch for symfony/* pin conflicts — Laravel transitively pins symfony/console, symfony/process, symfony/http-foundation, and a bundle requiring a different Symfony major will deadlock composer.
2. Read vendor/gdx/p-service-bus/src and answer: does the core depend on symfony/framework-bundle / ContainerBuilder, or only on PSR-11/PSR-14? If it's ContainerBuilder, stop — the cost of adapting handlers to Laravel's container is not worth it.
3. If the core is PSR-clean, first use case is a single non-critical consumer: one command class, one handler, in-memory or database transport, dispatched from a job that you already run. Prove the round-trip before touching anything on a critical path.

First thing to look at: the DependencyInjection/ folder — the extension and any compiler passes. That tells you exactly what the bundle does to the container and, therefore, what you'd have to reimplement in a Laravel ServiceProvider.

Implementation Patterns

The bundle's native patterns (Symfony):

• Attribute-based handlers. A #[AsCommandHandler]-style attribute on __invoke() is the idiomatic registration path. Keeps handler classes free of services.yaml edits and lets Symfony autowiring resolve constructor dependencies (repositories, loggers, clocks).
• Tag-based registration. For handlers you can't attribute (third-party, or conditional), tag services in services.yaml and let the compiler pass collect them into the bus's handler map.
• Per-bus middleware. The config tree lets you attach middleware to the command bus vs. the query bus vs. the event bus separately. Typical pipeline: logging → validation → transaction → retry → dead-letter. Put cross-cutting concerns here rather than in handlers — the whole point is that handlers stay single-purpose.
• Command/event/query separation. Model them as distinct buses. Commands return nothing (or a void handler); queries return a result; events fan out to zero-or-more subscribers. Enforce this in your own domain code, because the bundle won't.
• Router/middleware composition. Dispatching to a specific transport is decided in a router layer. Keep routing rules in config, not in the message class — that's how you move a message from sync to async without touching the producer.

Laravel-side patterns (if you commit to the core library):

• Wrap, don't leak. Define App\Bus\CommandBus and App\Bus\EventBus interfaces in your app. Bind the PServiceBus adapter behind them in a ServiceProvider. This lets you swap to Laravel's native queue dispatch (or Symfony Messenger in a Symfony sibling service) without rewriting call sites.
• Explicit handler map over auto-discovery. Symfony's compiler pass discovers handlers at compile time; Laravel has no equivalent for arbitrary attributes today. Use an explicit config/pservicebus.php map of message => handler and resolve handlers through Laravel's container — this is the single most important adaptation. Add a boot assertion that every mapped handler resolves, because failures otherwise surface at consume time in production.
• Worker as an Artisan command. Long-running consumer under Supervisor, alongside (not replacing) Horizon initially. DB::reconnect() per iteration, explicit memory ceiling, graceful shutdown on SIGTERM.
• Correlation IDs in message headers. Publish with a correlation_id, log it on publish/consume/ack/nack. This is cheap and invaluable the first time a message goes missing.
• Outbox pattern on the producer side if any message is published inside a DB transaction. Without it you have the classic dual-write loss window, and this library does not solve that for you.

Gotchas and Tips

• Framework mismatch is the headline gotcha. For a Laravel codebase this is a hard stop, not a porting exercise. Bundle registration, compiler passes, and ContainerBuilder semantics have no analogue in Laravel's ServiceProvider model. The bundle's artifacts are inert. Only the core library is potentially relevant, and it's unverified whether it's PSR-clean.
• Zero adoption means zero bug reports. No Stack Overflow corpus, no issue history to learn from, no community pressure to keep it compatible with current PHP. Assume you will be the maintainer. Budget for periodic fork-and-patch, or vendor the source privately and accept the fork.
• Composer can silently fail you. Check whether the dependency is a tagged Packagist release or a dev-main VCS entry. An untagged dependency is a reproducibility and supply-chain risk — do not accept it for production. Run composer why-not on any conflict before debugging by hand.
• Transport is unspecified in the docs. Before loading anything, find out whether it supports AMQP/Redis/DB/in-memory, and whether there's an outbox or transactional-messaging story. If the only viable transport is DB-backed, expect contention at moderate throughput and plan a broker migration.
• Schema evolution is your problem. Serialization format and backward-compatibility aren't documented. When a handler's message class changes while old messages are in flight, you get deserialization errors. Version your envelopes (a type + version field) or write tolerant readers. This bites in weeks, not months.
• Retries without a DLQ are infinite loops. The middleware pipeline offers retry and dead-letter, but the configuration is on you. A poison message with retry but no cap is an outage. Cap retries, route exhaustion to a DLQ, alert on DLQ depth.
• Bypassing Symfony's compile-time validation. In Symfony, misconfigured handlers fail at cache:warmup. In a Laravel adapter, misconfigured handlers fail at consume time in production. Add a startup self-check that resolves every registered handler — this is the single highest-value five lines of code you'll write.
• Long-running process hygiene. No request-scoped state, explicit DB::reconnect, memory ceiling + restart policy in Supervisor. This isn't specific to the package, but it's where every first Laravel bus adapter dies.
• Debug tooling exists only in the Symfony context. The console/debug commands for inspecting handlers won't work in Laravel. Build the equivalent: a small artisan bus:inspect command that lists message => handler and attempts resolution. You'll use it constantly during onboarding.
• Extension points you can rely on: the middleware pipeline and the handler resolver are the two seams worth targeting for adaptation. If either assumes ContainerBuilder, that's your signal to abandon the integration.
• When to stop and use Symfony Messenger instead. If the target is a Symfony service (not Laravel), Symfony Messenger is first-party, hireable-for, and documented. Adopting this package over Messenger requires an explicit, defensible reason — a specific routing or middleware model you genuinely lack. Absent that reason, walk away.