Notifier for Laravel

Notifier for Laravel is a package to send notifications (with Notifier) and monitoring (with Journal), built for Discord, Slack and mails.

Based on kiwilan/php-notifier.

Important

This package does not support push notifications or SMS (if you interested, a PR is welcome) on kiwilan/php-notifier.

About

Laravel offers a built-in Notification and Laravel Logging systems, this package is an alternative to these systems.

Notifier allows to send notifications without link to a user model and advanced and Journal is based on Log facade. Journal can write logs send notifications and write logs in the database with filament/notifications package (not included and not required).

When native Laravel notifications are for users, this package is designed for developers to help for debugging and monitoring, but you can use it for users too.

This package offer a support for Discord and Slack webhooks, but Slack has only basic support (without legacy API support), for more, you can use laravel/slack-notification-channel. To avoid dependencies, this package doesn't use it.

• Discord webhooks: support message and rich embeds.
• Slack webhooks: support message, attachments.
• Mail: support message and attachments with symfony/mailer.

Installation

You can install the package via composer:

composer require kiwilan/notifier-laravel

You can publish the config file with:

php artisan vendor:publish --tag="notifier-config"

Note

The configuration file is totally optional, if you have multiple webhooks, you can create your own configs to send notifications.

This is the contents of the published config file:

return [
    // Default notifier client to send HTTP request, can be `stream`, `curl` or `guzzle`.
    // `guzzle` is not included in this package, you need to install it manually.
    'client' => env('NOTIFIER_CLIENT', 'stream'),

    'discord' => [
        // Default Discord webhook URL.
        'webhook' => env('NOTIFIER_DISCORD_WEBHOOK', null),
        // Default Discord username.
        'username' => env('NOTIFIER_DISCORD_USERNAME', null),
        // Default Discord avatar URL.
        'avatar_url' => env('NOTIFIER_DISCORD_AVATAR_URL', null),
    ],

    'mail' => [
        // Use Laravel mailer instead package from `.env` file.
        'laravel_override' => env('NOTIFIER_MAIL_LARAVEL_OVERRIDE', false),
        // Set default subject for mail.
        'subject' => env('NOTIFIER_MAIL_SUBJECT', 'Notifier'),
        // Set default mailer from `.env` file.
        'mailer' => env('NOTIFIER_MAIL_MAILER', 'smtp'),
        'host' => env('NOTIFIER_MAIL_HOST', 'mailpit'),
        'port' => env('NOTIFIER_MAIL_PORT', 1025),
        'username' => env('NOTIFIER_MAIL_USERNAME', null),
        'password' => env('NOTIFIER_MAIL_PASSWORD', null),
        'encryption' => env('NOTIFIER_MAIL_ENCRYPTION', 'tls'),
        'from_address' => env('NOTIFIER_MAIL_FROM_ADDRESS', null),
        'from_name' => env('NOTIFIER_MAIL_FROM_NAME', null),
        'to_address' => env('NOTIFIER_MAIL_TO_ADDRESS', null),
        'to_name' => env('NOTIFIER_MAIL_TO_NAME', null),
    ],

    'slack' => [
        // Default Slack webhook URL.
        'webhook' => env('NOTIFIER_SLACK_WEBHOOK', null),
    ],

    'http' => [
        // Default HTTP URL to send request.
        'url' => env('NOTIFIER_HTTP_URL', null),
    ],

    // This feature use `filament/notifications` package, not included in this package.
    'to_database' => [
        // Default user model for notification.
        'model' => env('NOTIFIER_TO_DATABASE_USER', 'App\Models\User'),
        // Recipients ID for notification.
        'recipients_id' => explode(',', env('NOTIFIER_TO_DATABASE_RECIPIENTS_ID', '')),
    ],

    'journal' => [
        // Write logs for debugging when notifications are sent.
        'debug' => env('NOTIFIER_JOURNAL_DEBUG', false),
        // Write error logs with `error_log` function, in addition to Laravel log.
        'use_error_log' => env('NOTIFIER_JOURNAL_USE_ERROR_LOG', true),
    ],
];

Usage

Journal

Journal is a utility class for Laravel Logging.

use Kiwilan\Notifier\Facades\Journal;

