Getting Started

Minimal Setup

Installation:

composer require callisto/callisto-mailer
php artisan vendor:publish --provider="Callisto\Mailer\CallistoMailerBundle" --tag="config"

Publish the migrations and templates:

php artisan vendor:publish --provider="Callisto\Mailer\CallistoMailerBundle" --tag="migrations"
php artisan migrate

First Use Case:

Define a template in the database via php artisan callisto:mailer:create-template (CLI) or manually via the templates table.

Send a test email:

use Callisto\Mailer\Mailer;

$mailer = app(Mailer::class);
$mailer->send([
    'template_id' => 1, // ID of your template
    'recipient' => '[email protected]',
    'variables' => [
        'name' => 'John Doe',
        'unsubscribe_link' => url('/unsubscribe')
    ]
]);

Key Files to Review:
- config/callisto_mailer.php (core configuration like default sender, layouts, and storage paths).
- database/migrations/ (template and layout table structures).
- resources/views/callisto_mailer/ (default Twig layouts; override these for custom designs).

Implementation Patterns

Core Workflows

Template Management:
- Database-Driven: Store templates in templates table with fields like name, subject, html_content, is_active, and layout_id.
- Layouts: Use pre-built layouts (e.g., default.html.twig) or create custom ones in resources/views/callisto_mailer/layouts/.
- Variables Validation: Define expected variables in the template’s variables JSON field (e.g., {"name": "string", "is_active": "boolean"}). The mailer validates these before sending.

Sending Emails:

Basic Send:

$mailer->send([
    'template_id' => $templateId,
    'recipient' => $email,
    'variables' => $data,
    'subject_override' => 'Custom Subject' // Optional
]);

Batch Processing: Use Laravel’s queue system to defer sending:
```
$mailer->queue([
    'template_id' => 1,
    'recipient' => '[email protected]',
    'variables' => [...],
]);
```
Configure the queue in config/callisto_mailer.php under queue_connection.

Localization:
- Store translations for templates in the translations table (linked via template_id and locale).
- Pass the locale in the send method:
```
$mailer->send([
    'template_id' => 1,
    'recipient' => '[email protected]',
    'locale' => 'fr',
    'variables' => [...]
]);
```

Event Listeners:

Extend functionality by listening to events:

// In a service provider
$this->app->booted(function () {
    CallistoMailerEvents::onTemplateSent(function ($event) {
        // Log or process sent emails
    });
});

Testing:

Use the CallistoMailerTestCase trait for unit/feature tests:

use Callisto\Mailer\Testing\CallistoMailerTestCase;

class EmailTest extends CallistoMailerTestCase {
    public function testSendEmail() {
        $this->assertSentTo('[email protected]', 1); // template_id
    }
}

Gotchas and Tips

Pitfalls

Variable Validation Errors:
- If variables in the send method don’t match the template’s expected schema, the mailer throws a ValidationException.
- Fix: Double-check the variables JSON field in the templates table and ensure the sent data matches.
Layout Overrides:
- Custom layouts in resources/views/callisto_mailer/layouts/ must extend the base layout (default.html.twig) or implement the same Twig blocks (body, header, etc.).
- Fix: Use {{ block('body') }} in custom layouts to ensure compatibility.
Queue Configuration:
- If using queues, ensure callisto_mailer.queue_connection is set in the config (e.g., sync, database, or redis).
- Fix: Run php artisan queue:work in development to process queued emails.
Twig Security:
- The mailer escapes variables by default. To disable escaping for specific variables, use the safe filter in Twig:
```
{{ variables.some_html|safe }}
```

Database Locking:

Concurrent template updates can cause race conditions. Use transactions for critical operations:

DB::transaction(function () {
    $template = Template::find($id);
    $template->update(['html_content' => $newHtml]);
});

Debugging Tips

Log Sent Emails: Enable logging in config/callisto_mailer.php:
```
'logging' => [
    'enabled' => true,
    'channel' => 'mailer',
],
```
Check logs in storage/logs/mailer.log.
Template Preview: Use the callisto:mailer:preview CLI command to render templates locally:
```
php artisan callisto:mailer:preview 1 --variables='{"name":"Test"}'
```
Common Errors:
- Template Not Found: Verify template_id exists in the templates table.
- Layout Not Found: Ensure the layout_id in the template matches an entry in the layouts table or a file in resources/views/callisto_mailer/layouts/.

Extension Points

Custom Storage: Override the default template storage (e.g., use S3) by implementing Callisto\Mailer\Storage\TemplateStorageInterface and binding it in the service container.
Dynamic Layouts: Fetch layouts dynamically from an API or database by extending the LayoutResolver service.

Event Extensions: Dispatch custom events by extending the Mailer class and overriding the send method:

class CustomMailer extends Mailer {
    protected function afterSend($event) {
        event(new CustomEmailSent($event->getData()));
    }
}

Testing Helpers: Extend CallistoMailerTestCase to add custom assertions or mocks for your use case.


```markdown
### Configuration Quirks
1. **Default Sender**:
   The `from_email` and `from_name` in `config/callisto_mailer.php` are used if not overridden per email. Set them explicitly in the send method if needed:
   ```php
   $mailer->send([
       'template_id' => 1,
       'from_email' => '[email protected]',
       'from_name' => 'Your App',
       // ...
   ]);

Attachment Handling: The package doesn’t natively support attachments. Use Laravel’s SwiftMailer integration to attach files:
```
$mailer->send([
    'template_id' => 1,
    'attachments' => [
        'path/to/file.pdf' => 'filename.pdf',
    ],
    // ...
]);
```
Ensure config/callisto_mailer.php has 'attachments_enabled' => true.
Rate Limiting: Implement rate limiting via middleware or the queue system to avoid hitting email provider thresholds (e.g., Gmail’s 500 emails/day limit).

Callisto Mailer Laravel Package