Notify Bundle Laravel Package

Getting Started

• Confirm the target framework first. v1.0 is a Symfony bundle, not a Laravel package. It will not be auto-discovered by Laravel's package discovery, will not read config/notify.php, and will not expose Facades. It is usable in Laravel only if you pull in the Symfony components it depends on and wire it manually — realistically this belongs in a Symfony service, a standalone worker, or a shared internal service, not in a Laravel app.
• Install: composer require <vendor>/notify-bundle:^1.0. On Symfony, register the bundle in config/bundles.php (NotifyBundle::class => ['all' => true]).
• Look here first, in order: the README's quickstart, then Resources/config/services.(xml|yaml|php) to see what services are actually public/autowirable, then the bundle's DependencyInjection/Configuration.php — that file is the authoritative list of every config key, its defaults, and whether it's required. Release notes are a single line, so the config tree is your real documentation.
• Publish/inspect config before writing code: php bin/console config:dump-reference notify (adjust the alias to whatever the bundle extension is named). This prints the full tree with defaults and is the fastest way to discover required values like a transport DSN or API key.
• First use case: inject the notifier service into a controller or command, configure one transport (email or a webhook/HTTP transport), and send a single notification end-to-end. Do not wire multiple channels until one path is proven — at v1.0 the multi-transport behaviour is the least-documented surface.

Implementation Patterns

• Constructor injection, not container lookups. Symfony bundles of this shape register their services as private and rely on autowiring by interface. Type-hint the notifier/transport interface in your constructor; if autowiring fails, the interface is the problem, not the bundle.
• Keep notification construction out of controllers. Build a small application-level service (e.g. App\Notification\Notifier) that wraps the bundle's API, so a v1.x API change touches one class instead of every call site. This matters more than usual given the 1.0 version number.
• Transport-per-environment. Define the bundle's transport in config/packages/notify.yaml with an env-driven DSN (%env(NOTIFY_DSN)%), and a null/log transport for test and dev. Never let a test suite hit a live provider.
• Async by default for anything user-facing. If the bundle ships a Symfony Messenger integration (check for a Message class or a bus config key), route sends through Messenger with a dedicated transport and retry policy. If it doesn't, wrap calls in your own DispatchableMessage rather than sending inline in a request.
• Event hooks over subclassing. Prefer subscribing to whatever pre-send/post-send events the bundle dispatches (debug:event-dispatcher to enumerate) for logging, audit trails, and metrics. Subclassing a bundle service is the fastest way to break on a 1.1 upgrade.
• Cross-framework use. If you must consume this from a Laravel app, treat it as a plain library: instantiate the notifier via a small service provider that builds the Symfony service manually or via a compiled container, and keep the adapter in one binding. Expect to own the glue code.
• Integration tests: assert on the transport-level effect (queued message count, fake/recording transport, or a Mailhog/HTTP stub) rather than on the notifier's return value.

Gotchas and Tips

• Version 1.0 with a one-line changelog is a signal, not a guarantee. There is no upgrade history, no deprecation policy, and no migration guide. Pin to ^1.0 and treat the public API as provisional until a 1.1 lands with real notes. Read the released source before depending on any method not shown in the README.
• Laravel developers: you already have this. Laravel's built-in Notification system (mail/database/broadcast/vonage/slack channels, queueing, Notification::fake()) covers the same ground with zero integration cost. Only adopt this bundle in Laravel if a specific provider or Symfony-side feature is unavailable natively — otherwise the maintenance overhead of a hand-wired Symfony bundle in a Laravel app is not justified.
• No package discovery. Forgetting the bundles.php entry produces a confusing "service not found" rather than a clear "bundle not registered" error. If autowiring fails, check registration first, then config/services.yaml exclude rules.
• Config namespace mismatch. Bundle config lives under config/packages/<alias>.yaml; the alias normally comes from the extension class name, not the Composer package name. config:dump-reference with a guessed alias will just error — get the real alias from the Extension class or by running debug:config with no arguments.
• Cache is the usual culprit. After changing bundle config in a Symfony app: cache:clear (and cache:warmup in prod). A stale container is the single most common "the config key has no effect" cause.
• Debugging toolkit: debug:container --show-private <service> to confirm the notifier is registered, debug:event-dispatcher for hooks, and the Symfony profiler's events/services panels in dev. Errors surfacing as ServiceNotFoundException are almost always an unregistered bundle or a missing transport config.
• Extension points to plan for: custom transport/channel registration (a tagged service, typically), a decorator around the notifier service for logging/retry, and event subscribers. Decorating via decorates: is safer than overriding service definitions, which will silently break on a minor release.
• Secrets handling: keep DSNs/API keys in env vars, not config/packages/*.yaml committed to git. If the bundle supports Symfony Secrets, use the vault for prod.