Notification Bundle Laravel Package

Getting Started

• Establish which stack you're actually on. idci/notification-bundle is a Symfony2 bundle, not a Laravel package. There is no ServiceProvider, no facade, no publishable config, no package auto-discovery. On Laravel you cannot composer require this and call it a day — the realistic day-one move is to read the repo as a domain reference and build on Laravel's native Notifiable/Notification primitives. On a legacy Symfony2 app, follow the steps below.
• Install (Symfony2 only). Add idci/notification-bundle via Composer. Check the composer.json require block first — the Symfony/PHP constraints are old (pre-8.0), so you may need a pinned tag/branch or a VCS repositories entry pointing at the GitHub URL. Expect resolution friction on any modern PHP runtime.
• Register the bundle in app/AppKernel.php inside registerBundles(), scoped to the right environment block (dev/test/prod).
• Import configuration into app/config/config.yml. Don't guess the key: open DependencyInjection/Configuration.php first — the tree usually exposes entity class overrides, notifier/channel toggles, and cleanup settings.
• Create the schema. php app/console doctrine:schema:update --force, or generate a Doctrine migration so the Notification and association tables exist.
• Where to look first. Entity/, Manager/, Event/, and Notifier/. The manager service is the entry point — it wraps persistence and dispatches events. Inject it into a controller or service and call the create/notify method.
• First use case. From a controller or domain service: create a notification for the current user, render an unread list in a Twig template, mark items read on click. That exercises create → persist → query → update and validates wiring (container, Doctrine, config) in one pass.

Implementation Patterns

• Inject the manager, don't fetch it. Constructor-inject the notification manager service rather than calling $container->get(...) inline. It keeps call sites testable and decouples you from the service ID, which is the first thing to change if you fork.
• Create notifications from domain events. Rather than sprinkling notify() calls through controllers, dispatch your own domain events (order placed, comment posted) and let a listener create the Notification. This is the idiomatic Symfony2 pattern and the bundle's cleanest extension point — it also keeps the notifier layer out of your request handlers.
• Read/unread lifecycle. Keep read-state methods on the entity (markAsRead(), isRead()) and repository finders (findUnreadByUser(), paginated feeds). Avoid ad-hoc DQL in controllers; put the query logic in the Manager/repository.
• Per-channel notifiers. The bundle's model is notifier-per-channel. Implement the bundle's notifier interface for each channel (mail, in-app, custom), register the class as a service, and tag it so the manager discovers it. Prefer adding channels this way over editing the manager.
• Config-driven overrides. Use the bundle config to swap the entity class or toggle notifiers rather than editing vendor code — this is what keeps a fork mergeable.
• Transaction boundaries. Persist the notification, then dispatch delivery after the flush/commit. Sending inside an open transaction means a rollback can leave a delivered notification with no record.
• Test against mocks. Unit-test listeners by mocking the manager and asserting notify() was called with the right recipient/payload; integration-test the full create→query loop against a test database so schema and mapping issues surface early.
• If you're on Laravel, port — don't bridge. Reimplement the 2–3 behaviors you actually need (persistence, channel routing, dispatch) on Laravel's notifications table migration, via() channel methods, and ShouldQueue. Port any non-obvious routing/batching/recipient-resolution rules as explicit service classes behind an interface, with tests pinning behavior. Treat the repo as a spec, not a dependency.

Gotchas and Tips

• EOL stack. Symfony2 reached end-of-life in 2018; the code targets PHP 5.x/7.0-era constraints and Swiftmailer/Doctrine assumptions. It will not cleanly resolve on PHP 8.2+, and forcing it pins your dependency tree and blocks framework upgrades.
• No Laravel integration path. There is no PSR-4 Laravel auto-discovery and no illuminate/* requirement. Wrapping a foreign DI container and Doctrine ORM inside Laravel is a net-negative architecture decision — avoid it even if it "works" in a spike.
• Synchronous delivery on the request path. This era implies notification writes and sends inline with the user action. That surfaces as elevated p95 latency on the triggering endpoint and cascading timeouts when a mail/SMS provider degrades. If you port any of it, put delivery on a queue (ShouldQueue + Horizon on Laravel) from day one.
• Silent failures and duplicates. Expect no retry or dead-letter path. Add idempotency keys if you reimplement, and log every send attempt — otherwise a provider outage disappears into an exception you swallowed.
• Schema drift. Doctrine migrations don't map cleanly onto Laravel's migration history. If you're porting, rebuild the schema as a fresh Laravel migration rather than translating Doctine diffs.
• Config keys and service IDs are undocumented. Read DependencyInjection/Configuration.php and the service XML/YAML before writing config; guessing the tree wastes hours. Use debug:container and Doctrine's SQL logger to confirm what's actually wired.
• Event ordering matters. Listeners that create notifications should run after the originating entity is persisted. Set priorities deliberately; a listener firing pre-flush can reference a null ID.
• Extension points to lean on: tagged custom notifier services, entity class override via config, and event subscribers. Avoid editing vendor files directly — with 4 stars and 0 dependents there is no upstream patch stream, so your fork is permanent. Track any local edits in a branch you control.
• Bus-factor warning. Symfony2/Doctrine ramp-up produces knowledge you will throw away on a Laravel stack. Budget the learning toward Laravel's notification and queue internals instead — that knowledge compounds.