Home

Welcome to the DiscordPHP wiki!

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. DiscordPHP uses the ReactPHP/Promise.

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 represent Discord objects such as messages, guilds and channels.

Repositories

Repositories act as data containers consisting of parts. An example is a channel repository:

• A Guild has one ChannelRepository.
• The ChannelRepository has many Channel parts.

Creating and modifying parts must be done through the respective repository. 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 the factory methods:

• create() or new Part($discord, ...) to create a Part locally
• fetch() to fetch a Part from Discord (GET request to Discord API)
• save() to save a Part into Discord (POST request to Discord API)
• delete() to delete a Part locally & on Discord if exists (DELETE request to Discord API)

Additionally you may:

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

An example of a Message Part life cycle in a Channel:

1. a Member sends a "hello" Message
2. BOT received Event::MESSAGE_CREATE then create() the $message Part
   1. Additionally if saveMessages option is enabled, cache locally into $channel->messages Repository
3. If BOT has the appropriate permission, for instance delete($message), BOT will send a DELETE HTTP request
4. Once done(), the $message is unset() from $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
        });
    }
});