PHP package that contains a set of methods for simple, direct and elegant communication with Discord channels via Webhooks.
composer require php-channels/discord-webhook
composer update php-channels/discord-webhook
To run unit tests using PHPUnit:
./vendor/bin/phpunit ./tests
To run code static analysis using PHP Stan:
./vendor/bin/phpstan analyse
The main goal of this package is to allow highly customizable messages to be sent to Discord channels in a simple and semantic way via Webhooks. The base payload used to build the code can be accessed at ./documentation/payload.json
.
use PhpChannels\DiscordWebhook\Discord;
...
Discord::message('https://discord.com/api/webhooks/your-webhook-path')
->setUsername('My Bot')
->setContent('Hello World!')
->send();
There are two ways which the destination webhook of the message can be defined. The first is to pass the URL of the webhook as parameter to the message (?string $webhook = null)
method, as in the example below:
use PhpChannels\DiscordWebhook\Discord;
...
Discord::message('https://discord.com/api/webhooks/your-webhook-path');
// ...
Or the webhook can be set via the setWebhook (string $webhook)
method, as in the second example:
use PhpChannels\DiscordWebhook\Discord;
...
Discord::message()
->setWebhook('https://discord.com/api/webhooks/your-webhook-path');
// ...
The name of the sender of the message can be set using the setUsername (string $username)
method, as in the example below:
use PhpChannels\DiscordWebhook\Discord;
...
Discord::message('https://discord.com/api/webhooks/your-webhook-path')
->setUsername('Your Name')
->setContent('Hello World!')
->send();
The avatar of the sender of the message can be set using the setAvatar (string $avatar_url)
method, as in the example below:
use PhpChannels\DiscordWebhook\Discord;
...
Discord::message('https://discord.com/api/webhooks/your-webhook-path')
->setUsername('My Bot')
->setContent('Hello World!')
->setAvatar('https://fake-avatar.com/avatar.png')
->send();
A simple text content of the message can be set using the setContent (string $content)
method, as in the example below:
use PhpChannels\DiscordWebhook\Discord;
...
Discord::message('https://discord.com/api/webhooks/your-webhook-path')
->setContent('A simple text message you want to send!')
->send();
However, the message content can be enriched through the setEmbeds (array $embeds)
method, which takes an array as a parameter, enabling a wide range of customizations, as in the example below:
use PhpChannels\DiscordWebhook\Discord;
...
Discord::message('https://discord.com/api/webhooks/your-webhook-path')
->setEmbeds(['color' => '123456', 'title' => 'Embed content!'])
->send();
Working with embeds content through a single array that fully handles this property is very powerful and can certainly be very useful on many occasions. But it can get really confusing when we are working with a very large array of settings, making it difficult to read and maintain the code. To solve this problem methods for manipulating embeds were added to the package, which are described below.
To handle the embeds[0]['author']
property, the setAuthor (string $name, ?string $url = '', ?string $icon_url = '')
method can be used, as in the examples below:
use PhpChannels\DiscordWebhook\Discord;
...
Discord::message('https://discord.com/api/webhooks/your-webhook-path')
->setAuthor('Author Name')
->send();
// optional param $url
Discord::message('https://discord.com/api/webhooks/your-webhook-path')
->setAuthor('Author Name', 'https://fake-author.com')
->send();
// optional param $icon_url
Discord::message('https://discord.com/api/webhooks/your-webhook-path')
->setAuthor('Author Name', 'https://fake-author.com', 'https://fake-icon.com/icon.png')
->send();
To handle the embeds[0]['title']
property, the setTitle (string $title)
method can be used, as in the examples below:
use PhpChannels\DiscordWebhook\Discord;
...
Discord::message('https://discord.com/api/webhooks/your-webhook-path')
->setTitle('Your title here!')
->send();
To handle the embeds[0]['url']
property, the setUrl (string $url)
method can be used, as in the examples below:
use PhpChannels\DiscordWebhook\Discord;
...
Discord::message('https://discord.com/api/webhooks/your-webhook-path')
->setUrl('https://fake-url.com')
->send();
To handle the embeds[0]['description']
property, the setDescription (string $description)
method can be used, as in the examples below:
use PhpChannels\DiscordWebhook\Discord;
...
Discord::message('https://discord.com/api/webhooks/your-webhook-path')
->setDescription('Your description here!')
->send();
To handle the embeds[0]['color']
property, the setColor (string $color)
method can be used, as in the examples below:
use PhpChannels\DiscordWebhook\Discord;
...
Discord::message('https://discord.com/api/webhooks/your-webhook-path')
->setColor('2450411')
->send();
Note: The color value should be a decimal number. We suggest to use this converter to convert hexadecimal values to decimal.
Or you can use setColor
method passing a string reference color
, as in the example below:
use PhpChannels\DiscordWebhook\Discord;
...
Discord::message('https://discord.com/api/webhooks/your-webhook-path')
->setColor('info')
->send();
The possible color references are:
'info', 'error', 'notice', 'warning', 'success'
.
To add fields to embeds[0]['fields']
property, the setField (string $name, string $value, bool $inline = null)
method can be used, as in the examples below:
use PhpChannels\DiscordWebhook\Discord;
...
Discord::message('https://discord.com/api/webhooks/your-webhook-path')
->setField('Name', 'Value')
->send();
// optional param $inline
Discord::message('https://discord.com/api/webhooks/your-webhook-path')
->setField('Name', 'Value', true)
->send();
// multiple fields
Discord::message('https://discord.com/api/webhooks/your-webhook-path')
->setField('Name 1', 'Value 1')
->setField('Name 2', 'Value 2', true)
->send();
Note: This method can be invoked several times, each time adding a new field to the array.
To add fields to embeds[0]['thumbnail']
property, the setThumbnail (string $thumbnail)
method can be used, as in the examples below:
use PhpChannels\DiscordWebhook\Discord;
...
Discord::message('https://discord.com/api/webhooks/your-webhook-path')
->setThumbnail('https://fake-thumb.com/thumb.png')
->send();
To add fields to embeds[0]['image']
property, the setImage (string $image)
method can be used, as in the examples below:
use PhpChannels\DiscordWebhook\Discord;
...
Discord::message('https://discord.com/api/webhooks/your-webhook-path')
->setImage('https://fake-image.com/image.png')
->send();
To add fields to embeds[0]['footer']
property, the setFooter (string $text, ?string $icon_url = '')
method can be used, as in the examples below:
use PhpChannels\DiscordWebhook\Discord;
...
Discord::message('https://discord.com/api/webhooks/your-webhook-path')
->setFooter('Text to footer here!')
->send();
// optional param $icon_url
Discord::message('https://discord.com/api/webhooks/your-webhook-path')
->setFooter('Text to footer here!', 'https://fake-icon.com/icon.png')
->send();
use PhpChannels\DiscordWebhook\Discord;
...
Discord::message('https://discord.com/api/webhooks/your-webhook-path')
->setUsername('Application Bot')
->setAvatarUrl('https://fake-avatar.com/avatar.png')
->setContent('Content here!')
->setColor('2450411')
->setTitle('Title here!')
->setDescription('Description here!')
->send();
Note: The above example is for documentation purposes only, and that all the methods presented in this file can be combined to send the message as you need.