README

A better fork of CortexPE's DiscordWebhookAPI virion.

A PocketMine-MP Virion to easily send messages via Discord Webhooks

Usage:

Installation is easy, you may get a compiled phar here or integrate the virion itself into your plugin.

This virion is purely object oriented. So, to use it you'll have to import the Webhook object, the Message object and the optional Embed object (if necessary)

Basic Usage:

Import the classes

You'll need to import these classes in order to easily use it within our code.

<?php

use CortexPE\DiscordWebhookAPI\Message;
use CortexPE\DiscordWebhookAPI\Webhook;
use CortexPE\DiscordWebhookAPI\Embed; // optional

Construct a Discord Webhook object

You'll need the Webhook's URL. For more information regarding how to create Discord webhooks on a Discord Text Channel, Please click here.

$webHook = new Webhook("YOUR WEBHOOK URL");

Construct a Discord Message object

You'll need to create a new Message object for every message that you want to send... You can use different message objects for separate webhooks and this object DOES NOT depend on the Webhook object. It is stand-alone and it would work by itself.

$msg = new Message();
$msg->setUsername("USERNAME"); // optional
$msg->setAvatarURL("https://cortexpe.xyz/utils/kitsu.png"); // optional
$msg->setContent("INSERT TEXT HERE"); // optional. Maximum length is 2000 characters, the limit is set by discord, therefore it is not hardcoded within this API

Sending the message

You can easily send the message to the webhook now! 🎉 This will schedule a new AsyncTask on the Server's AsyncPool to prevent blocking the Main Thread. Do take note however, that you CANNOT send a blank message. doing so will only produce an error received from Discord itself.

$webHook->send($msg);

How easy was that? ^-^ Now for the much more advanced and cooler stuff, Embeds!

Embeds

Before you send the message, you might want to add an embed. A message can have several embeds in it! You only have to construct an embed and use the Message->addEmbed() method to add it into the message object.

$embed = new Embed();

Now, the embed has to have something in it to function properly, so we'll add in a title (optional) and a description (optional). All of the fields are optional, but it should contain ATLEAST one field or it would refuse to add it into the message

$embed->setTitle("Embed Title Here");
$embed->setDescription("A very awesome description");

We can even set a footer text! The text on the bottom part of the embeds...

$embed->setFooter("Erin is kawaii UwU");

Or even, add an icon to the footer...

$embed->setFooter("Erin is kawaii UwU","https://cortexpe.xyz/utils/kitsu.png");

Now that the embed has been constructed and has a valid content, we will have to add it to the Message object... We'll need to use the Message->addEmbed() method for that.

$msg->addEmbed($embed);

You can even enable specific mentions, using the following statement: Message->getAllowedMentions(). The only things you need are discord snowflakes/ids. Be aware, if you call Message->getAllowedMentions() you will get a new instance of the AllowedMentions class, which will allowing all mentions passing through.

$msg->getAllowedMentions()->addUser($userId1, $userId2); // Only the two users corresponding with these two ids will be mentioned
$msg->getAllowedMentions()->addRole($roleId1, $roleId2); // Now also all the people with $roleId1 and $roleId2 will be mentioned

But if you want to suppress every mention out of that message you can use following method.

$msg->getAllowedMentions()->suppressAll();

Components

Message components—we'll call them "components" moving forward—are a framework for adding interactive elements to the messages. They're accessible, customizable, and easy to use. This components are currently W.I.P. which means it's under of development. If you have an issue about executing this code. You can create an issue or pull request for a feature request or subject/proposal to change. To find out about this components, checkout discord docs that can be read here.

To add Components, you must create an instance to class by using:

$component = new Component();

To add a button link text, just add this:

$component->addButtonLink("Click me!", "https://cortexpe.xyz/");

Now add it to our message instance by using:

$msg->addComponent($component);

That's all for the Basic Usage of the API. To learn more, You can explore it by reading the API's source code yourself (the code is simple and explanatory) or by using your favorite IDE to index it yourself. :3

Sample Code used to test this API earlier:

// Construct a discord webhook with its URL
$webHook = new Webhook("YOUR WEBHOOK URL");

// Construct a new Message object
$msg = new Message();

$msg->setUsername("USERNAME");
$msg->setAvatarURL("https://cortexpe.xyz/utils/kitsu.png");
$msg->setContent("INSERT TEXT HERE");
$msg->suppressAll();

// Create an embed object with #FF0000 (RED) as the embed's color and "EMBED 1" as the title
$embed = new Embed();
$embed->setTitle("EMBED 1");
$embed->setColor(0xFF0000);
$msg->addEmbed($embed);

$embed = new Embed();
$embed->setTitle("EMBED 2");
$embed->setColor(0x00FF00);
$embed->setAuthor("AUTHOR", "https://CortexPE.xyz", "https://cortexpe.xyz/utils/kitsu.png");
$embed->setDescription("Lorem ipsum dolor sit amet, consectetur adipiscing elit.");
$msg->addEmbed($embed);

$embed = new Embed();
$embed->setTitle("EMBED 3");
$embed->setColor(0x0000FF);
$embed->addField("FIELD ONE", "Some text here");
$embed->addField("FIELD TWO", "Some text here", true);
$embed->addField("FIELD THREE", "Some text here", true);
$embed->setThumbnail("https://cortexpe.xyz/utils/kitsu.png");
$embed->setImage("https://cortexpe.xyz/utils/kitsu.png");
$embed->setFooter("Erin is kawaii UwU","https://cortexpe.xyz/utils/kitsu.png");
$msg->addEmbed($embed);

$webHook->send($msg);

This API was made with ❤️ by CortexPE, Enjoy!~ :3