lab123/lumen-notification
A lightweight notification package for Lumen that brings a Laravel-style API for sending alerts through mail, database, and other channels. Simple to install and configure, it suits microservices and small APIs that need reliable user notifications without pulling in the full framework.
Version 1.0.0 is the first stable tag, and it is breaking on platform requirements, not API: PHP ^8.1, Lumen 10/11, Laravel 10–13. Nothing in the vendor tree changed shape — it's still a thin integration layer that registers the Illuminate notification stack inside Lumen (which ships without it), plus the mail/services config stubs and the notification:table / make:notification commands. Before installing, read vendor/lab123/lumen-notification/src/ — specifically the provider's register() and boot() — and confirm what it actually binds. With 2 stars and no dependents, the provider is the documentation.
Decide your track first. On Lumen 5–9 you stay on 0.1.0-beta.2 permanently — there is no upgrade path and no further releases for those versions. If you are on Lumen 5–9, install the beta explicitly and accept that you are depending on an abandoned branch:
composer require "lab123/lumen-notification:^0.1.0-beta.2"
On PHP 8.1+ with Lumen 10/11, install the stable tag:
composer require "lab123/lumen-notification:^1.0"
Register the provider manually in bootstrap/app.php (Lumen has no package discovery):
$app->register(Lab123\LumenNotification\LumenNotificationServiceProvider::class);
If you plan to use the Notification facade or the database channel, the usual Lumen prerequisites still apply:
$app->withFacades();
$app->withEloquent();
Acknowledge the advisory before your first composer install in CI. Laravel/Lumen 10/11 are flagged by PKSA-zwc5-qtrz-zm1n with no upstream fix, so composer audit will fail the build. Add the ignore to composer.json deliberately, with the reason recorded next to it in your README/CHANGELOG — not silently in a shell alias:
"config": {
"audit": {
"ignore": ["PKSA-zwc5-qtrz-zm1n"]
}
}
Then publish or copy the config. Lumen's vendor:publish only works once the provider is registered; if a tag isn't documented, copy from the vendor tree directly:
php artisan vendor:publish --provider="Lab123\LumenNotification\LumenNotificationServiceProvider"
# fallback
cp vendor/lab123/lumen-notification/config/mail.php config/mail.php
cp vendor/lab123/lumen-notification/config/services.php config/services.php
Create the database table if you'll use the database channel:
php artisan notification:table
php artisan migrate
First use case: a welcome/password-reset email to an existing User model. Add Illuminate\Notifications\Notifiable, implement routeNotificationForMail() (or rely on the default email attribute), and send:
$user->notify(new App\Notifications\WelcomeNotification($user));
If that single call works end-to-end, the wiring is correct. Everything else is standard Laravel notification behaviour layered on top.
Pin the platform, not just the package. After 1.0.0 the meaningful pin is illuminate/notifications at the major matching your Lumen version. The package constraint spans Lumen 10/11 and Laravel 10–13, which is wider than any single app, so let Composer resolve the framework first and confirm afterwards:
composer why-not laravel/framework ^11.0
composer show lab123/lumen-notification illuminate/notifications
Notifiable models. The package doesn't replace Illuminate\Notifications\Notifiable; use it directly. In Lumen, the trait gives you notify(), notifyNow(), routeNotificationFor*, and the notifications() morphMany relation for the database channel.
use Illuminate\Notifications\Notifiable;
class User extends Model
{
use Notifiable;
public function routeNotificationForMail(): string
{
return $this->email;
}
}
On-demand notifications are the highest-value pattern in Lumen, because you often don't have an auth guard or notifiable model configured yet (contact forms, invites, ops alerts):
use Illuminate\Support\Facades\Notification;
Notification::route('mail', '[email protected]')
->route('slack', config('services.slack.webhook'))
->notify(new SystemAlert($message));
This is also the cleanest way to verify mail transport without touching Eloquent — reach for it first when debugging, and it doubles as your smoke test immediately after upgrading to 1.0.0.
Service-layer wrapper. Don't scatter $user->notify() across controllers. Lumen apps tend to have light domain layers, so a small dispatcher keeps channels and queue decisions in one place:
class Notifier
{
public function __construct(private ChannelManager $notifications) {}
public function send($notifiable, Notification $n): void
{
$this->notifications->send($notifiable, $n);
}
}
Injecting Illuminate\Notifications\ChannelManager works even when facades are disabled, and it still respects Notification::fake() in tests because the fake swaps that binding.
Queued notifications. Mark notifications implements ShouldQueue and set QUEUE_CONNECTION to redis/database in .env. Lumen defaults to sync, which means a slow SMTP handshake blocks the HTTP request — this is the single most common production surprise. Run php artisan queue:work and make sure the queue service provider is registered (the notification package generally does not do this for you).
class WelcomeNotification extends Notification implements ShouldQueue
{
public $tries = 3;
public $backoff = [10, 60];
public function via($notifiable): array { return ['mail', 'database']; }
public function toMail($notifiable): MailMessage
{
return (new MailMessage)
->subject('Welcome')
->markdown('emails.welcome', ['user' => $notifiable]);
}
}
Database channel / inbox. After notification:table, $user->notifications and $user->unreadNotifications are available. Use them for an in-app feed, and call $notification->markAsRead() in a route. Remember this table stores JSON payloads — treat it as a feed, not an audit log; prune it on a schedule.
Custom channels. The extension point is ChannelManager::extend, not the package. Register it in your own service provider after the package provider:
$this->app->afterResolving(ChannelManager::class, function (ChannelManager $manager) {
$manager->extend('sms', fn ($app) => new SmsChannel($app->make(SmsClient::class)));
});
Then via() can return 'sms'. This is how you'd add a local SMS gateway the package will never support.
Upgrade audit pattern. Because 1.0.0 is a platform bump, diff the provider between the two tags before you trust it — if src/ is byte-identical apart from composer.json, your regression risk is Composer resolution, not runtime:
git diff 0.1.0-beta.2 1.0.0 -- vendor/lab123/lumen-notification/src
Testing. With facades enabled:
Notification::fake();
$user->notify(new WelcomeNotification($user));
Notification::assertSentTo($user, WelcomeNotification::class, function ($n, $channels) {
return in_array('mail', $channels);
});
If facades are off, bind NotificationFake yourself or resolve ChannelManager — the fake is what you're actually swapping.
composer audit now fails by default. PKSA-zwc5-qtrz-zm1n affects Lumen 10/11 with no upstream fix. Add config.audit.ignore to composer.json, commit the reason, and set a calendar reminder to re-check — an ignore entry with no review date is how advisories get forgotten. Note that composer audit --no-dev does not exempt this; the advisory is on the framework itself.app/Providers/ and drop the dependency, or (b) plan the framework upgrade. Do not start new work on the beta.^8.1 is a hard floor. The upgrade to 1.0.0 cannot happen on PHP 8.0 regardless of your Lumen version. Check php -v on every deploy target and CI image before changing the constraint — the failure surfaces as an opaque Composer resolution error.Notification. If you also register Laravel's NotificationServiceProvider, you can end up with duplicate bindings or a resolved singleton that ignores your Notification::extend calls. Register exactly one path; check bootstrap/app.php for leftovers.extra.laravel.providers; a manual $app->register() plus discovery causes double registration.MAIL_MAILER vs MAIL_DRIVER. Laravel 9+ reads mail.default / MAIL_MAILER. With the 1.0.0 floor at Lumen 10, the shipped config/mail.php should already use default — but if you carried a config file forward from a pre-1.0 install, MailManager will throw or silently fall back. Diff against vendor/laravel/framework/src/Illuminate/Mail/MailManager.php.config/services.php. Mailgun, Postmark, SES and Slack all read services.*. The package ships it, but only if you actually copy/publish it — a missing file yields confusing "driver not configured" errors rather than a clear missing-config exception.MailMessage::markdown() requires the vendor mail views and the Markdown renderer. Lumen's view.paths is minimal; add resource_path('views') and publish resources/views/vendor/mail if the package supports it. Plain ->view() is more predictable if you're unsure.php artisan config:cache. After upgrading to 1.0.0 — especially if you re-published mail.php/services.php — run php artisan config:clear; a stale cache will happily serve the old config and hide the upgrade entirely.Notification::route('mail', $email) is fine; Notification::route('sms', ...) without a matching channel driver throws Notification not supported at send time, not at route time.uuidMorphs('notifiable'). If your models use auto-incrementing integer keys, confirm whether you need morphs() instead; a type mismatch fails silently on lookup rather than on insert.$notification->locale = 'fr' relies on translation files under lang/. Lumen doesn't ship a lang directory — create one or localized notifications fall back to the default strings without warning.composer why-not laravel/framework <version> before assuming a clean install; pin illuminate/notifications to the matching major if you hit a resolution conflict.$this->app->register(...) calls, vendor the provider into app/Providers/ and drop the dependency — you keep the config files and lose the supply-chain risk, which matters more now that the package pins an advisory-affected framework range.via() return values, (2) Queue::fake()/Notification::fake() left in a test, (3) QUEUE_CONNECTION=sync masking a failing job, (4) mail log (storage/logs/laravel.log with MAIL_MAILER=log), (5) transport credentials in config/services.php. Ninety percent of "notifications don't work" reports resolve at step 1 or 3.How can I help you explore Laravel packages today?