Api Events Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package — there is no service provider, no facade, and no package auto-discovery. Read the release notes with that lens: v1.1.1 is a compatibility release (Symfony 7, PHPUnit 10), so nothing you already have wired up should break, but the floor on your dependency versions moves up.

Minimal steps:

1. composer require timobakx/api-events-bundle — check the resolved symfony/* constraints; v1.1.1 is the first release that will happily resolve against Symfony 7.
2. Register the bundle in config/bundles.php (Symfony) — TimoBakx\ApiEventsBundle\ApiEventsBundle::class => ['all' => true]. If you are pulling this into a Laravel app, you must register it manually in a service provider and boot the container bindings yourself; nothing is auto-wired for you.
3. Look first at vendor/timobakx/api-events-bundle/src/ — specifically the event classes and the subscriber/listener that dispatches them. That pair tells you the entire contract faster than the README.
4. Check for a config file under config/packages/api_events.* in the bundle's DependencyInjection/ folder to see which knobs actually exist before inventing your own.
5. First use case: attach a single listener that logs or decorates every API request/response cycle, confirm it fires, then build from there.

Implementation Patterns

Listener-first integration. The bundle's value is the event objects it dispatches. Write a subscriber that implements EventSubscriberInterface, map the bundle's event constants to methods, and set priorities deliberately — response-mutating listeners should run late, logging/telemetry listeners early.

Version-gated wiring. If you support both Symfony 6.4 LTS and 7.x across environments, pin ^1.1.1 only where PHP 8.2+ is guaranteed; keep ^1.1.0 on older branches. Don't try to make one lockfile serve both.

Adapter pattern for Laravel. Since Laravel already ships Symfony's EventDispatcher under the hood, the cheapest integration is to bind the bundle's event classes into Laravel's dispatcher and listen with standard Event::listen() calls. Treat the bundle as a source of event value objects rather than as a framework integration.

Test with attributes, not annotations. PHPUnit 10 support means the package's own suite moved to attributes. Mirror that in your tests: #[DataProvider('...')] with a public static provider method, #[Test] where relevant. If your app is still on PHPUnit 9, you can consume the bundle fine — the constraint only affects the dev dependencies of the bundle itself.

Config-driven enablement. Wrap listener registration in a config flag so the events can be silenced in local/CLI contexts where the API lifecycle doesn't apply.

Gotchas and Tips

• Don't assume Laravel ergonomics. There is no config/api-events.php to publish, no php artisan vendor:publish, no facade. Anything you want configurable, you wrap yourself.
• Symfony 7 is a hard floor shift. Symfony 7 drops PHP < 8.2 and removes long-deprecated APIs. If your app is on PHP 8.1, composer will silently keep you on v1.1.0 — confirm with composer why-not timobakx/api-events-bundle 1.1.1 rather than guessing.
• PHPUnit 10 is not backwards compatible. Static data providers, no @expectedException, setUp(): void signatures. If you copy test patterns out of the bundle's repo into a PHPUnit 9 project, they will fail.
• Debug the dispatcher, not your code. bin/console debug:event-dispatcher (and debug:event-dispatcher <event.name>) shows whether your listener is actually registered and at what priority. Nine times out of ten a "listener never fires" bug is a missing bundle registration or a listener registered on the wrong event constant.
• Priorities bite. Two listeners both mutating the response will produce order-dependent bugs. Set explicit priorities instead of relying on registration order.
• Extension points are the event classes themselves: subclass or decorate them if you need extra payload, and prefer a decorator over editing vendor code. Custom subscribers tagged via kernel.event_subscriber remain the sanctioned extension mechanism.
• Check the changelog diff, not just the headline. compare/v1.1.0...v1.1.1 is a single PR — low risk, no deprecations introduced, but it also means no new features. Don't plan work around capabilities you assumed were added.