Message Bus Laravel Package

Getting Started

telephantast/message-bus is a small, low-ceremony message bus abstraction (message → handler dispatch with middleware support). With only 19 stars and an unknown repository link, treat the source as the primary documentation.

Minimal integration:

composer require telephantast/message-bus

1. Read src/ first. The package is small enough that the interfaces (MessageBus, Message, Middleware, likely a MessageHandler contract) are the whole story. Look for a facade/service provider and check whether handlers are resolved through the Laravel container by class-string or by interface binding.
2. Register the provider (usually auto-discovered via extra.laravel.providers). If not auto-discovered, add it to bootstrap/providers.php.
3. First use case — a command bus inside a controller. Create a Message DTO, a handler class with a __invoke (or handle) method, and dispatch through the injected MessageBus. This replaces fat controllers and keeps transactional/queue logic out of HTTP code.

final class RegisterUser implements \Telephantast\MessageBus\Message {
    public function __construct(public readonly string $email) {}
}

final class RegisterUserHandler {
    public function __invoke(RegisterUser $message, UserRepository $users): User {
        return $users->create($message->email);
    }
}

// In a controller / action
public function __invoke(RegisterUserRequest $request, MessageBus $bus): UserResource
{
    return UserResource::make($bus->dispatch(new RegisterUser($request->email)));
}

If the package does not ship a facade, inject the MessageBus interface via the container. Verify the binding name once — it is the single most important detail to confirm before building on top of this package.

Implementation Patterns

• CQRS-lite separation. Use the same bus for commands and queries: commands return void/aggregate, queries return read models. If the package distinguishes them (some message-bus implementations do via separate CommandBus/QueryBus interfaces), lean into that; otherwise split by convention and naming.
• Middleware pipeline. The main reason to choose a message bus over plain method calls is the middleware stack. Typical middleware: DB::transaction(...) wrapping command handlers, validation, logging with correlation IDs, and metrics. Order matters — register transaction middleware innermost (after validation) so retries don't re-open transactions unnecessarily.
• Service container as resolver. Most small message-bus packages use app()->make($handlerClass) to resolve the handler. That means any Laravel injection pattern works inside handlers: repositories, Http client, cache, filesystem — no extra wiring needed.
• Queued commands. If the package includes queue support (check for a ShouldQueue-style interface or a QueueMiddleware), dispatch long-running work through the bus from HTTP code and let the bus handle serialization. If not, wrap the dispatch in a Job and keep the bus synchronous.
• Testing seam. Wrap the bus in an application-level CommandBus service you control, e.g. App\Bus\CommandBus delegating to the package. This lets you swap the underlying implementation later, mock it in tests, and add app-specific middleware without forking. It is the single highest-value integration tip for a 19-star package.
• Domain event fan-out. Use the bus for domain events inside aggregates, dispatching after persistence. Pair with Laravel's own Event system rather than replacing it — the bus handles the handler pipeline, Laravel events handle observers and broadcast notifications.
• Nested dispatch. Be explicit about whether the bus is re-entrant. If handler A dispatches message B, confirm middleware runs for B (usually yes) and that transactions compose correctly (Laravel's nested DB::transaction is a no-op, so this is safe).

Gotchas and Tips

• Undocumented API surface. With 19 stars and no linked repository, expect no docs. Read composer.json, src/, and any tests/ before committing. Lock the version in composer.json to something specific ("^1.0" rather than "*") so a minor release doesn't change middleware contract semantics.
• Handler return types. Message bus packages commonly type dispatch() as mixed. Add your own typed wrappers (CommandBus::dispatch(Message): void, QueryBus::fetch(Query): mixed) so PHPStan/Psalm stay useful. Without this, generic handlers silently widen return types.
• Middleware ordering is load-bearing. Transaction + retry middleware in the wrong order causes duplicate side effects (e.g., HTTP calls executed twice). Convention: [Logging, Metrics, Validation, Transaction, Retry] from outside in, with retry placed to wrap the transactional unit deliberately.
• Container binding failures. If handlers aren't auto-resolved, the package likely requires explicit registration (a config map, attribute, or interface binding). The error surfaces as "Target [X] is not instantiable" or a reflection exception at dispatch time — not at boot. Warm the bus in a test to catch this early.
• Serialization for queued messages. Message DTOs must be plain-data or SerializesModels-compatible. Avoid carrying Eloquent models across async boundaries without SerializesModels; prefer IDs. If the package uses serialize() directly, closures and container-resolved objects will break.
• Debugging. Add a TracingMiddleware that logs message class → handler class → duration. Because the bus hides dispatch behind one call, stack traces are less useful than a trace list of which messages ran and which middleware fired.
• Extension points. The middleware interface is your extension point — do not subclass the bus. If the package lacks a decorator API, compose around it (class TracedBus implements MessageBus) and bind that in a service provider.
• Escape hatch ready. Given the small ecosystem footprint, keep the bus behind your own interface from day one. If the package stalls, swapping in Symfony Messenger, League Tactician, or a Illuminate\Bus wrapper is a one-file change instead of a refactor.
• License note. MIT, so vendoring/forking is viable if a critical bug blocks you. Prefer a fork over an unmaintained dependency in production.