Getting Started

Minimal Steps

Installation:
```
composer require chris13/mail-bundle "~1"
```
Ensure Composer is installed globally.
Bundle Registration: Add the bundle to app/AppKernel.php under registerBundles():
```
new Chris\Bundle\MailBundle\MailBundle(),
```

Configuration: Add SendGrid (or other provider) settings to config.yml:

mail:
    sendgrid:
        user: your_sendgrid_user
        password: your_sendgrid_pass
        options:
            turn_off_ssl_verification: true

First Use Case: Inject the mailer service and send a basic email:

$mailer = $this->get('mail_bundle.send_grid_mailer');
$mailer->send(
    'from@example.com',
    ['to@example.com'],
    'Subject',
    'Plain text body',
    'HTML body'
);

Where to Look First

README: Focus on the Usage section for SendGrid-specific examples.
Service Container: Check app/config/config.yml for provider-specific configurations.
Service IDs: Use debug:container to locate the correct mailer service ID (e.g., mail_bundle.send_grid_mailer).

Implementation Patterns

Core Workflows

Sending Emails: Use the injected mailer service to send emails with minimal boilerplate:
```
$mailer->send($from, $to, $subject, $textBody, $htmlBody, $categories = []);
```
- Categories: Pass an array of strings to tag emails (useful for SendGrid categorization).
Provider-Specific Logic: The bundle abstracts provider-specific details (e.g., SendGrid API calls). Extend or override services if needed (see Gotchas).
Integration with Laravel’s Mailer: If using Laravel’s built-in Mail facade, wrap the bundle’s mailer in a custom facade or service for consistency:
```
// In a service provider
$this->app->bind('mailer', function () {
    return $this->app->get('mail_bundle.send_grid_mailer');
});
```

Testing: Mock the mailer service in tests:

$this->app->instance('mail_bundle.send_grid_mailer', $mockMailer);

Advanced Patterns

Dynamic Configuration: Load provider credentials from environment variables or a secure config file:

mail:
    sendgrid:
        user: "%env(SENDGRID_USER)%"
        password: "%env(SENDGRID_PASSWORD)%"

Event Listeners: Attach listeners to the mailer service for logging, analytics, or transformations:
```
$mailer->addListener(function ($event) {
    // Pre-process email data
});
```
Batch Processing: Queue emails using Laravel’s queue system by wrapping the mailer call:
```
Mail::queue(function ($message) use ($mailer) {
    $mailer->send(...);
});
```

Gotchas and Tips

Pitfalls

Deprecated Kernel: The bundle assumes Symfony’s AppKernel.php. For Laravel, register the bundle in config/app.php under providers:
```
Chris\Bundle\MailBundle\MailBundle::class,
```
Fix: Override the bundle’s Bootstrap class if needed.
Service ID Mismatch: The bundle uses Symfony-style service IDs (e.g., mail_bundle.send_grid_mailer). Laravel’s container may not autowire these directly. Fix: Use app('mail_bundle.send_grid_mailer') or alias the service:
```
'aliases' => [
    'mailer' => 'mail_bundle.send_grid_mailer',
],
```
SSL Verification: Disabling SSL verification (turn_off_ssl_verification) is enabled by default. Re-enable for production:
```
options:
    turn_off_ssl_verification: false
```
No Laravel Mail Integration: The bundle doesn’t integrate with Laravel’s Mail facade or Mailable classes. Manually pass raw data to the send() method.
Outdated Dependencies: The package is unmaintained (last release: 2018). Test thoroughly or fork for updates.

Debugging Tips

Check Service Existence: Run php artisan config:dump and php artisan container:debug to verify the mailer service is registered.

Log Provider Errors: Wrap send() calls in a try-catch to log SendGrid API responses:

try {
    $mailer->send(...);
} catch (\Exception $e) {
    \Log::error('Mail send failed: ' . $e->getMessage());
}

Verify Credentials: Use SendGrid’s API keys instead of username/password if available (the bundle doesn’t support this natively).

Extension Points

Custom Mailer: Extend the base mailer class (Chris\Bundle\MailBundle\Mailer\MailerInterface) to add features like attachments or templates:

class CustomMailer implements MailerInterface {
    public function sendWithAttachment($from, $to, $subject, $text, $html, $attachmentPath) {
        // Custom logic
    }
}

Override Services: Replace the default SendGrid mailer in config/services.yml:

services:
    mail_bundle.send_grid_mailer:
        class: App\Services\CustomSendGridMailer
        arguments: [...]

Add New Providers: Implement a new mailer class and register it as a service. Follow the existing SendGridMailer as a reference.

Configuration Quirks

YAML Structure: The config.yml expects nested mail > sendgrid keys. Misplaced keys will cause errors. Example:
```
# Incorrect (will fail)
sendgrid:
    user: ...

# Correct
mail:
    sendgrid:
        user: ...
```
Options Array: The options key must be an array. Passing a string or other type will break the mailer.

Mail Bundle Laravel Package