​
Laravel Integration Guide

This guide covers the integration of Shoutbox with Laravel, including setup, configuration, and usage patterns.

​
Installation

  1. Install the package via Composer:
composer require shoutboxnet/shoutbox
  1. Add your Shoutbox configuration to config/services.php:
'shoutbox' => [
    'key' => env('SHOUTBOX_API_KEY'),
],
  1. Add your API key to .env:
SHOUTBOX_API_KEY=your-api-key-here

​
Basic Usage

​
Simple Email

use Illuminate\Support\Facades\Mail;

Mail::to('[email protected]')
    ->send(new ShoutboxMail('<h1>Hello</h1><p>This is a test email.</p>'));

​
Advanced Email Options

Mail::to('[email protected]')
    ->from('[email protected]', 'Sender Name')
    ->replyTo('[email protected]')
    ->cc(['[email protected]', '[email protected]'])
    ->send(new ShoutboxMail('<h1>Hello</h1><p>This is a test email.</p>'));

​
Queue Integration

​
Basic Queue Usage

class SendEmailJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function handle()
    {
        Mail::to('[email protected]')
            ->send(new ShoutboxMail('<h1>Hello</h1><p>This is a queued email.</p>'));
    }
}

​
Dispatching the Job

SendEmailJob::dispatch();
// or with delay
SendEmailJob::dispatch()->delay(now()->addMinutes(10));

​
Custom Mailable

​
Creating a Custom Mailable

use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Queue\SerializesModels;

class WelcomeEmail extends Mailable
{
    use Queueable, SerializesModels;

    private $userData;

    public function __construct($userData)
    {
        $this->userData = $userData;
    }

    public function build()
    {
        return $this->view('emails.welcome')
                    ->with([
                        'name' => $this->userData['name'],
                        'email' => $this->userData['email']
                    ]);
    }
}

​
Using Custom Mailable

Mail::to($user->email)->send(new WelcomeEmail($userData));

​
Attachments

​
Adding Attachments

use Illuminate\Support\Facades\Mail;
use Shoutbox\Attachment;

$attachment = new Attachment();
$attachment->filepath = storage_path('app/documents/report.pdf');
$attachment->filename = 'quarterly-report.pdf';
$attachment->contentType = 'application/pdf';

Mail::to('[email protected]')
    ->send(new ShoutboxMail('<h1>Report Attached</h1>', [$attachment]));

​
Error Handling

​
Try-Catch Block

try {
    Mail::to('[email protected]')
        ->send(new ShoutboxMail('<h1>Hello</h1>'));
} catch (\Exception $e) {
    Log::error('Failed to send email: ' . $e->getMessage());
    // Handle the error
}

​
Queue Error Handling

class SendEmailJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public $tries = 3; // Number of retries
    public $backoff = [60, 180, 360]; // Delay between retries in seconds

    public function handle()
    {
        Mail::to('[email protected]')
            ->send(new ShoutboxMail('<h1>Hello</h1>'));
    }

    public function failed(\Exception $e)
    {
        Log::error('Email job failed: ' . $e->getMessage());
        // Notify team or take other actions
    }
}

​
Rate Limiting

​
Basic Rate Limiting

// In a service provider or middleware
RateLimiter::for('sending-emails', function (Request $request) {
    return Limit::perMinute(60); // 60 emails per minute
});

// In your code
RateLimiter::attempt(
    'sending-emails',
    1, // Number of attempts to consume
    function() {
        Mail::to('[email protected]')
            ->send(new ShoutboxMail('<h1>Hello</h1>'));
    }
);

​
Queue Rate Limiting

class SendEmailJob implements ShouldQueue
{
    public $tries = 3;

    public function middleware()
    {
        return [new ThrottlesExceptions(60, 1)]; // 60 attempts per minute
    }

    public function handle()
    {
        Mail::to('[email protected]')
            ->send(new ShoutboxMail('<h1>Hello</h1>'));
    }
}

​
Testing

​
Mail Fake

use Illuminate\Support\Facades\Mail;

class EmailTest extends TestCase
{
    public function test_sending_welcome_email()
    {
        Mail::fake();

        // Trigger email sending
        $this->post('/register', [
            'email' => '[email protected]',
            'name' => 'Test User'
        ]);

        Mail::assertSent(WelcomeEmail::class, function ($mail) {
            return $mail->hasTo('[email protected]');
        });
    }
}

​
Queue Fake

use Illuminate\Support\Facades\Queue;

class EmailTest extends TestCase
{
    public function test_queued_email()
    {
        Queue::fake();

        // Trigger job dispatch
        SendEmailJob::dispatch();

        Queue::assertPushed(SendEmailJob::class);
    }
}

​
Best Practices

  1. Environment Configuration

    • Keep API keys in .env
    • Use different keys for development/production
    • Configure queue settings appropriately

  2. Error Handling

    • Implement proper try-catch blocks
    • Log errors comprehensively
    • Set up proper queue error handling

  3. Performance

    • Use queues for bulk sending
    • Implement rate limiting
    • Monitor queue performance

  4. Testing

    • Write comprehensive tests
    • Use Mail::fake() and Queue::fake()
    • Test error scenarios

  5. Security

    • Validate email addresses
    • Sanitize HTML content
    • Protect API keys

​
Troubleshooting

Common issues and solutions:

  1. Emails not sending

    • Check API key configuration
    • Verify queue worker is running
    • Check for rate limiting

  2. Queue issues

    • Run php artisan queue:restart
    • Check queue configuration
    • Monitor failed_jobs table

  3. Rate limiting

    • Adjust rate limits
    • Implement proper queuing
    • Monitor API usage

  4. Attachment problems

    • Verify file permissions
    • Check file paths
    • Validate file sizes

​
Support

For additional support:

  • Check GitHub issues
  • Contact support team
  • Review API documentation
  • Join developer community