Enrichments Bundle Laravel Package

Getting Started

1. composer require <vendor>/<package> — Laravel's package auto-discovery registers the service provider, so there is nothing to add to config/app.php on Laravel 5.5+.
2. Publish any config the provider exposes (php artisan vendor:publish --provider="...ServiceProvider") and commit it. The package reads its defaults from config, not from env directly.
3. Look first at the package's ServiceProvider::register(). As of v0.1.2 all internal services are registered as private bindings; the dispatcher is the only public entry point into the package. That single fact determines almost every integration decision below.
4. First use case: resolve the dispatcher and hand it work.

use Vendor\Package\Dispatcher;

public function __construct(private Dispatcher $dispatcher) {}

public function store(StoreRequest $request)
{
    $this->dispatcher->dispatch($request->validated());
}

If the dispatcher is bound as a singleton, constructor injection gets you the same instance everywhere — safe to inject into controllers, jobs, listeners, and console commands alike.

Implementation Patterns

Inject the dispatcher, don't reach past it. The private bindings are implementation detail. Whether you inject via constructor, app(Dispatcher::class), or a facade (if one is shipped), the dispatcher is the contract. Everything the package does — queuing, resolving handlers, resolving the underlying services — happens behind it.

Queue-aware usage. If the dispatcher fans work out to queued jobs, keep dispatch calls inside services/actions rather than controllers so the same call path works from HTTP, console, and queued listeners. Wrap dispatch in a small application-level service if you need consistent logging, tracing IDs, or tenant context.

Configuration-driven behaviour. Set the package's config values (queue connection, retry policy, handler namespace, etc.) in the published config file and override per-environment via .env keys the package documents. Avoid config([...]) calls at runtime — they won't survive config:cache and will be invisible to Octane workers booted before the change.

Testing. Prefer swapping the dispatcher's dependencies rather than mocking the dispatcher itself. Because the internal services are private, bind a fake before the package provider registers its own binding — i.e. in a test service provider or setUp() prior to app resolution — or use the package's own fake/swap mechanism if one exists. Assertions on dispatched payloads are far less brittle than asserting on internal service calls.

Integration surface. Typical day-to-day integrations: calling the dispatcher from a queued job's handle(), from a scheduled command, or from a listener reacting to a domain event. Keep those call sites thin — the dispatcher should be a single line in each, with the real logic in your own classes.

Gotchas and Tips

• v0.1.2 is a visibility change, and it can break you. Services are now registered as private because "they are only needed in the dispatcher." If you were type-hinting one of those internal services in a constructor, calling app(SomeInternalService::class), or resolving them in a test, you will now get a "Target [...] is not instantiable" / binding-not-found error. The fix is to depend on the dispatcher, not its collaborators. Pin ^0.1.2 deliberately and grep your codebase for the package's service class names before upgrading.
• Private means un-extendable from the outside. You can no longer rebind those services in a service provider to substitute your own implementation. If you need customisation there, it has to go through the dispatcher's public API or the package's config. Treat the internal services as frozen private API — the maintainers have signalled they will change them freely.
• Binding order matters. Anything you register to override package behaviour must run after the auto-discovered provider. Use $this->app->register(..., true) or a deferred provider, and verify with php artisan about / php artisan tinker rather than guessing.
• config:cache in production. New config keys added in a release are invisible until you re-run php artisan config:cache. This is the single most common "the upgrade did nothing" report.
• Debugging dispatch failures. Because the interesting work happens inside the dispatcher, exceptions often surface from the container trying to instantiate a private service's dependency rather than from your call site. Read the full stack trace to the ServiceProvider frame before assuming your payload is wrong.
• Version pinning. At 0.x, semver allows breaking changes in patch releases, and this release demonstrates it. Pin an exact version in composer.json and review each bump's diff — the changelog line here is one sentence but affected the container contract.
• Extension points to watch. If the package later ships a contract/interface for the dispatcher, prefer binding against that rather than the concrete class. Until then, keep the dispatcher behind one thin wrapper class of your own so a future rename or signature change is a one-file edit.