Notifications Laravel Package

Getting Started

• Install with composer require mrshanebarron/notifications and let package discovery register the service provider. Confirm the resolved version is ^1.0.1 — 1.0.0 shipped a config filename that the package no longer looks for.
• Publish config before touching the API: php artisan vendor:publish --tag=sb-config. If the tag returns "no publishable resources", run vendor:publish with no tag and read the group name out of the prompt; tags and filenames do not always match.
• Open config/sb-notifications.php (or whatever the sb- file publishes as) first. It is the single source of truth: channels, queue connection, database table, and toggles all live there, and env var names are derived from the keys. Read it top to bottom before writing a notification class.
• Check the service provider next — mergeConfigFrom, publishes, and any container bindings. Three lines tell you whether partial config overrides are safe (deep merge) or whether you must copy nested blocks whole (shallow array_merge, the common case).
• First use case: send one notification to yourself through the default channel in a local environment. Define a single notification class, dispatch it synchronously, and confirm delivery end to end. That exercises config, channel resolution, and the transport in one pass.
• Upgrade path from 1.0.0: republish with --force, diff the old file against the new stub, delete the stale config, then php artisan config:clear. Do this before any code change or you will debug the wrong layer.

Implementation Patterns

• Config-first, code-second. Drive channel selection, queue connection, and delivery toggles through config/sb-*.php and .env, never constructor arguments. Ops can then change behaviour without an application deploy, and tests can swap implementations with a config([...]) call.
• One notification class per intent. Name them for the event, not the channel — InvoicePaid, TrialExpiring — and declare channels inside the class. A class that fans out to mail, database, and a custom transport keeps delivery logic out of controllers and models.
• Wrap in a thin application service. App\Services\Notifier exposing two or three intention-revealing methods (notifyInvoicePaid, notifyTrialExpiring) keeps package types out of controllers and gives you one file to change when the package API shifts.
• Queue the fan-out, not the object. Implement ShouldQueue on the notification and dispatch normally. Do not serialise a resolved package manager into a job payload — reconstruct inside handle() instead. Stale-config bugs almost always originate from a serialised manager.
• Bind the contract, not the concrete class. Where the package exposes an interface, bind your own implementation in AppServiceProvider after the package provider registers, so you can layer logging, retries, or tenant scoping onto the default without forking vendor code.
• Database notifications need a migration. If a database channel exists, publish or create the notifications table before writing to it, and check the config's table name matches. Silent no-ops on a missing table are a classic first-run symptom.
• Custom channels as classes. Implement the package's channel contract (or Laravel's send method signature if it delegates) and register the alias in config. This is the cheapest extension point — SMS, Slack, in-app — and keeps third-party SDKs out of notification classes.
• Test with fakes at the boundary. Notification::fake() (or the package's equivalent) for assertions on who was notified, Http::fake() and Mail::fake() for the transport. Reserve config overrides for behaviour toggles. Assert on the notification class and payload rather than on delivery side effects.
• Feature-flag the rollout. Add features.notifications_enabled at the app level and guard dispatch sites, so a misbehaving channel can be turned off in production without reverting the release.
• Observe before you instrument. If the package fires events on send or failure, register a listener in staging and log payloads. Cheaper than adding dd() inside vendor/.

Gotchas and Tips

• The 1.0.1 config rename is the headline risk. Published config from 1.0.0 sits at a path the package no longer reads. Symptom: your tuned settings are silently ignored and defaults apply. Fix: republish with --force, diff, delete the stale file.
• Two config files can coexist. A rename never deletes the old one. config/notifications.php sitting next to config/sb-notifications.php is the standard post-upgrade state — audit config/ after every patch release.
• Cached config masks the fix. config:clear locally and config:cache in the deploy pipeline. A cached config from before the rename keeps old values alive and makes it look like the upgrade did nothing. Container images with config baked at build time need a rebuild, not a restart.
• Verify the publish tag separately from the filename. --tag= mismatches are common. When in doubt, run vendor:publish bare and read the prompt.
• Merge semantics bite on nested keys. mergeConfigFrom is a shallow array_merge. A partial override of a nested block (e.g. one channel's options) replaces the whole block and drops sibling keys. Copy nested blocks in full.
• Published config freezes at publish time. New keys in later releases never appear in your file. Diff vendor/mrshanebarron/notifications/config/ against yours on each upgrade and port additions across — worth automating in CI.
• .env values are strings. Cast in the config file: (bool) env('SB_QUEUE_ENABLED', false). Do not trust the package to coerce "false".
• Queue worker restarts after deploy. Queued notifications carry the notification class and payload; if the shape changed, in-flight jobs can fail against new code. Restart workers as part of the release, and consider ShouldBeUnique or idempotency keys for anything user-visible.
• Debugging order: resolved config values (config('sb.*')) → container binding (app()->bound(...)) → resolved instance class → the outbound transport call. Ninety percent of "notifications aren't sending" reports resolve at step one.
• Pin the version. "mrshanebarron/notifications": "^1.0.1" in composer.json so no environment resolves back to the broken 1.0.0. Note that a config key rename is arguably breaking and would normally warrant 1.1.0 — worth raising with the maintainer rather than absorbing silently.
• Extension points live in the provider. Read bind, singleton, and extend calls before deciding to fork. Most behavioural changes (retry policy, logging, per-tenant transports) are achievable by rebinding after the package provider has registered.