Form Handler Bundle Laravel Package

Getting Started

• Install the package with Composer and let Laravel package discovery register its service provider. If discovery is disabled, add the provider to bootstrap/providers.php (Laravel 11+) or config/app.php.
• Publish any package config only if you need to override defaults:

  php artisan vendor:publish --tag=package-config
  

• Look first at the package service provider and its service definitions. v1.0.6 corrected a service-definition argument from event.dispatcher to event_dispatcher, so confirm you are on >=1.0.6 before debugging missing event dispatch or container-resolution errors.
• First use case: resolve the package’s main service from the container and confirm it receives an event dispatcher, then dispatch a package event and assert a listener runs:

  use Illuminate\Support\Facades\Event;
  
  Event::listen(PackageEvent::class, fn ($event) => /* handle */);
  
  event(new PackageEvent(...));
  

• If the package documents a facade or helper, use that first; fall back to container resolution only when the package does not expose a public API.

Implementation Patterns

• Prefer constructor injection over resolving services manually. The package’s internal service definition now points at event_dispatcher; your application code should depend on Laravel’s event dispatcher contract (Illuminate\Contracts\Events\Dispatcher) or the events binding, not on the package’s internal argument key.
• Register listeners in a dedicated EventServiceProvider or via Event::listen() in a service provider’s boot() method. Keep package-event listeners separate from domain listeners so they are easy to find with php artisan event:list.
• In tests, use Event::fake([PackageEvent::class]) and Event::assertDispatched(...). If you need to isolate the package service, bind a mock to Illuminate\Contracts\Events\Dispatcher; do not bind a fake to event.dispatcher, which was the typo corrected in v1.0.6.
• When customizing the package service, use container extend() or a decorator rather than editing vendor service definitions. If you must override the definition, keep argument names aligned with the installed package version.
• Typical workflow:
  1. Install and publish config if needed.
  2. Configure the package.
  3. Register listeners for package events.
  4. Dispatch an event in a feature test and assert the listener ran.
  5. Clear caches and restart queue workers after deployment.
• For queued listeners, ensure the queue worker is restarted after upgrading so it picks up the corrected service definition. Use afterCommit() on listeners that must not run before a transaction commits.

Gotchas and Tips

• Upgrading from <=1.0.5: earlier versions used the incorrect event.dispatcher argument. If you added a workaround container alias or binding for event.dispatcher, remove it after upgrading. Keeping both can mask configuration mistakes.
• event_dispatcher is an internal service-definition key, not a stable public container binding. Application code should resolve events or the dispatcher contract instead. This reduces the chance of breaking when the package changes its internal wiring again.
• Clear compiled and cached state after upgrading:

  php artisan optimize:clear
  

  If you use config caching or Octane, restart workers as well. Cached service definitions can make a fixed package still behave like the old version.
• Debugging container-resolution failures: inspect the exception message for the missing binding, then check whether the package service provider was registered and whether your own provider overrides the same service. In Tinker:

  app()->bound('events'); // expected true
  app()->bound('event_dispatcher'); // may be false; do not rely on it
  

• If events are dispatched but listeners never fire, check listener registration, queue configuration, and whether Event::fake() is still active in the current test case.
• Extension points to prefer: published config, container extend(), service decoration, and custom listeners. Avoid subclassing internal package services unless the package documents them as extension points.
• When overriding the package’s service definition in your own provider, use the corrected event_dispatcher argument name and add an integration test that dispatches a package event. This catches typo-level regressions before deployment.