Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kiwilan/php-notifier

PHP Notifier is a package to send mails or notifications for Discord or Slack.
https://github.com/kiwilan/php-notifier

discord mail notification notifier slack webhook

Last synced: 29 days ago
JSON representation

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

Host: GitHub
URL: https://github.com/kiwilan/php-notifier
Owner: kiwilan
License: mit
Created: 2024-02-08T17:57:15.000Z (11 months ago)
Default Branch: main
Last Pushed: 2024-03-16T09:55:26.000Z (10 months ago)
Last Synced: 2024-03-16T11:22:59.981Z (10 months ago)
Topics: discord, mail, notification, notifier, slack, webhook
Language: PHP
Homepage: https://packagist.org/packages/kiwilan/php-notifier
Size: 198 KB
Stars: 0
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

        # **PHP Notifier**

![Banner with british letter box picture in background and Notifier title](https://raw.githubusercontent.com/kiwilan/php-notifier/main/docs/banner.jpg)

[![php][php-version-src]][php-version-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]

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:

```bash

composer require kiwilan/php-notifier

```

> [!NOTE]

> For Laravel, you can use [`kiwilan/notifier-laravel`](https://github.com/kiwilan/notifier-laravel) package.

## Usage

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

-   [Discord](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks): support message and rich embeds webhooks.

-   [Slack](https://api.slack.com/messaging/webhooks): support message and attachments webhooks (without legacy API support).

-   Mail: support message and attachments with [`symfony/mailer`](https://symfony.com/doc/current/mailer.html).

### Discord

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

```php

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](./docs/discord-rich-embed.jpg)

```php

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.

```php

use Kiwilan\Notifier\Notifier;

$notifier = new Notifier();

$mailConfig = $notifier->mail('smtp')

    ->mailer('smtp')

    ->host('mailpit')

    ->port(1025)

    ->username(null)

    ->password(null)

    ->encryption('tls');

```

```php

$mailConfig->from('[email protected]', 'Hello')

    ->to('[email protected]', 'To')

    ->subject('Hello, Mail!')

    ->message('Hello, Mail!')

    ->html('
Hello, Mail!')

    ->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.

```php

use Symfony\Component\Mime\Address;

$mailConfig->from('[email protected]', 'Hello')

    ->to([

      new Address('[email protected]', 'To1'),

      new Address('[email protected]', 'To2'),

    ])

    ->send();

```

You can add attachments with `addAttachment` method.

```php

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

    ->send();

```

### Slack

You can send simple message.

```php

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.

```php

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.

```php

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.

```php

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.

```php

$notifier = new Notifier();

$discord = $notifier->discord($webhook)

    ->message('Hello, Discord!')

    ->send();

if ($discord->isSuccess()) {

    echo 'Message sent!';

}

```

## 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/php-notifier.svg?style=flat-square&colorA=18181B&colorB=777BB4

[version-href]: https://packagist.org/packages/kiwilan/php-notifier

[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/php-notifier.svg?style=flat-square&colorA=18181B&colorB=777BB4

[downloads-href]: https://packagist.org/packages/kiwilan/php-notifier

[license-src]: https://img.shields.io/github/license/kiwilan/php-notifier.svg?style=flat-square&colorA=18181B&colorB=777BB4

[license-href]: https://github.com/kiwilan/php-notifier/blob/main/README.md

[tests-src]: https://img.shields.io/github/actions/workflow/status/kiwilan/php-notifier/run-tests.yml?branch=main&label=tests&style=flat-square&colorA=18181B

[tests-href]: https://github.com/kiwilan/php-notifier/actions/workflows/run-tests.yml

[codecov-src]: https://codecov.io/gh/kiwilan/php-notifier/branch/main/graph/badge.svg?token=n85p0OoBu0

[codecov-href]: https://codecov.io/gh/kiwilan/php-notifier