kiwilan/php-notifier

PHP Notifier is a package to send mails or notifications for Discord or Slack.

Fund package maintenance!
kiwilan

0.0.40 2024-05-02 11:08 UTC

README

Banner with british letter box picture in background and Notifier title

php version downloads license tests codecov

PHP Notifier is a package to send mails or notifications for Discord or Slack.

Important

This package does not support push notifications or SMS (if you interested, a PR is welcome).

Installation

You can install the package via composer:

composer require kiwilan/php-notifier

Note

For Laravel, you can use kiwilan/notifier-laravel package.

Usage

This package offer a support for Discord and Slack webhooks, and emails with symfony/mailer.

  • Discord: support message and rich embeds webhooks.
  • Slack: support message and attachments webhooks (without legacy API support).
  • Mail: support message and attachments with symfony/mailer.

Discord

You can send simple message, with user and avatar. Default user and avatar will be webhook's name and avatar.

use Kiwilan\Notifier\Notifier;

$notifier = new Notifier();
$discord = $notifier->discord('https://discord.com/api/webhooks/1234567890/ABCDEFGHIJKLMN0123456789')
    ->message('Hello, Discord!')
    ->user('Notifier', 'https://raw.githubusercontent.com/kiwilan/php-notifier/main/docs/banner.jpg')
    ->send();

You can also send rich embeds.

discord-rich-embed

use Kiwilan\Notifier\Notifier;

$notifier = new Notifier();
$discord = $notifier->discord($webhook)
    ->rich('Rich advanced')
    ->title('Notifier')
    ->user('Notifier', 'https://raw.githubusercontent.com/kiwilan/php-notifier/main/docs/banner.jpg')
    ->url('https://ewilan-riviere.com')
    ->author('Author', 'https://ewilan-riviere.com', 'https://raw.githubusercontent.com/kiwilan/php-notifier/main/docs/banner.jpg')
    ->color('#3498db')
    ->timestamp()
    ->fields([
        ['name' => 'Field 1', 'value' => 'Value 1'],
        ['name' => 'Field 2', 'value' => 'Value 2'],
    ], inline: true)
    ->thumbnail('https://raw.githubusercontent.com/kiwilan/php-notifier/main/docs/banner.jpg')
    ->image('https://raw.githubusercontent.com/kiwilan/php-notifier/main/docs/banner.jpg')
    ->footer('Footer', 'https://raw.githubusercontent.com/kiwilan/php-notifier/main/docs/banner.jpg')
    ->send();

Mail

Mail use symfony/mailer to send emails.

use Kiwilan\Notifier\Notifier;

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

Note

If html is not set, message will be used as HTML content. And if html is set but not message, html will be used as plain text content with strip_tags method.

Multiple recipients can be added with to method.

use Symfony\Component\Mime\Address;

$mailConfig->from('hello@example.com', 'Hello')
    ->to([
      new Address('to1@example.com', 'To1'),
      new Address('to2@example.com', 'To2'),
    ])
    ->send();

You can add attachments with addAttachment method.

$mailConfig->addAttachment('path/to/file.txt', 'file.txt')
    ->send();

Slack

You can send simple message.

use Kiwilan\Notifier\Notifier;

$notifier = new Notifier();
$slack = $notifier->slack('https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX')
    ->message('Hello, Slack!')
    ->send();

You can also send attachments.

use Kiwilan\Notifier\Notifier;

$notifier = new Notifier();
$slack = $notifier->slack($webhook)
    ->attachment('*Hello, Slack!*')
    ->color('#36a64f')
    ->pretext('Optional pre-text that appears above the attachment block')
    ->author('Kiwilan', 'https://github.com/kiwilan')
    ->title('php-notifier', 'https://github.com/kiwilan/php-notifier')
    ->text('Optional text that appears within the attachment')
    ->fields([
        [
            'title' => 'Priority',
            'value' => 'High',
            'short' => false,
        ],
        [
            'title' => 'Priority',
            'value' => 'High',
            'short' => false,
        ],
    ])
    ->imageUrl('https://raw.githubusercontent.com/kiwilan/php-notifier/main/docs/banner.jpg')
    ->footer('Slack API', 'https://raw.githubusercontent.com/kiwilan/php-notifier/main/docs/banner.jpg')
    ->timestamp(new DateTime())
    ->send();

HTTP

You can use http method to send HTTP request.

use Kiwilan\Notifier\Notifier;

$notifier = new Notifier();
$http = $notifier->http('https://jsonplaceholder.typicode.com/posts')
    ->method('POST')
    ->send();

$statusCode = $http->getStatusCode();
$body = $http->getResponseBody();
$headers = $http->getResponseHeaders();

Client

HTTP requests use native stream context to send data, curl and guzzle can be used as option (default is stream).

Warning

If you use guzzle, you need to install guzzlehttp/guzzle package.

use Kiwilan\Notifier\Notifier;

$notifier = new Notifier();

$stream = $notifier->client('stream') // default
    ->discord($webhook)
    ->message('Hello, Discord!')
    ->send();

$curl = $notifier->client('curl') // use curl instead of stream
    ->discord($webhook)
    ->message('Hello, Discord!')
    ->send();

$guzzle = $notifier->client('guzzle') // use guzzle instead of stream (need guzzlehttp/guzzle package)
    ->discord($webhook)
    ->message('Hello, Discord!')
    ->send();

To know if request is successful, you can use isSuccess method.

$notifier = new Notifier();

$discord = $notifier->discord($webhook)
    ->message('Hello, Discord!')
    ->send();

if ($discord->isSuccess()) {
    echo 'Message sent!';
}

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

License

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