README

NotifyCord

A powerful and flexible Discord notification package for Laravel

NotifyCord is a powerful and flexible package for sending Discord notifications from your Laravel application. It provides a clean and simple way to send rich Discord messages through channels and webhooks, and integrates perfectly with Laravel's notification system.

✨ Features

🔌 Seamless integration with Laravel's Notification system
🔗 Support for webhook-based notifications
📋 Rich embed message support (title, description, fields, colors, etc.)
🔘 Discord components support (buttons, action rows)
🔁 Automatic rate limit handling and retries
🧩 Queue-compatible for asynchronous notifications
🛡️ Error handling with detailed exceptions
⚙️ Comprehensive configuration options

📋 Requirements

PHP 8.0 or higher
Laravel 9.0 or higher
GuzzleHTTP 7.0 or higher

💻 Installation

You can install the package via composer:

composer require notifycord/notifycord

The package will automatically register its service provider if you're using Laravel's package auto-discovery.

If you're using Laravel without auto-discovery, add the service provider to your config/app.php:

'providers' => [
    // ...
    NotifyCord\NotifyCord\NotifyCordServiceProvider::class,
],

'aliases' => [
    // ...
    'NotifyCord' => NotifyCord\NotifyCord\Facades\NotifyCord::class,
],

Publishing the Configuration

You can publish the configuration file with:

php artisan vendor:publish --tag="notifycord-config"

This will create a config/notifycord.php configuration file in your application with the following options:

return [
    'default_webhook' => env('DISCORD_WEBHOOK_URL'),
    // 'bot_token' => env('DISCORD_BOT_TOKEN'),  // Not used in webhook-only mode
    'retry_on_rate_limit' => true,
    'retry_on_failure' => true,
    'max_retries' => 3,
    'retry_delay' => 2, // seconds
    'timeout' => 5, // seconds
    'connect_timeout' => 5, // seconds
    'log_errors' => true,
    'log_file' => storage_path('logs/notifycord.log'),  // Custom log file for NotifyCord
    // ...
];

Environment Configuration

Add the following to your .env file:

DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/webhook-id/webhook-token

📖 Usage Guide

🚀 Laravel Notification System Integration

The easiest way to use NotifyCord is through Laravel's notification system. First, create a notification:

php artisan make:notification DiscordNotification

Then, modify the generated notification class to include a toDiscord method:

<?php

namespace App\Notifications;

use Illuminate\Notifications\Notification;
use NotifyCord\NotifyCord\Facades\NotifyCord;

class DiscordNotification extends Notification
{
    protected $message;
    
    public function __construct($message)
    {
        $this->message = $message;
    }
    
    public function via($notifiable)
    {
        return ['discord'];
    }
    
    public function toDiscord($notifiable)
    {
        return NotifyCord::message($this->message)
            ->embed(function ($embed) {
                $embed->title('Important Notification')
                     ->description('This is an important notification from your application')
                     ->color('#ff0000')
                     ->timestamp()
                     ->footer('Your Application', 'https://example.com/logo.png')
                     ->field('Status', 'Active', true)
                     ->field('Environment', app()->environment(), true);
            })
            ->button('View Details', 'primary', 'view_details')
            ->button('Visit Dashboard', 'link', null, 'https://dashboard.example.com');
    }
}

To make your model "notifiable" via Discord, add the routeNotificationForDiscord method to it:

<?php

namespace App\Models;

use Illuminate\Notifications\Notifiable;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use Notifiable;
    
    public function routeNotificationForDiscord()
    {
        // Return your Discord webhook URL
        return 'https://discord.com/api/webhooks/your-webhook-id/your-webhook-token';
    }
}

Then send the notification:

$user->notify(new DiscordNotification('Hello from NotifyCord!'));

🔄 Direct Usage

You can also use NotifyCord directly without a notification class:

use NotifyCord\NotifyCord\Facades\NotifyCord;

// Send to the default webhook configured in .env
NotifyCord::channel()->send(null, new class {
    public function toDiscord() {
        return NotifyCord::message('Direct message using NotifyCord!')
            ->embed(function ($embed) {
                $embed->title('Direct Usage Example')
                     ->description('This message was sent directly without a notification class')
                     ->color('#00ff00');
            });
    }
});