Journal::debug('Hello, Journal!');
Journal::info('Hello, Journal!');
Journal::warning('Hello, Journal!');
Journal::error('Hello, Journal!');

To database

You can use Journal to log in the database with filament/notifications package (you have to install it).

This method will search App\Models\User::class and get all users with canAccessPanel() allowed, by default all users with access will be notified.

use Kiwilan\Notifier\Facades\Journal;

Journal::info('Hello, Journal!')
  ->toDatabase();

To notifier

You can use Journal to send a notification with discord, mail or slack (you have to set the config file).

use Kiwilan\Notifier\Facades\Journal;

Journal::info('Hello, Journal!')
  ->toNotifier('discord');

Handler

You can use Journal as a handler for Laravel Exceptions.

• toDatabase is a boolean to log the exception in the database with filament/notifications package (you have to install it).
• toNotifier is a string to send a notification with discord, mail or slack (you have to set the config file).

<?php

namespace App\Exceptions;

use Kiwilan\Notifier\Facades\Journal;
use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
use Throwable;

class Handler extends ExceptionHandler
{
  public function register(): void
  {
    $this->reportable(function (Throwable $e) {
      Journal::handler($e, toDatabase: true, toNotifier: 'mail');
    });
  }
}

Notifier

Notifier is an alternative to Laravel Notifications.

Note

If notifier.journal.debug is true, debug level logs will be written for sending and sent notifications. In all cases, error level logs will be written for sending errors.

For HTTP client, you can configure notifier.client in the config file with stream, curl or guzzle and override it with second parameter for Discord, Slack and HTTP.

Discord

Default webhook URL, username and avatar URL can be set in the config file.

use Kiwilan\Notifier\Facades\Notifier;

$notifier = Notifier::discord()
  ->username('Laravel')
  ->avatarUrl('https://laravel.com/img/favicon/favicon-32x32.png')
  ->message('Hello, Discord!');

$notifier->send();

You can pass a custom webhook URL:

use Kiwilan\Notifier\Facades\Notifier;

$notifier = Notifier::discord('https://discord.com/api/webhooks/1234567890/ABCDEFGHIJKLMN0123456789');

Mail

Default mailer, host, port, username, password, encryption, from address, from name, to address and to name can be set in the config file.

You can use NOTIFIER_MAIL_LARAVEL_OVERRIDE to use Laravel mailer instead of package mailer.

use Kiwilan\Notifier\Facades\Notifier;

$notifier = Notifier::mail()
  ->subject('Hello, Mail!')
  ->message('Hello, Mail!');

$notifier->send();

You can pass a custom mailer:

use Kiwilan\Notifier\Facades\Notifier;

$notifier = Notifier::mail('smtp')
  ->from('hello@example.com', 'Hello')
  ->to('to@example.com', 'To')
  ->subject('Hello, Mail!')
  ->message('Hello, Mail!')
  ->mailer('smtp')
  ->host('mailpit')
  ->port(1025)
  ->username(null)
  ->password(null)
  ->encryption('tls');

Slack

Default webhook URL can be set in the config file.

use Kiwilan\Notifier\Facades\Notifier;

$notifier = Notifier::slack()
  ->message('Hello, Slack!');

$notifier->send();

You can pass a custom webhook URL:

use Kiwilan\Notifier\Facades\Notifier;

$notifier = Notifier::slack('https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX');

HTTP

You can use Notifier to send a request with http method. URL can be null if you set it in the config file with notifier.http.url.

use Kiwilan\Notifier\Facades\Notifier;

$notifier = Notifier::http('https://example.com')
  ->method('POST')
  ->headers([
    'Content-Type' => 'application/json',
  ])
  ->body([
    'hello' => 'world',
  ])
  ->send();

Command

You can use Notifier as a command to send a notification with discord, mail or slack.

Two options are available:

• -t or --type to set the type of notification, default is mail.
• -w or --webhook to set the webhook URL (only for discord and slack). If not set, the default webhook URL from the config file will be used.

php artisan notifier -t=discord -w=https://discord.com/api/webhooks/1234567890/ABCDEFGHIJKLMN0123456789 "Hello, Discord!"

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Ewilan Rivière
• All Contributors

License

The MIT License (MIT). Please see License File for more information.