README

A simple, elegant, and feature-rich Laravel package for sending Discord webhook messages with support for text content, embeds, and rich formatting.

Requirements

• PHP 8.2 or higher
• Laravel 11.x or 12.x

Installation

Install the package via Composer:

composer require larafystudios/discord-webhooks

The package will automatically register its service provider and facade.

Configuration

Publish Configuration (Optional)

If you want to customize the default configuration, publish the config file:

php artisan vendor:publish --tag=discord-webhooks-config

This will create a config/discord-webhooks.php file in your project.

Environment Variables

You can configure the package using environment variables in your .env file:

DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/your-webhook-url
DISCORD_WEBHOOK_USERNAME="Laravel Application"
DISCORD_WEBHOOK_AVATAR_URL=https://example.com/avatar.png

Usage

Basic Text Message

Send a simple text message:

use LarafyStudios\DiscordWebhooks\DiscordWebhook;

DiscordWebhook::make()
    ->setContent('Hello from Laravel!')
    ->send();

Using the Facade

You can also use the provided facade:

use DiscordWebhook;

DiscordWebhook::make()
    ->setContent('Hello from Laravel!')
    ->send();

Custom Webhook URL

Specify a different webhook URL for a specific message:

DiscordWebhook::make('https://discord.com/api/webhooks/your-custom-webhook-url')
    ->setContent('Custom webhook message')
    ->send();

Customize Username and Avatar

Set a custom username and avatar for the webhook:

DiscordWebhook::make()
    ->setUsername('My Custom Bot')
    ->setAvatarUrl('https://example.com/avatar.png')
    ->setContent('Hello with custom identity!')
    ->send();

Rich Embeds

Create beautiful embed messages:

DiscordWebhook::make()
    ->setContent('Check out this embed!')
    ->addEmbed(function ($embed) {
        $embed->setTitle('Embed Title', 'https://example.com')
              ->setDescription('This is a detailed description of the embed content.')
              ->setColor(0x3498db) // Blue color
              ->addField('Field 1', 'Value 1', true)
              ->addField('Field 2', 'Value 2', true)
              ->addField('Field 3', 'This is a longer value that spans multiple lines', false)
              ->setFooter('Footer text', 'https://example.com/footer-icon.png')
              ->setTimestamp();
    })
    ->send();

Embed Only (No Text)

Send an embed without text content:

DiscordWebhook::make()
    ->addEmbed(function ($embed) {
        $embed->setTitle('Notification')
              ->setDescription('This is an embed-only message')
              ->setColor(0x00ff00) // Green
              ->setTimestamp();
    })
    ->send();

Multiple Embeds

Add multiple embeds to a single message:

DiscordWebhook::make()
    ->setContent('Multiple embeds example')
    ->addEmbed(function ($embed) {
        $embed->setTitle('First Embed')
              ->setDescription('This is the first embed')
              ->setColor(0xff0000); // Red
    })
    ->addEmbed(function ($embed) {
        $embed->setTitle('Second Embed')
              ->setDescription('This is the second embed')
              ->setColor(0x0000ff); // Blue
    })
    ->send();

Using Embed Instance Directly

You can also create and pass an embed instance directly:

use LarafyStudios\DiscordWebhooks\DiscordEmbed;

$embed = new DiscordEmbed();
$embed->setTitle('Direct Embed')
      ->setDescription('Created directly')
      ->setColor(0xffff00);

DiscordWebhook::make()
    ->setContent('Using direct embed instance')
    ->addEmbed($embed)
    ->send();

Method Chaining

All methods support fluent chaining:

DiscordWebhook::make()
    ->setUsername('My Bot')
    ->setAvatarUrl('https://example.com/avatar.png')
    ->setContent('Chained methods example')
    ->addEmbed(function ($embed) {
        $embed->setTitle('Title')
              ->setDescription('Description')
              ->setColor(0x3498db)
              ->setAuthor('Author Name', 'https://example.com', 'https://example.com/author.png')
              ->setThumbnail('https://example.com/thumbnail.png')
              ->setImage('https://example.com/image.png')
              ->addField('Inline Field 1', 'Value', true)
              ->addField('Inline Field 2', 'Value', true)
              ->addField('Full Width Field', 'Value', false)
              ->setFooter('Footer', 'https://example.com/footer.png')
              ->setTimestamp();
    })
    ->send();

API Reference

DiscordWebhook Methods

DiscordEmbed Methods

Error Handling

The send() method returns boolean:

• true if the webhook was sent successfully
• false if the webhook failed to send

Errors are automatically logged to Laravel's log system. If the webhook URL is not set, an InvalidArgumentException will be thrown during instantiation.

Examples

Notification System

// In your User model or event listener
use LarafyStudios\DiscordWebhooks\DiscordWebhook;

public function notifyNewUser($user)
{
    DiscordWebhook::make()
        ->setContent("New user registered: {$user->name}")
        ->addEmbed(function ($embed) use ($user) {
            $embed->setTitle('New User Registration')
                  ->setDescription("User {$user->name} ({$user->email}) has registered.")
                  ->setColor(0x00ff00)
                  ->addField('User ID', (string) $user->id, true)
                  ->addField('Email', $user->email, true)
                  ->setTimestamp();
        })
        ->send();
}

Error Reporting

try {
    // Your code here
} catch (\Exception $e) {
    DiscordWebhook::make()
        ->setContent('⚠️ An error occurred in the application')
        ->addEmbed(function ($embed) use ($e) {
            $embed->setTitle('Error Report')
                  ->setDescription($e->getMessage())
                  ->setColor(0xff0000)
                  ->addField('File', $e->getFile(), false)
                  ->addField('Line', (string) $e->getLine(), true)
                  ->setTimestamp();
        })
        ->send();
}

Testing

When testing your application, you may want to prevent actual webhook calls. You can mock the Http facade or use a test webhook URL.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

The MIT License (MIT). Please see License File for more information.

Support

For issues, questions, or contributions, please visit the GitHub repository.

Made with ❤️ by LarafyStudios