Home

Welcome to the DiscordPHP wiki!

This wiki is currently a work in progress. Content may be missing or inaccurate. Feel free to join our Discord server to get additional help.

Library Architecture

Promises

As a stateful library there is mass data that needs to be processed. This requires asynchronous execution to prevent data loss and slow downs. This means that promises are required to be used for most methods that would require contact with the Discord servers. Methods are indicated if they return promises. Read up on the usage of promises here, albeit in a JavaScript context, but the concepts carry over to PHP.

Promise Usage

Here is an example of sending a message in a channel, which will return a promise:

echo 'before message'.PHP_EOL;

$channel->sendMessage('my message')->then(function (Message $message) {
    echo 'Message sent!'.PHP_EOL;
    // Message was successfully sent, continue with execution.
})->otherwise(function (\Exception $e) {
    echo 'Error sending message: '.$e->getMessage().PHP_EOL;
    // Message was not sent and an error occured.
});

echo 'after message'.PHP_EOL;

The output from this code would be the following:

before message
after message
Message sent!

Parts

Parts act as data containers and represent Discord objects such as messages, guilds and channels.

Repositories

Repositories contain many parts. An example is a channel repository:

• A guild has one channel repository.
• The channel repository has many channel parts.

Creating and modifying parts must be done through the respective channel. An example is if you are modifying a channel:

1. The channel part is modified.
2. The channel part is saved through the repository, which sends an HTTP request to the Discord to update the object remotely, and stores the part in the local repository.

Depending on the repository endpoints, you may use:

• create() to create a Part locally
• fetch() to fetch a Part from Discord remotely
• save() to save a Part into Discord remotely
• delete() to delete a Part locally & remotely if exists on Discord

Additionally you may:

• fresh() load or refresh a local Part from the Discord remotely
• freshen() load or refresh all local Parts from the Discord remotely

An example of a message part life cycle in a Channel:

1. a Member sends a "hello" Message remotely
2. Your BOT received Event::MESSAGE_CREATE then create() the Message Part
   1. Additionally store it locally to your $channel->messages Repository if you enabled saveMessages option (i.e. Cached)
3. If your BOT has the appropriate permission, you may for intance delete() the Message Part. Your BOT sends a HTTP DELETE request for that message to Discord remotely
4. When done() your BOT deletes the Message Part locally from the $channel->messages Repository

$discord->on(Event::MESSAGE_CREATE, function (Message $message, Discord $discord) { // 2
    if ($message->content == 'hello') { // 1
        $message->delete() // 4
        ->done(function ($deletedMessage) { // 5
            // Message is deleted, $deletedMessage is the data of cached Message
        });
    }
});