Notifications

composer require glueful/email-notification
php glueful extensions:enable email-notification   # also runs its migrations

MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_ENCRYPTION=tls
MAIL_USERNAME=your-username
MAIL_PASSWORD=your-password
[email protected]
MAIL_FROM_NAME="Your App"

use Glueful\Notifications\Services\NotificationService;

$notifiable = new UserNotifiable($user['uuid'], $user['email']);
$notifications = app($context, NotificationService::class);

$result = $notifications->send(
    type: 'user.welcome',
    notifiable: $notifiable,
    subject: 'Welcome!',
    data: [
        'template_name' => 'welcome',
        'name' => $user['name'],
        'action_url' => 'https://app.example.com/get-started',
    ],
    options: ['channels' => ['email']]
);

namespace App\Notifications;

use Glueful\Notifications\Contracts\Notifiable;

class UserNotifiable implements Notifiable
{
    public function __construct(
        private string $uuid,
        private string $email
    ) {}

    public function routeNotificationFor(string $channel)
    {
        // Map channel to recipient. Extend for SMS, push, etc.
        return $channel === 'email' ? $this->email : null;
    }

    public function getNotifiableId(): string
    {
        return $this->uuid;
    }

    public function getNotifiableType(): string
    {
        return 'user';
    }

    public function shouldReceiveNotification(string $notificationType, string $channel): bool
    {
        return true; // Consult stored preferences here if you keep them
    }

    public function getNotificationPreferences(): array
    {
        return [];
    }
}

$notifications->send('order.shipped', $notifiable, 'Your order has shipped', [
    'order_id' => $orderId,
]); // default_channels => ['database']

$unread = $notifications->getUnreadCount($notifiable);
$notifications->markAllAsRead($notifiable);

// Persist + database now; email on the queue
$notifications->sendSplit(
    type: 'order.placed',
    notifiable: $notifiable,
    subject: 'Order confirmation',
    data: ['template_name' => 'default', 'message' => 'Thanks for your order!'],
    persistNowChannels: ['database'],
    dispatchAsyncChannels: ['email'],
);

// Equivalent: options sync_channels / async_channels on send()
$notifications->send('order.placed', $notifiable, 'Order confirmation', $data, [
    'async_channels' => ['email'],
]);

php glueful queue:work --queue=notifications,default

$notifications->send(
    type: 'reminder',
    notifiable: $notifiable,
    subject: "Don't forget!",
    data: ['template_name' => 'default', 'message' => 'Your trial ends tomorrow'],
    options: [
        'schedule' => new \DateTime('+1 day'),
        'channels' => ['database', 'email'],
    ]
);

$notifications->send('urgent.alert', $notifiable, 'Action Required', $data, [
    'channels' => ['email'],
    'priority' => 'high',
]);

$notifications->send('order.placed', $notifiable, 'Order confirmation', $data, [
    'channels' => ['email'],
    'idempotency_key' => "order-placed:{$orderUuid}",
]);

php glueful notifications:process-retries

use Glueful\Events\EventService;
use Glueful\Notifications\Events\NotificationSent;
use Glueful\Notifications\Events\NotificationFailed;

$events = app($context, EventService::class);

$events->addListener(NotificationSent::class, function ($event) use ($context) {
    app($context, \Psr\Log\LoggerInterface::class)->info('Notification sent', [
        'type' => $event->getNotification()->getType(),
        'channel' => $event->getChannel(),
    ]);
});

$events->addListener(NotificationFailed::class, function ($event) use ($context) {
    app($context, \Psr\Log\LoggerInterface::class)->error('Notification failed', [
        'type' => $event->getNotification()->getType(),
        'error' => $event->getReason(),
    ]);
});

return [
    'default_channels' => ['database'],
    'async_queue' => 'notifications',
    'channel_failure_policy' => 'any_success',
    'critical_channels' => [],
    'idempotency_enabled' => true,
    'idempotency_ttl_seconds' => 300,
    'max_retry_attempts' => 3,
    'retry_delay_seconds' => 60,
];

return [
    'retry' => [
        'enabled' => env('MAIL_RETRY_ENABLED', true),
        'max_attempts' => env('MAIL_RETRY_MAX_ATTEMPTS', 3),
        'delay' => env('MAIL_RETRY_DELAY', 300),
        'backoff' => env('MAIL_RETRY_BACKOFF', 'exponential'),
        'jitter' => env('MAIL_RETRY_JITTER', true),
    ],
    'debug' => ['enabled' => env('MAIL_DEBUG', false)],        // log recipient/subject/type per send
    'logging' => ['enabled' => env('MAIL_LOG_RESULTS', false)], // log each send outcome
    'security' => [
        'allowed_domains' => env('MAIL_ALLOWED_DOMAINS', null),  // exact-match allowlist
        'blocked_domains' => env('MAIL_BLOCKED_DOMAINS', null),  // also blocks subdomains
        'attachment_allowed_paths' => null,                       // null = app storage dir
    ],
];

// ✅ Good - persisted now, emailed by a worker
$notifications->sendSplit($type, $notifiable, $subject, $data, ['database'], ['email']);

// ❌ Bad - the request waits on SMTP
$notifications->send($type, $notifiable, $subject, $data, ['channels' => ['email']]);

// ✅ Good - personal
"Hi {$user['name']}, your order is ready!"

// ❌ Bad - generic
"Your order is ready."

public function testWelcomeNotification(): void
{
    $notifiable = new \App\Notifications\UserNotifiable('user-uuid', '[email protected]');

    $result = app($this->app->getContext(), \Glueful\Notifications\Services\NotificationService::class)->send(
        type: 'user.welcome',
        notifiable: $notifiable,
        subject: 'Welcome!',
        data: ['template_name' => 'welcome', 'name' => 'Jane Doe'],
        options: ['channels' => ['email']]
    );

    $this->assertSame('success', $result['status']);
}

namespace App\Channels;

use Glueful\Notifications\Contracts\Notifiable;
use Glueful\Notifications\Contracts\NotificationChannel;

final class SmsChannel implements NotificationChannel
{
    public function __construct(private readonly SmsProvider $sms)
    {
    }

    public function getChannelName(): string
    {
        return 'sms';
    }

    public function isAvailable(): bool
    {
        return $this->sms->isConfigured();
    }

    public function format(array $data, Notifiable $notifiable): array
    {
        return $data;
    }

    public function getConfig(): array
    {
        return [];
    }

    public function send(Notifiable $notifiable, array $data): bool
    {
        $phone = $notifiable->routeNotificationFor('sms');
        if (!is_string($phone) || $phone === '') {
            return false;
        }

        return $this->sms->send($phone, (string) ($data['body'] ?? ''))->isSuccessful();
    }
}

use Glueful\Bootstrap\ApplicationContext;
use Glueful\Extensions\ServiceProvider;

final class SmsServiceProvider extends ServiceProvider
{
    public function boot(ApplicationContext $context): void
    {
        $this->registerNotificationChannel($this->app->get(SmsChannel::class));
    }
}