README

Laravel 通知器是一个用于发送通知（使用 Notifier）和监控（使用 Journal）的包，专为 Discord、Slack 和邮件设计。

基于 kiwilan/php-notifier。

重要

此包不支持推送通知或短信（如果您感兴趣，欢迎提交 PR）在 kiwilan/php-notifier。

关于

Laravel 提供了内置的通知和 Laravel 日志记录系统，此包是这些系统的替代品。

Notifier 允许发送通知，而不必链接到用户模型，而 Journal 基于 Log 门面。 Journal 可以使用 filament/notifications 包（不包括且不要求）将日志发送到数据库，并记录日志。

当原生 Laravel 通知是针对用户时，此包旨在帮助开发者进行调试和监控，但您也可以为用户使用它。

此包提供了对 Discord 和 Slack Webhook 的支持，但 Slack 仅提供基本支持（没有对旧版 API 的支持），对于更多功能，您可以使用 laravel/slack-notification-channel。为了避免依赖关系，此包不使用它。

Discord Webhook：支持消息和丰富嵌入。
Slack Webhook：支持消息和附件。
邮件：支持消息和附件与 symfony/mailer。

安装

您可以通过 composer 安装此包

composer require kiwilan/notifier-laravel

您可以使用以下命令发布配置文件

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

注意

配置文件完全是可选的，如果您有多个 Webhook，您可以创建自己的配置来发送通知。

这是发布配置文件的内容

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),
    ],
];

用法

Journal

Journal 是 Laravel 日志记录的一个实用工具。

use Kiwilan\Notifier\Facades\Journal;

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

到数据库

您可以使用 Journal 使用 filament/notifications 包将日志记录到数据库（您必须安装它）。

此方法将搜索 App\Models\User::class 并获取所有具有 canAccessPanel() 允许权限的用户，默认情况下所有具有访问权限的用户都将收到通知。

use Kiwilan\Notifier\Facades\Journal;

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

到通知器

您可以使用 Journal 使用 discord、mail 或 slack 发送通知（您必须设置配置文件）。

use Kiwilan\Notifier\Facades\Journal;

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

处理器

您可以将 Journal 用作 Laravel 异常的处理器。

toDatabase 是一个布尔值，用于使用 filament/notifications 包将异常记录到数据库（您必须安装它）。
toNotifier 是一个字符串，用于使用 discord、mail 或 slack 发送通知（您必须设置配置文件）。

<?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');
    });
  }
}

通知器

通知器是 Laravel 通知的替代品。

注意

如果 notifier.journal.debug 设置为 true，则发送和已发送的通知将记录 debug 级别的日志。在所有情况下，发送错误都将记录 error 级别的日志。

对于 HTTP 客户端，您可以在配置文件中配置 notifier.client 为 stream、curl 或 guzzle，并通过第二个参数覆盖 Discord、Slack 和 HTTP 的配置。

Discord

默认 webhook URL、用户名和头像 URL 可以在配置文件中设置。

use Kiwilan\Notifier\Facades\Notifier;

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

$notifier->send();

您可以传递自定义 webhook URL

use Kiwilan\Notifier\Facades\Notifier;

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

邮件

默认的 mailer、host、port、username、password、encryption、from address、from name、to address 和 to name 可以在配置文件中设置。

您可以使用 NOTIFIER_MAIL_LARAVEL_OVERRIDE 来使用 Laravel 邮件发送器而不是包邮件发送器。

use Kiwilan\Notifier\Facades\Notifier;

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

$notifier->send();

您可以传递自定义邮件发送器

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

默认 webhook URL 可以在配置文件中设置。

use Kiwilan\Notifier\Facades\Notifier;

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

$notifier->send();

您可以传递自定义 webhook URL

use Kiwilan\Notifier\Facades\Notifier;

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

HTTP

您可以使用 Notifier 通过 http 方法发送请求。如果已在配置文件中设置了 notifier.http.url，则 URL 可以是 null。

use Kiwilan\Notifier\Facades\Notifier;

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

命令

您可以将 Notifier 用作命令，通过 discord、mail 或 slack 发送通知。

有两个选项可用

-t 或 --type 用于设置通知类型，默认为 mail。
-w 或 --webhook 用于设置 webhook URL（仅适用于 discord 和 slack）。如果未设置，则将使用配置文件中的默认 webhook URL。

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

测试

composer test

变更日志

有关最近更改的更多信息，请参阅变更日志。

贡献

有关详细信息，请参阅贡献指南。

安全漏洞

请查看我们关于如何报告安全漏洞的安全策略。

鸣谢

许可证

MIT 许可证 (MIT)。有关更多信息，请参阅许可证文件。

kiwilan / notifier-laravel

维护者

详细信息