Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kiwilan/notifier-laravel
Notifier for Laravel is a package to send notifications and monitoring, built for Discord, Slack and mails.
https://github.com/kiwilan/notifier-laravel
discord laravel logging mail notification slack webhook
Last synced: about 1 month ago
JSON representation
Notifier for Laravel is a package to send notifications and monitoring, built for Discord, Slack and mails.
- Host: GitHub
- URL: https://github.com/kiwilan/notifier-laravel
- Owner: kiwilan
- License: mit
- Created: 2024-02-01T18:54:05.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2024-03-16T09:58:13.000Z (10 months ago)
- Last Synced: 2024-03-16T11:14:08.273Z (10 months ago)
- Topics: discord, laravel, logging, mail, notification, slack, webhook
- Language: PHP
- Homepage: https://packagist.org/packages/kiwilan/notifier-laravel
- Size: 382 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
README
# **Notifier for Laravel**
[![php][php-version-src]][php-version-href]
[![laravel][laravel-src]][laravel-href]
[![version][version-src]][version-href]
[![downloads][downloads-src]][downloads-href]
[![license][license-src]][license-href]
[![tests][tests-src]][tests-href]
[![codecov][codecov-src]][codecov-href]
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`](https://github.com/kiwilan/php-notifier).
> [!IMPORTANT]
> This package does not support push notifications or SMS (if you interested, a PR is welcome) on [`kiwilan/php-notifier`](https://github.com/kiwilan/php-notifier).
## About
Laravel offers a built-in [Notification](https://laravel.com/docs/10.x/notifications) and [Laravel Logging](https://laravel.com/docs/10.x/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`](https://github.com/laravel/slack-notification-channel). To avoid dependencies, this package doesn't use it.
- [Discord webhooks](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks): support message and rich embeds.
- [Slack webhooks](https://api.slack.com/messaging/webhooks): support message, attachments.
- Mail: support message and attachments with [`symfony/mailer`](https://symfony.com/doc/current/mailer.html).
## Installation
You can install the package via composer:
```bash
composer require kiwilan/notifier-laravel
```
You can publish the config file with:
```bash
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:
```php
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](https://laravel.com/docs/10.x/logging).
```php
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.
```php
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).
```php
use Kiwilan\Notifier\Facades\Journal;
Journal::info('Hello, Journal!')
->toNotifier('discord');
```
#### Handler
You can use Journal as a handler for [Laravel Exceptions](https://laravel.com/docs/10.x/errors).
- `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
reportable(function (Throwable $e) {
Journal::handler($e, toDatabase: true, toNotifier: 'mail');
});
}
}
```
### Notifier
Notifier is an alternative to [Laravel Notifications](https://laravel.com/docs/10.x/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.
```php
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:
```php
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.
```php
use Kiwilan\Notifier\Facades\Notifier;
$notifier = Notifier::mail()
->subject('Hello, Mail!')
->message('Hello, Mail!');
$notifier->send();
```
You can pass a custom mailer:
```php
use Kiwilan\Notifier\Facades\Notifier;
$notifier = Notifier::mail('smtp')
->from('[email protected]', 'Hello')
->to('[email protected]', '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.
```php
use Kiwilan\Notifier\Facades\Notifier;
$notifier = Notifier::slack()
->message('Hello, Slack!');
$notifier->send();
```
You can pass a custom webhook URL:
```php
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`.
```php
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.
```bash
php artisan notifier -t=discord -w=https://discord.com/api/webhooks/1234567890/ABCDEFGHIJKLMN0123456789 "Hello, Discord!"
```
## Testing
```bash
composer test
```
## Changelog
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
## Contributing
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
## Security Vulnerabilities
Please review [our security policy](../../security/policy) on how to report security vulnerabilities.
## Credits
- [Ewilan Rivière](https://github.com/ewilan-riviere)
- [All Contributors](../../contributors)
## License
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
[
](https://github.com/kiwilan)
[version-src]: https://img.shields.io/packagist/v/kiwilan/notifier-laravel.svg?style=flat-square&colorA=18181B&colorB=777BB4
[version-href]: https://packagist.org/packages/kiwilan/notifier-laravel
[php-version-src]: https://img.shields.io/static/v1?style=flat-square&label=PHP&message=v8.1&color=777BB4&logo=php&logoColor=ffffff&labelColor=18181b
[php-version-href]: https://www.php.net/
[downloads-src]: https://img.shields.io/packagist/dt/kiwilan/notifier-laravel.svg?style=flat-square&colorA=18181B&colorB=777BB4
[downloads-href]: https://packagist.org/packages/kiwilan/notifier-laravel
[license-src]: https://img.shields.io/github/license/kiwilan/notifier-laravel.svg?style=flat-square&colorA=18181B&colorB=777BB4
[license-href]: https://github.com/kiwilan/notifier-laravel/blob/main/README.md
[tests-src]: https://img.shields.io/github/actions/workflow/status/kiwilan/notifier-laravel/run-tests.yml?branch=main&label=tests&style=flat-square&colorA=18181B
[tests-href]: https://github.com/kiwilan/notifier-laravel/actions/workflows/run-tests.yml
[codecov-src]: https://codecov.io/gh/kiwilan/notifier-laravel/branch/main/graph/badge.svg?token=1py1fk6vwc
[codecov-href]: https://codecov.io/gh/kiwilan/notifier-laravel
[laravel-src]: https://img.shields.io/static/v1?label=Laravel&message=v10-11&style=flat-square&colorA=18181B&colorB=FF2D20
[laravel-href]: https://laravel.com