// Or specify a custom webhook URL
$webhookUrl = 'https://discord.com/api/webhooks/custom/webhook';
$notifiable = new class {
    public function routeNotificationForDiscord() {
        return $webhookUrl;
    }
};

NotifyCord::channel()->send($notifiable, new class {
    public function toDiscord() {
        return NotifyCord::message('Custom webhook message');
    }
});

📊 Message Components

🎨 Rich Embeds

Discord embeds provide rich formatting options:

NotifyCord::message('Message with embed')
    ->embed(function ($embed) {
        $embed->title('Embed Title')
             ->description('This is the embed description')
             ->url('https://example.com')
             ->color('#3498db')
             ->timestamp() // Current time
             ->footer('Footer text', 'https://example.com/footer-icon.png')
             ->thumbnail('https://example.com/thumbnail.png')
             ->image('https://example.com/image.png')
             ->author('Author Name', 'https://example.com', 'https://example.com/author-icon.png')
             ->field('Field 1', 'Value 1', true)
             ->field('Field 2', 'Value 2', true)
             ->field('Field 3', 'Value 3', false);
    });

🔘 Interactive Buttons

Add interactive buttons to your messages:

NotifyCord::message('Message with buttons')
    ->button('Primary Button', 'primary', 'primary_button_id')
    ->button('Secondary Button', 'secondary', 'secondary_button_id')
    ->button('Success Button', 'success', 'success_button_id')
    ->button('Danger Button', 'danger', 'danger_button_id')
    ->button('Visit Website', 'link', null, 'https://example.com');

You can also organize buttons into multiple action rows:

NotifyCord::message('Message with multiple action rows')
    ->button('Button 1', 'primary', 'button_1')
    ->button('Button 2', 'secondary', 'button_2')
    ->addActionRow()
    ->button('Button 3', 'success', 'button_3')
    ->button('Button 4', 'danger', 'button_4');

📋 Examples

🚀 Quick and Easy Usage

For the simplest way to send a Discord notification without any boilerplate:

// Send a simple message (uses default webhook from config)
NotifyCord::sendMessage('Server backup completed successfully!');

// Send to a specific webhook
$webhookUrl = 'https://discord.com/api/webhooks/your-webhook-id/your-webhook-token';
NotifyCord::sendMessage('Database migration completed', $webhookUrl);

// Send a rich message with embeds and buttons
NotifyCord::sendMessage('New signup alert', null, function($message) use ($user) {
    $message->embed(function($embed) use ($user) {
        $embed->title('New User Registration')
             ->description('A new user has registered on your platform')
             ->color('#2ecc71')
             ->field('Name', $user->name, true)
             ->field('Email', $user->email, true)
             ->timestamp();
    })
    ->button('View Profile', 'primary', 'view_profile');
});

🌈 Preset Message Styles

NotifyCord offers predefined message styles for common notification types:

// Success message (green)
NotifyCord::success(
    'Backup Completed', 
    'Database backup was successfully created.',
    ['Size' => '25.3 MB', 'Location' => 's3://backups/']
);

// Error message (red)
NotifyCord::error(
    'Process Failed', 
    'Unable to complete the scheduled task.',
    ['Error Code' => 'ERR-501', 'Time' => now()->format('H:i:s')]
);

// Warning message (orange)
NotifyCord::warning(
    'Disk Space Low', 
    'Your server is running low on disk space.',
    ['Used' => '85%', 'Free' => '15 GB']
);

// Info message (blue)
NotifyCord::info(
    'Deployment Started', 
    'A new deployment process has been initiated.',
    ['Branch' => 'main', 'Commit' => 'a7d3h1f']
);

// Server monitoring alert (purple)
NotifyCord::serverAlert(
    'Performance Issue', 
    'High CPU usage detected on web server.',
    [
        'CPU' => '92%',
        'Memory' => '76%',
        'Load Avg' => '4.56, 4.12, 3.79'
    ]
);

