Service Bus Lite Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package — there is no service provider, facade, or config/service_bus_lite.php. If you're coming from Laravel, mentally map it to "a package that registers a few singletons in the container and lets you tag handler classes." That's essentially all it does.

Minimal steps, assuming a Symfony 2/3-era app (see Gotchas — that assumption matters):

1. composer require psamatt/service-bus-lite-bundle and let Composer resolve psamatt/service-bus-lite alongside it. Verify the Symfony constraint in composer.json before you commit to this; the bundle predates Symfony Flex.
2. Register the bundle: new Psamatt\ServiceBusLiteBundle\ServiceBusLiteBundle() in app/AppKernel.php (or the equivalent in config/bundles.php if it happens to autoload cleanly).
3. Look first at DependencyInjection/ and Resources/config/services.xml inside the bundle before reading any README. The docs are thin-to-nonexistent, and the container definitions are the real documentation: they tell you the service IDs for the command bus, the handler locator, and whatever tag name the compiler pass collects.
4. First use case: define a command object, write a handler class, register the handler as a service with the bundle's handler tag, inject the command bus into a controller, and call $bus->handle(new SomeCommand(...)). Confirm it dispatches before building anything else.

Implementation Patterns

The day-to-day value of a package like this is the wiring convention, so lean on it rather than fighting it.

Tag-and-dispatch. The core pattern is: controller/service depends on the command bus, builds a command DTO, and hands it off. Handlers are plain services carrying the bundle's tag (or implementing the library's handler interface, if autoconfiguration is enabled). Keep controllers thin — construct the command, dispatch, return a response. This is the single pattern you'll repeat most.

One bus per bounded context. Rather than one god-bus, define separate bus service aliases for commands that must stay isolated (e.g. billing vs. shipping). With a Lite library this usually means duplicating the service definition with a different handler locator rather than relying on the bundle to give you multi-bus support for free.

Middleware for cross-cutting concerns. Logging, transaction wrapping, and validation belong in middleware around the bus, not inside every handler. Check whether the bundle exposes a middleware tag; if not, decorate the bus service in your app's services.yml and keep the bundle's definition untouched.

Interface-first handlers. Have handlers implement a small application-level HandlerInterface and use Symfony's _instanceof autoconfiguration to apply the tag. This decouples your code from the library's exact tag name and makes swapping the bus later a container change, not a code change.

Integration tip: put the command/handler classes in your domain or application layer (not in a Bundle), and keep the bundle registration confined to app/config. When you eventually outgrow the library, you delete a config block instead of refactoring business logic.

Gotchas and Tips

It is effectively unmaintained. Four stars and zero dependents is the headline. Assume no security patches, no Symfony 4+/5+/6+ support, and no PHP 8 compatibility. Pin your Symfony and PHP versions before adopting, and treat a composer update as a potential breaking event. For any new project, implement the pattern yourself (~100 lines) rather than adding this dependency.

No Laravel path. There is no bridge, adapter, or port. If you're a Laravel developer evaluating this for a Laravel codebase, the answer is "borrow the pattern, not the package" — a Laravel service provider with singleton() bindings and a tag-like handler map gives you the same thing in an afternoon.

Silent compiler-pass failures. The most common debugging trap with handler-collecting bundles: a mistagged or forgotten handler simply never resolves, and you get a "no handler for command" error at runtime rather than at compile time. Use bin/console debug:container --tag=<the-bundle's-tag> to confirm each handler is actually collected, and add an explicit check for duplicate handlers for the same command.

Configuration quirks. The extension alias is likely derived from the bundle name (service_bus_lite), but verify it in the Extension class rather than guessing — a wrong alias silently ignores your YAML because Symfony skips unclaimed config keys in older versions. Also check whether the bundle expects the bus as a public service; older bundles often declare everything public, and relying on that hides autowiring problems later.

Extension points are container-level, not API-level. The realistic customization surface is: override the bus service definition in your app config, decorate it, or supply your own middleware. Don't expect events, configurable retry policies, or failure transports — this is "Lite" and predates the current Symfony Messenger feature set.

Debugging dispatches. Since the bus is just a container service, debug:container and a dump() inside your middleware give you more than any logging the bundle offers. If a command appears to hang, check for circular handler dependencies first — those surface as container exceptions at request time, not at boot.