Getting Started

Minimal Steps

Install the package via Composer:
```
composer require twig/inky-extra
```
Register the extension in your Laravel/Symfony Twig environment:
- Laravel (using spatie/laravel-twig): Automatic.
- Manual registration (Symfony/Laravel):
```
$twig->addExtension(new \Twig\Extra\Inky\InkyExtension());
```

Create an Inky template (e.g., resources/views/emails/welcome.inky):

<container>
  <row>
    <columns large="6">
      <h1>Welcome, {{ name }}!</h1>
      <p>Thanks for signing up.</p>
    </columns>
  </row>
</container>

Render the template in a Twig view:

{% set name = "John" %}
{{ include('emails/welcome.inky', {'name': name}) | inky_to_html }}

Test the output in real email clients (Gmail, Outlook, etc.) using tools like Litmus or Email on Acid.

First Use Case: Transactional Email

Replace a manual HTML email template with an Inky template for a password reset email:

<!-- resources/views/emails/reset_password.inky -->
<container>
  <row>
    <columns large="8">
      <h1>Reset Your Password</h1>
      <p>Click the button below to reset your password:</p>
      <button>{{ reset_link }}</button>
      <p>If you didn't request this, ignore this email.</p>
    </columns>
  </row>
</container>

Render it in a Laravel Mailable:

public function build()
{
    return $this->markdown('emails.reset_password')
                ->with([
                    'reset_link' => $this->resetLink,
                ]);
}

Update the Twig template (resources/views/emails/reset_password.blade.php):

{{ include('emails/reset_password.inky', {'reset_link': reset_link}) | inky_to_html }}

Implementation Patterns

Usage Patterns

1. Component-Based Emails

Use Twig macros to create reusable email components (e.g., headers, footers):

{% macro header(title) %}
  <container>
    <row>
      <columns large="12">
        <h1>{{ title }}</h1>
      </columns>
    </row>
  </container>
{% endmacro %}

{% macro footer() %}
  <container>
    <row>
      <columns large="12">
        <p>&copy; {{ year }} Your Company. All rights reserved.</p>
      </columns>
    </row>
  </container>
{% endmacro %}

Include them in your Inky templates:

{{ include('emails/_macros.inky') }}

{{ header('Welcome!') }}
<row>
  <columns large="6">
    <p>Your content here.</p>
  </columns>
</row>
{{ footer() }}

2. Dynamic Content with Twig Logic

Combine Twig logic with Inky templates for conditional content:

{% set user = App\Models\User::find(1) %}
{% set is_premium = user->is_premium %}

{{ include('emails/welcome.inky', {
    'name': user.name,
    'is_premium': is_premium ? 'true' : 'false'
}) | inky_to_html }}

In your Inky template (welcome.inky):

{% if is_premium == 'true' %}
  <row>
    <columns large="12">
      <p>Enjoy your premium features!</p>
    </columns>
  </row>
{% endif %}

3. A/B Testing with Template Variants

Create multiple Inky templates (e.g., welcome_variant_a.inky, welcome_variant_b.inky) and select them dynamically:

{% set variant = 'a' %} {# or fetch from database #}

{% set template = 'emails/welcome_variant_' ~ variant ~ '.inky' %}
{{ include(template, {'name': user.name}) | inky_to_html }}

4. Integration with Laravel Mailables

Extend Laravel’s Mailable class to support Inky templates:

use Twig\Extra\Inky\InkyExtension;

class InkyMailable extends Mailable
{
    public function build()
    {
        return $this->twig('emails.welcome', [
            'name' => $this->name,
        ]);
    }

    protected function getTwig()
    {
        $twig = parent::getTwig();
        $twig->addExtension(new InkyExtension());
        return $twig;
    }
}

Workflows

1. Development Workflow

Design: Create Inky templates in .inky files (e.g., resources/views/emails/).
Develop: Use Twig logic to pass dynamic data to Inky templates.
Test: Render templates locally and preview in real clients using tools like MJML’s preview tool or Litmus.
Deploy: Push templates to production; the inky_to_html filter converts them to HTML on-the-fly.

2. CI/CD Integration

Add a step to test email rendering in your pipeline:

# .github/workflows/test-emails.yml
jobs:
  test-emails:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm install -g mjml
      - run: |
          # Convert Inky to HTML and validate
          php artisan twig:render emails/welcome.inky --data='{"name":"Test"}' > welcome.html
          mjml welcome.html --no-validate

3. Caching Strategy

Cache rendered HTML for high-volume emails (e.g., newsletters):

// In your Mailable or controller
$html = Cache::remember("email-welcome-{$user->id}", now()->addHours(1), function () use ($user) {
    return view('emails.welcome', ['user' => $user])->render();
});

Integration Tips

1. Laravel-Specific Tips

Use spatie/laravel-twig for seamless Twig integration in Laravel.
Leverage Laravel’s Mailable classes to encapsulate email logic and Inky rendering.
Queue emails for high-volume campaigns to avoid timeouts:
```
Mail::to($user)->queue(new InkyMailable($user));
```

2. Symfony-Specific Tips

Register the extension in your Twig configuration:

# config/packages/twig.yaml
twig:
    extensions:
        - Twig\Extra\Inky\InkyExtension

Use Symfony’s Swiftmailer or Mailer component to send emails:

$message = (new \Symfony\Component\Mailer\Email())
    ->to($user->email)
    ->subject('Welcome!')
    ->html($twig->render('emails/welcome.inky', ['name' => $user->name]))
    ->text($twig->render('emails/welcome.txt', ['name' => $user->name]));
$mailer->send($message);

3. Testing Tips

Unit Test Inky Templates: Use PHPUnit to test template rendering:

public function testWelcomeEmail()
{
    $twig = $this->app->make('twig');
    $html = $twig->render('emails/welcome.inky', ['name' => 'John']);
    $this->assertStringContainsString('Welcome, John!', $html);
}

Visual Regression Testing: Use tools like Percy or Applitools to catch rendering issues across email clients.

Gotchas and Tips

Pitfalls

1. Variable Scope Conflicts

Issue: Inky’s {{ }} syntax conflicts with Twig’s variable interpolation. Raw Inky strings must be pre-processed.

Fix: Pass resolved variables as strings to the inky_to_html filter:

{% set name = "John" %}
{{ include('emails/welcome.inky', {'name': name}) | inky_to_html }}

Avoid:

{{ include('emails/welcome.inky') | inky_to_html }} {# This won't work for dynamic content #}

2. Outlook-Specific Quirks

Issue: Outlook may ignore or misrender Inky’s semantic markup (e.g., <container>, <row>).
Fix: Add Outlook-specific hacks or

Inky Extra Laravel Package