Discord API PHP: Lightweight Composer Package for Discord REST API

Discord API PHP is a lightweight Composer package that lets you send messages, rich embeds, and files to Discord channels using bot tokens or webhooks. In other words, instead of setting up a full gateway bot with ReactPHP and websockets, you install one package and start posting to Discord in three lines of code.

Additionally, the package supports Ed25519 interaction signature verification for slash commands, a fluent embed builder, and message management (edit, delete, react). As a result, you can build Discord integrations — from deploy notifications to interactive slash commands — without any external dependencies.

Furthermore, the package is available on Packagist and the source code is on GitHub.

Why a Lightweight Discord API PHP Package?

The dominant Discord API PHP library — DiscordPHP — is a full gateway bot framework. Specifically, it requires ReactPHP, an event loop, websocket connections, and runs exclusively in CLI mode. However, most PHP developers do not need a persistent bot process. Instead, they need to:

  • Send a notification when a deployment finishes.
  • Post an alert when a server metric exceeds a threshold.
  • Forward form submissions to a Discord channel.
  • Handle incoming slash commands from a web endpoint.

Consequently, a full gateway bot is overkill for these use cases. The Discord API PHP package solves this by providing a REST-only wrapper with zero external dependencies — just PHP’s built-in ext-curl, ext-json, and ext-sodium (for interaction verification only).

Installation

Install the package via Composer:

composer require renzojohnson/discord-api

Moreover, no additional configuration is needed. The package auto-loads via PSR-4 and targets Discord REST API v10.

Sending Messages

The most common use case is sending a text message to a Discord channel. Specifically, you create a client instance with your bot token and call sendMessage():

use RenzoJohnson\Discord\Discord;

$discord = new Discord('your-bot-token');
$discord->sendMessage('CHANNEL_ID', 'Hello from PHP!');

In addition, the client handles authentication headers, JSON encoding, and error responses automatically. As a result, you focus on your message content rather than HTTP plumbing.

Rich Embeds

For formatted messages, the Discord API PHP package includes a fluent embed builder. Specifically, you chain methods to construct the embed structure:

use RenzoJohnson\Discord\Message\Embed;

$embed = (new Embed())
    ->title('Deploy Complete')
    ->description('Production updated to v2.4.1')
    ->color(0x00FF00)
    ->field('Environment', 'Production', inline: true)
    ->field('Duration', '43 seconds', inline: true)
    ->footer('CI/CD Pipeline')
    ->timestamp(date('c'));

$discord->sendEmbed('CHANNEL_ID', $embed);

Moreover, the builder uses PHP 8.4 named parameters for optional fields. Consequently, the code reads naturally and you only specify what you need.

Message Management

Beyond sending, the package also handles message editing, deletion, and reactions:

// Edit a message
$discord->editMessage('CHANNEL_ID', 'MESSAGE_ID', 'Updated text');

// Delete a message
$discord->deleteMessage('CHANNEL_ID', 'MESSAGE_ID');

// Add a reaction
$discord->addReaction('CHANNEL_ID', 'MESSAGE_ID', '👍');

As a result, you can build workflows that post a status message, update it as a process runs, and add a checkmark reaction when the task completes.

Webhook Integration

If you do not need a bot token, the package supports Discord webhooks. In particular, webhooks are useful for one-way notifications where you post messages without managing a bot application:

use RenzoJohnson\Discord\Webhook\Webhook;

$webhook = new Webhook('https://discord.com/api/webhooks/ID/TOKEN');
$webhook->send('Build failed on main branch');
$webhook->sendEmbed($embed, content: 'See details below');

Furthermore, webhook messages support the same embed format as bot messages. Consequently, you get rich formatting without creating a bot application in the Discord Developer Portal.

Slash Command Verification

When building slash commands, Discord sends interaction requests to your server. The Discord API PHP package verifies these requests using Ed25519 signature validation — the cryptographic method Discord requires:

use RenzoJohnson\Discord\Webhook\InteractionVerifier;

$body = InteractionVerifier::verify('YOUR_PUBLIC_KEY');
$interaction = json_decode($body, true);

if ($interaction['type'] === 1) {
    InteractionVerifier::respondToPing();
}

Specifically, the verification uses PHP’s ext-sodium extension to validate the X-Signature-Ed25519 header. As a result, you are protected against forged interaction requests without implementing the cryptographic logic yourself.

Discord API PHP vs Other Libraries

There are several Discord API PHP libraries available. However, they serve fundamentally different use cases. The following table highlights the differences:

Feature renzojohnson/discord-api DiscordPHP RestCord
PHP version 8.4+ 8.1+ 7.0+
Dependencies Zero ReactPHP, Evenement Guzzle
API version REST v10 Gateway + REST v10 REST v6
Runs in web requests Yes No (CLI only) Yes
Webhooks Yes No No
Slash commands Ed25519 verification Gateway events No
Embed builder Fluent API Yes No
Persistent connection No (stateless) Yes (websocket) No
Maintained Active Active Abandoned

In particular, if you need to send messages from a web application, handle webhooks, or verify slash commands without a persistent bot process, this package is the right choice. If you need real-time gateway events (member joins, message streams, voice), DiscordPHP is more appropriate.

Error Handling

The package provides specific exception types for common failure scenarios:

use RenzoJohnson\Discord\Exception\AuthenticationException;
use RenzoJohnson\Discord\Exception\RateLimitException;
use RenzoJohnson\Discord\Exception\DiscordException;

try {
    $discord->sendMessage('CHANNEL_ID', 'Hello');
} catch (AuthenticationException $e) {
    // Invalid bot token
} catch (RateLimitException $e) {
    $retryAfter = $e->getRetryAfter(); // seconds to wait
} catch (DiscordException $e) {
    // General API error
}

Specifically, the RateLimitException includes the retry delay from Discord’s response headers. Consequently, you can implement backoff logic without parsing rate limit headers manually.

Common Questions

Do I need a bot token or a webhook?

It depends on your use case. A bot token lets you send messages to any channel, edit messages, add reactions, and retrieve channel data. A webhook URL only posts to one specific channel. In short, use a bot token for interactive features and a webhook for simple notifications.

Can I use this without ext-sodium?

Yes. The ext-sodium extension is only required for slash command interaction verification. If you only send messages or use webhooks, you do not need it. Similarly, the package checks for the extension at runtime and throws a clear error if you try to verify interactions without it.

Does this work in Laravel, Symfony, or WordPress?

Yes. The package is framework-agnostic. Moreover, it works with any PHP project that uses Composer. There are no framework-specific dependencies, service providers, or configuration files required.

Getting Started

The Discord API PHP package gives you a clean, dependency-free way to integrate Discord into any PHP application. Send messages, build rich embeds, handle webhooks, and verify slash commands — all without ReactPHP or external HTTP libraries.

Additionally, check out these other open source contributions and developer tools:

If you need help with the Discord API PHP package or want to report an issue, contact us directly or open an issue on GitHub.