DiscordEventsHandler

DiscordEventsHandler is a PHP event handling library designed specifically for Discord bots, based on the DiscordPHP library.

Presentation

It offers an intuitive way to listen and react to Discord events with enhanced control through prioritized listeners and cancellable events.

By wrapping each event into a dedicated class, this system provides clear and precise event data, eliminating the need to constantly consult Discord PHP documentation or closure signatures.

Features

Project TODO Progress

• Clean and Expressive API
• Listeners Priority System
• Event Traits Implementation (categorize events: MessageEvent, ChannelEvent, etc.)
• Cancellable Events Handling
• Typed Event objects, Additional Attributes and Methods

Clean and Expressive API

Compared to vanilla Discord PHP event listening, your code becomes cleaner and easier to understand.

Discord PHP vs DiscordEventsHandler

// Discord PHP way:
$discord->on(Event::MESSAGE_CREATE, function (Message $message, Discord $discord) {
    echo "{$message->author->username}: {$message->content}";
});

// DiscordEventsHandler way:
$listenersHandler->addListener(MessageCreateEvent::class, new EventListener(function(MessageCreateEvent $event) {
    echo "{$event->getMessage()->author->username}: {$event->getMessage()->content}";
}, ListenerPriority::HIGH));

Listeners Priority System

Register listeners with predefined priority levels (LOWEST, LOW, NORMAL, HIGH, HIGHEST) or any custom priority between 0 and 200.

Listeners are executed from highest to lowest priority. For example:

$eventsHandler->addListener(InitEvent::class, new EventListener(fn($e) => print("First\n"), ListenerPriority::HIGHEST));
$eventsHandler->addListener(InitEvent::class, new EventListener(fn($e) => print("Second\n"), ListenerPriority::NORMAL));
$eventsHandler->addListener(InitEvent::class, new EventListener(fn($e) => print("Last\n"), ListenerPriority::LOWEST));

Output

First
Second
Last

Cancellable Events Handling

If an event supports cancellation, listeners can stop the event propagation, meaning that other listeners will not receive this event.

⚠️ Note: cancelling an event does not truly cancel it at the Discord API level.

However, for specific events like MessageCreateEvent, we can take actions such as deleting the message to simulate a cancellation effect.

Typed Event objects, Additional Attributes and Methods

Each event is represented by its own class containing all related data, making event handling clearer and more maintainable.

No more guessing the closure parameters or looking up event structures in external docs.

Installation

Creating a Discord Bot Application

To create a Discord bot application, follow the official guide provided by Discord:
How to Create a Discord Application

This guide will walk you through the process of setting up your bot, including creating an application, adding a bot user, and obtaining your bot token.

Clone the project and run the bot

Clone the repository:

git clone https://github.com/SwouitAzia/DiscordEventsHandler.git
cd DiscordEventsHandler
composer install

Create a .env file in the project root and add your Discord bot token (see .env.example file).

Run your bot:

php src/DiscordEventsHandler/Loader.php

Credits and License

Credits

This project draws inspiration from PocketMine, which offers an intuitive event system with prioritized listeners and cancellable events.

Its approach to event handling has been adapted to fit the nature of Discord bots, aiming to provide a similar level of clarity and control.

License

This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0).

CC BY-NC 4.0