// User activity notification (teal)
NotifyCord::userActivity(
    'User Signed Up',
    'A new user has registered on your platform.',
    'John Doe',
    'https://example.com/avatars/johndoe.png',
    [
        'Email' => 'john@example.com',
        'Plan' => 'Premium',
        'Referrer' => 'Google'
    ]
);

📱 Mobile App Notifications

// Mobile app transaction notification
public function sendPurchaseNotification($user, $transaction)
{
    $user->notify(new DiscordNotification("New Purchase: #{$transaction->id}"))
        ->embed(function ($embed) use ($transaction) {
            $embed->title("Purchase: {$transaction->product_name}")
                 ->description("Your purchase has been successfully completed.")
                 ->timestamp()
                 ->color('#2ecc71')
                 ->field('Customer', $transaction->user->name, true)
                 ->field('Price', "{$transaction->amount} {$transaction->currency}", true)
                 ->field('Status', 'Confirmed', true);
        })
        ->button('Order Details', 'primary', 'view_order')
        ->button('Invoice', 'secondary', 'view_invoice')
        ->button('Support', 'link', null, 'https://example.com/support');
}

🚨 System Alerts

// System alert notification
public function sendServerAlert($system, $metrics)
{
    return NotifyCord::message("System Alert: {$system->name}")
        ->embed(function ($embed) use ($system, $metrics) {
            $embed->title("🚨 High CPU Usage")
                 ->description("Server CPU usage has exceeded the configured threshold.")
                 ->color('#e74c3c')
                 ->timestamp()
                 ->field('Server', $system->name, true)
                 ->field('CPU', "{$metrics->cpu_usage}%", true)
                 ->field('Memory', "{$metrics->memory_usage}%", true)
                 ->field('Disk', "{$metrics->disk_usage}%", true)
                 ->footer("Server Monitor", "https://example.com/logo.png");
        });
}

🎨 Advanced Embed Helpers

For specialized embed styles, use the DiscordEmbedHelper class:

use NotifyCord\NotifyCord\Helpers\DiscordEmbedHelper;

// Send an image embed
NotifyCord::sendMessage('', null, function($message) {
    $message->embed(
        DiscordEmbedHelper::imageEmbed(
            'Beautiful Sunset', 
            'https://example.com/images/sunset.jpg',
            '#ff9900'
        )
    );
});

// Send a code snippet
NotifyCord::sendMessage('', null, function($message) {
    $message->embed(
        DiscordEmbedHelper::codeEmbed(
            'Example PHP Code',
            'php',
            '$user = User::find(1);\necho $user->name;',
            '#8e44ad'
        )
    );
});

// Send a progress bar
NotifyCord::sendMessage('', null, function($message) {
    $message->embed(
        DiscordEmbedHelper::progressEmbed(
            'Download Progress',
            75,
            100,
            'Downloading...',
            '#2980b9'
        )
    );
});

// Send a before/after comparison
NotifyCord::sendMessage('', null, function($message) {
    $message->embed(
        DiscordEmbedHelper::comparisonEmbed(
            'Settings Changed',
            [
                'Plan' => ['before' => 'Free', 'after' => 'Premium'],
                'Storage' => ['before' => '5 GB', 'after' => '50 GB'],
                'Users' => ['before' => '3', 'after' => 'Unlimited']
            ],
            '#16a085'
        )
    );
});

🐛 Debugging and Troubleshooting

If your messages are not being sent but no errors appear, you can check the NotifyCord log file:

$logPath = storage_path('logs/notifycord.log');
if (file_exists($logPath)) {
    $logs = file_get_contents($logPath);
    // Display or process logs
}

Common issues and solutions:

Invalid webhook URL: Ensure your webhook URL is correct and the webhook exists in your Discord server.
Rate limiting: Discord may rate limit your requests. The package will retry automatically, but check logs for details.
Network issues: If your server cannot reach Discord's API, check your server's network configuration.
Large messages: Discord has message size limits. Try sending smaller messages or fewer embeds.

You can also enable verbose logging by adding this to your .env file:

NOTIFYCORD_DEBUG=true

🛡️ Security

If you discover any security vulnerabilities, please email contact@example.com instead of using the issue tracker.

📄 License

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

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

notifycord / notifycord

Maintainers

Package info

Statistics

Security