Notification Bundle Laravel Package

Getting Started

Verify framework fit before anything else. This is a Symfony bundle (PerformNotificationBundle, -bundle naming, Symfony DI container, config tree, event dispatcher). In a Laravel codebase it will not auto-register, will not use Illuminate\Notifications, and will not speak Laravel's queue or mailer contracts natively. Confirm that before spending a sprint on it.

Fastest path to a working copy (scratch Symfony app):

1. composer require perform/notification-bundle in a throwaway Symfony 6/7 skeleton — not in your Laravel app yet.
2. Register the bundle in config/bundles.php and inspect the vendor dir for DependencyInjection/Configuration.php and Resources/config/services.* — that is where the real configuration surface lives, not in the README.
3. Grep the source for the notification contract (*Notification.php, *Transport*.php, *Handler*.php) to answer "what does it own?" — transport adapters only, or also templating, routing, and preferences.
4. Dispatch one email notification through a non-production transport. That single flow tells you more than the description does.

Where to look first, in order:

• The bundle class — what it registers, what it assumes.
• The DI extension/configuration — the full set of knobs and defaults.
• The transport interface — the extension point you'd actually implement.
• Any recipient/preference model — this is the part worth stealing regardless of adoption.

First real use case: pull it into a scratch branch and map its channel + preference schema against your three highest-value flows (transactional email, in-app alert, SMS). You are evaluating it as a reference implementation, not a dependency. If you can't answer "which of our flows does this model cleanly?" in ~2 days, stop.

Implementation Patterns

Recommended pattern: adapter behind an internal contract. Do not let callers touch the bundle directly. Define your own contract and implement it over both Laravel native and the bundle:

interface NotificationDispatcher
{
    public function send(Notifiable $recipient, Notification $n): void;
}

• LaravelNotificationDispatcher wraps Illuminate\Notifications\ChannelManager.
• PerformNotificationDispatcher wraps the bundle's dispatch service.
• Bind one in a service provider; cutover and rollback are a one-line binding change.

Concept mapping table — write this down before bridging anything:

Reference-model extraction (the highest-value pattern). Even if you never install it, copy the shape:

• A Notification value object carrying channel list, template key, and payload.
• A Transport interface with one method per transport (send(Recipient, RenderedNotification)).
• A per-user NotificationPreference model with (user_id, channel, type, enabled) — the opt-out schema is the part most teams under-design.
• A RecipientRouter that resolves a notifiable to concrete addresses per channel.

Bridge pattern if you genuinely dual-stack. If you run Symfony services alongside Laravel and want one contract across both, put the bundle behind a queue job you own:

final class DispatchPerformNotification implements ShouldQueue
{
    public function handle(NotificationDispatcher $d): void { /* ... */ }
}

Queue on the Laravel side, never call the bundle synchronously in a request cycle. This keeps retries, failed(), and backoff under Laravel's semantics rather than a Symfony message bus you aren't monitoring.

Transport adapter pattern. Implement the package's transport interface with a thin class that delegates to a Laravel-native transport (MailManager, an SMS SDK wrapper). This keeps the bundle's routing/preference logic while your actual delivery stays on infrastructure you already observe.

Templating. Do not adopt the bundle's templating if it renders Symfony/Twig shapes. Keep rendering in Laravel (Blade/markdown mailables) and pass fully-rendered content into the bundle — or better, skip the bundle and render into your own dispatcher.

Testing. You will not get Notification::fake(). Wrap dispatch behind your internal contract and fake that in tests; otherwise every test touching notifications becomes an integration test against a third-party transport.

Gotchas and Tips

• Read-only subtree split. This repo is a build artifact of an upstream monorepo you cannot patch directly. Any fix means forking and either republishing under your own namespace or using a Composer VCS repository override. Decide on fork-and-vendor before adoption, not after the first bug.
• Symfony bundle registration is a no-op in Laravel. config/bundles.php doesn't exist. You must write a ServiceProvider, publish config, and alias any container IDs by hand. Budget for a permanent bridge shim you own.
• Config tree ≠ config file. The bundle's knobs are defined in DependencyInjection/Configuration.php, not documented. Read that file to know what's actually configurable — the description's "configurable templates and recipient routing" may be thinner than it sounds.
• Check for proprietary transport requirements. Some "Perform" packages ship transports that require a vendor account/API key. If the only working transports need credentials you don't have, the spike ends there.
• Queue semantics mismatch. If it dispatches synchronously or via a Symfony message bus, notification sends will inflate p95 latency and couple user requests to third-party availability. Always queue, and verify retry/backoff behavior yourself — Symfony bus retries do not behave like Laravel's failed() hooks.
• Mailer bypass risk. If it composes Symfony\Mime messages directly, it skips Laravel's mailer — meaning no provider failover, no mail logging, no theming hooks. Verify before trusting it with transactional email.
• Pin exact versions and review the lockfile. New vendor namespace, no publishing reputation, no CVE history discoverable. Treat as unaudited code.
• Abandonment is the default assumption. 0 stars / 0 dependents means no external pressure to keep it current. Assign an internal owner and add it to your dependency-review cadence.
• Extension points worth knowing: the transport interface (implement it), the notification/handler contract (implement or wrap it), and the routing/preference service (extract its schema even if you don't use its runtime).
• Debugging tip: when a notification silently no-ops, check in this order — (1) is the transport registered in the container, (2) did the config key land under the right root, (3) did the recipient router resolve an address for that channel. Failures here are typically silent, not exceptions.
• If any of the above is blocking, stop. The honest day-to-day answer for a Laravel team is: use Illuminate\Notifications, and lift this package's preference schema as inspiration. The bundle is a scoping artifact, not a runtime dependency.