Email Templates

https://github.com/visualbuilder/email-templates
Admin
Email Templates is a Filament 3.0 plugin that provides a content management system for creating,...
Tokens:14,138
Snippets:77
Trust Score:5.7
License:GPL-3.0
Update:11 months ago
Show doc for...
Tokens:
Raw
### Install Filament Email Templates Package

Source: https://context7.com/visualbuilder/email-templates/llms.txt

Installs the Filament Email Templates package using Composer. This is the first step to integrate the email template system into your Laravel application.

```bash
composer require visualbuilder/email-templates
```

--------------------------------

### Run Filament Email Templates Installation Command

Source: https://context7.com/visualbuilder/email-templates/llms.txt

Executes the installation command for Filament Email Templates. This command publishes configuration files, migrations, assets, and optionally seeds default templates and runs migrations.

```bash
php artisan filament-email-templates:install --seed
```

--------------------------------

### Install Filament Email Templates Package

Source: https://github.com/visualbuilder/email-templates/blob/3.x/README.md

Installs the email templates package via Composer and publishes its assets using a Laravel Artisan command. The `--seed` option populates default templates.

```bash
composer require visualbuilder/email-templates

php artisan filament-email-templates:install --seed
```

--------------------------------

### Creating a Custom Token Helper in PHP

Source: https://context7.com/visualbuilder/email-templates/llms.txt

Illustrates how to extend the `DefaultTokenHelper` to create a custom token replacement logic. By overriding the `replaceTokens` method, developers can add their own token replacements before or after the default processing. The example shows adding a custom `##discount_code##` token. This custom helper must be registered in the `config/filament-email-templates.php` configuration file.

```php
// app/Helpers/MyTokenHelper.php
namespace App\Helpers;

use Visualbuilder\EmailTemplates\DefaultTokenHelper;

class MyTokenHelper extends DefaultTokenHelper
{
    public function replaceTokens(string $content, $models): string
    {
        // Call parent for standard replacements
        $content = parent::replaceTokens($content, $models);

        // Add custom token logic
        if (isset($models->discount_code)) {
            $content = str_replace('##discount_code##', $models->discount_code, $content);
        }

        return $content;
    }
}

// Register in config/filament-email-templates.php
'tokenHelperClass' => App\Helpers\MyTokenHelper::class,
```

--------------------------------

### Basic Mailable Class with Single Model

Source: https://context7.com/visualbuilder/email-templates/llms.txt

Provides an example of a basic Laravel Mailable class designed for sending emails using Visualbuilder's templating system. This class, `UserWelcomeEmail`, uses the `BuildGenericEmail` trait and specifies a template name (`user-welcome`). It accepts a `User` model in its constructor, sets the recipient's email address, and makes the `user` model available for token replacement in the template.

```php
// app/Mail/Visualbuilder/EmailTemplates/UserWelcomeEmail.php
namespace App\Mail\Visualbuilder\EmailTemplates;

use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Queue\SerializesModels;
use Visualbuilder\EmailTemplates\Traits\BuildGenericEmail;

class UserWelcomeEmail extends Mailable
{
    use Queueable, SerializesModels, BuildGenericEmail;

    public string $template = 'user-welcome';
    public string $sendTo;
    public $user;

    public function __construct($user)
    {
        $this->user = $user;
        $this->sendTo = $user->email;
    }
}

// Send the email
use App\Mail\Visualbuilder\EmailTemplates\UserWelcomeEmail;
use Illuminate\Support\Facades\Mail;

$user = User::find(1);
Mail::send(new UserWelcomeEmail($user));
```

--------------------------------

### Create a New Generic Email Mailable Class (PHP)

Source: https://github.com/visualbuilder/email-templates/blob/3.x/README.md

Example of a new Mailable class intended for use with Visual Builder's email templates. It utilizes the BuildGenericEmail trait and requires setting the 'template' property to the email template key.

```php
<?php

namespace AppMail;

use IlluminateBusQueueable;
use IlluminateMailMailable;
use IlluminateQueueSerializesModels;
use VisualbuilderEmailTemplatesTraitsBuildGenericEmail;

class MyFunkyNewEmail extends Mailable
{
    use Queueable, SerializesModels, BuildGenericEmail;

    public string $template = 'email-template-key';  //Change this to the key of the email template content to load
    public string $sendTo;

    /**
     * Create a new message instance.
     *
     * @return void
     */
    public function __construct($user) {
        $this->sendTo = $user;
    }
}
```

--------------------------------

### Conditionally Enable Navigation using a Closure

Source: https://github.com/visualbuilder/email-templates/blob/3.x/README.md

This example demonstrates how to enable navigation for email templates dynamically based on user permissions using a closure. The navigation is only enabled if the authenticated user has the 'view_email_templates' or 'view_any_email_templates' capability. This is typically implemented within the `AdminPanelProvider.php` file.

```php
// AdminPanelProvider.php
    ->plugins([
// ...
        EmailTemplatesPlugin::make()
                ->enableNavigation(
                    fn () => auth()->user()->can('view_email_templates') || auth()->user()->can('view_any_email_templates)'),
               ),
    ])

```

--------------------------------

### Creating Custom Model Accessors for Email Tokens

Source: https://context7.com/visualbuilder/email-templates/llms.txt

Explains how to define custom model accessors in Laravel to be used as tokens within email templates. This allows for dynamic data retrieval and formatting from model attributes. Examples show both traditional and modern (Laravel 9+) accessor syntax. The custom accessor `fullName` can then be used in templates as `##user.full_name##`.

```php
// app/Models/User.php
class User extends Authenticatable
{
    // Method 1: Traditional accessor
    public function getFullNameAttribute()
    {
        return $this->firstname . ' ' . $this->lastname;
    }

    // Method 2: Modern accessor (Laravel 9+)
    protected function fullName(): Attribute
    {
        return Attribute::make(
            get: fn () => $this->firstname . ' ' . $this->lastname,
        );
    }
}

// Use in template: Hello ##user.full_name##!
```

--------------------------------

### Configure Basic Filament Email Templates Settings

Source: https://context7.com/visualbuilder/email-templates/llms.txt

Sets up basic configuration options for the Filament Email Templates package. This includes table names, mailable directory, navigation settings, logo details, and customer service information.

```php
// config/filament-email-templates.php
return [
    'table_name' => 'vb_email_templates',
    'theme_table_name' => 'vb_email_templates_themes',
    'mailable_directory' => 'Mail/Visualbuilder/EmailTemplates',

    'navigation' => [
        'enabled' => true,
        'templates' => [
            'sort' => 10,
            'label' => 'Email Templates',
            'icon' => 'heroicon-o-envelope',
            'group' => 'Content',
        ],
        'themes' => [
            'sort' => 20,
            'label' => 'Email Template Themes',
            'icon' => 'heroicon-o-paint-brush',
            'group' => 'Content',
        ],
    ],

    'logo' => 'media/email-templates/logo.png',
    'logo_width' => '500',
    'logo_height' => '126',
    'content_width' => '600',

    'customer-services' => [
        'email' => 'support@yourcompany.com',
        'phone' => '+441273 455702'
    ],

    'links' => [
        ['name' => 'Website', 'url' => 'https://yourwebsite.com', 'title' => 'Goto website'],
        ['name' => 'Privacy Policy', 'url' => 'https://yourwebsite.com/privacy-policy', 'title' => 'View Privacy Policy'],
    ],
];
```

--------------------------------

### Mailable Class with Multiple Models

Source: https://context7.com/visualbuilder/email-templates/llms.txt

Demonstrates creating a Mailable class, `BookingConfirmationEmail`, that includes multiple models (`User` and `Booking`) to be used for token replacement. The constructor accepts instances of both models and assigns them to public properties. The `sendTo` property is also set using the `User` model's email. Tokens like `##user.name##` and `##booking.date##` can then be utilized within the specified template (`booking-confirmation`).

```php
// app/Mail/Visualbuilder/EmailTemplates/OrderConfirmationEmail.php
namespace App\Mail\Visualbuilder\EmailTemplates;

use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Queue\SerializesModels;
use Visualbuilder\EmailTemplates\Traits\BuildGenericEmail;
use App\Models\User;
use App\Models\Order;
use App\Models\Booking;

class BookingConfirmationEmail extends Mailable
{
    use Queueable, SerializesModels, BuildGenericEmail;

    public string $template = 'booking-confirmation';
    public string $sendTo;
    public User $user;
    public Booking $booking;

    public function __construct(User $user, Booking $booking)
    {
        $this->user = $user;
        $this->booking = $booking;
        $this->sendTo = $user->email;
    }
}

// Use tokens in template: ##user.name##, ##booking.date##, ##booking.location##
```

--------------------------------

### Run Pest Tests (Bash)

Source: https://github.com/visualbuilder/email-templates/blob/3.x/README.md

This command executes all tests defined in the project using the Pest testing framework. It's a standard way to ensure code quality and functionality.

```bash
./vendor/bin/pest      

```

--------------------------------

### Mailable with PHP 8 Constructor Property Promotion

Source: https://context7.com/visualbuilder/email-templates/llms.txt

Shows how to utilize PHP 8's constructor property promotion for concisely defining Mailable classes. The `SalesOrderEmail` class demonstrates this feature by declaring public properties directly in the constructor signature (`public User $user`, `public Order $order`, `public Invoice $invoice`). This reduces boilerplate code. An attachment is generated from the `Invoice` model and the recipient email is set.

```php
namespace App\Mail\Visualbuilder\EmailTemplates;

use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Queue\SerializesModels;
use Visualbuilder\EmailTemplates\Traits\BuildGenericEmail;
use App\Models\User;
use App\Models\Order;
use App\Models\Invoice;

class SalesOrderEmail extends Mailable
{
    use Queueable, SerializesModels, BuildGenericEmail;

    public string $template = 'sales-order';
    public string $sendTo;
    public $attachment;

    public function __construct(
        public User $user,
        public Order $order,
        public Invoice $invoice
    )
    {
        $this->attachment = $invoice->getPdf();
        $this->sendTo = $user->email;
    }
}

// Tokens available: ##user.name##, ##order.reference##, ##invoice.number##
```

--------------------------------

### Implement Email Verification

Source: https://context7.com/visualbuilder/email-templates/llms.txt

This snippet demonstrates how to implement email verification for users, requiring the User model to implement 'MustVerifyEmail'. It also shows how to override the default verification email using a custom service provider and how to manually send a verification notification with a temporary signed route.

```php
// Requires User model to implement MustVerifyEmail
use Illuminate\Contracts\Auth\MustVerifyEmail;

class User extends Authenticatable implements MustVerifyEmail
{
    // ...
}

// Register the auth service provider to override default verification email
// config/app.php or AppServiceProvider
Visualbuilder\EmailTemplates\EmailTemplatesAuthServiceProvider::class

// Manual verification notification
use Illuminate\Support\Facades\URL;

$notification = new \Filament\Notifications\Auth\VerifyEmail();
$notification->url = URL::temporarySignedRoute(
    'filament.admin.auth.email-verification.verify',
    now()->addMinutes(60),
    [
        'id' => $user->getKey(),
        'hash' => sha1($user->getEmailForVerification()),
    ]
);

$user->notify($notification);

// Template key: 'user-verify-email'
// Tokens: ##user.name##, ##verificationUrl##
```

--------------------------------

### Using Config Value Tokens in HTML Emails

Source: https://context7.com/visualbuilder/email-templates/llms.txt

Demonstrates how to use placeholder tokens within HTML email templates to dynamically insert configuration values. These tokens are automatically replaced with corresponding values from configuration files, provided they are whitelisted in the `config_keys` array of `config/filament-email-templates.php`.

```html
// In email template HTML editor:
// Welcome to ##config.app.name##!
// Visit us at ##config.app.url##
// Contact support: ##config.email-templates.customer-services##
```

```php
// Values are automatically replaced from config files
// Must be whitelisted in config/filament-email-templates.php config_keys array
```

--------------------------------

### TokenHelper Facade

Source: https://context7.com/visualbuilder/email-templates/llms.txt

The TokenHelper facade provides a utility to replace placeholders within email content. It takes the content string and a models object containing the data to substitute for the placeholders like '##user.name##' and '##config.app.name##'.

```php
use Visualbuilder\EmailTemplates\Facades\TokenHelper;

$content = "Hello ##user.name##, welcome to ##config.app.name##!";
$models = (object)[
    'user' => $user,
];

$replaced = TokenHelper::replace($content, $models);
// Output: "Hello John Doe, welcome to My Application!"
```

--------------------------------

### Configure Token Replacements for Email Templates

Source: https://context7.com/visualbuilder/email-templates/llms.txt

Defines known tokens and configuration keys that can be used for dynamic content replacement within email templates. This allows for easy injection of data from models and application configuration.

```php
// config/filament-email-templates.php
'known_tokens' => [
    'tokenUrl',
    'verificationUrl',
    'message'
],

'config_keys' => [
    'app.name',
    'app.url',
    'email-templates.customer-services'
],
```

--------------------------------

### Test and Preview Email Templates in Development (PHP)

Source: https://context7.com/visualbuilder/email-templates/llms.txt

Provides methods to preview email content and send test emails during development without actual delivery. It involves retrieving template data, rendering the view, and optionally sending a test email to a specific address. This aids in debugging and verifying template accuracy.

```php
use Visualbuilder\EmailTemplates\Models\EmailTemplate;
use App\Models\User;

// Preview email without sending
$template = EmailTemplate::findEmailByKey('user-welcome', 'en_GB');
$previewData = $template->getEmailPreviewData();

// Render view
$html = view($template->view_path, ['data' => $previewData])->render();
echo $html;

// Send test email
use App\Mail\Visualbuilder\EmailTemplates\UserWelcomeEmail;

$testUser = User::first();
Mail::to('developer@test.com')->send(new UserWelcomeEmail($testUser));
```

--------------------------------

### Create Email Template Theme (PHP)

Source: https://context7.com/visualbuilder/email-templates/llms.txt

Creates a new theme for email templates, defining specific color schemes for various email components like headers, body, buttons, and footers. Allows customization of the visual appearance of emails.

```php
use Visualbuilder\EmailTemplates\Models\EmailTemplateTheme;

$theme = EmailTemplateTheme::create([
    'name' => 'Dark Mode',
    'colours' => [
        'header_bg' => '#1a202c',
        'body_bg' => '#2d3748',
        'text_color' => '#f7fafc',
        'button_bg' => '#4299e1',
        'button_text' => '#ffffff',
        'footer_bg' => '#1a202c',
    ],
    'is_default' => false,
]);

```

--------------------------------

### EmailTemplate Model Methods

Source: https://context7.com/visualbuilder/email-templates/llms.txt

This API reference details methods available on the EmailTemplate model for managing email templates. It covers finding templates by key, clearing cache, generating previews, checking mailable class existence, and accessing related data like themes and logo URLs.

```php
use Visualbuilder\EmailTemplates\Models\EmailTemplate;

// Find template by key with caching
$template = EmailTemplate::findEmailByKey('user-welcome', 'en_GB');

// Clear specific template cache
EmailTemplate::clearEmailTemplateCache('user-welcome', 'en_GB');

// Get base64 preview for iframe
$base64Content = $template->getBase64EmailPreviewData();

// Get preview data array
$previewData = $template->getEmailPreviewData();
// Returns: ['user' => User, 'content' => string, 'subject' => string, 'theme' => array]

// Check if mailable class exists
$exists = $template->mailable_exists; // boolean

// Get mailable class name
$className = $template->getMailableClass(); // "App\Mail\Visualbuilder\EmailTemplates\UserWelcome"

// Access relationships
$theme = $template->theme; // EmailTemplateTheme instance
$logoUrl = $template->logo; // Full URL to logo asset
$viewPath = $template->view_path; // "vb-email-templates::email.default"
```

--------------------------------

### Queue Email Sending with Laravel Mail Facade (PHP)

Source: https://context7.com/visualbuilder/email-templates/llms.txt

Enables asynchronous email delivery using Laravel's Mail facade and queue system. Emails can be queued for default processing, scheduled for a specific time using `Mail::later`, or dispatched to a dedicated queue with custom delays. This improves application responsiveness by offloading email tasks.

```php
use App\Mail\Visualbuilder\EmailTemplates\UserWelcomeEmail;
use Illuminate\Support\Facades\Mail;

// Queue with default queue
Mail::queue(new UserWelcomeEmail($user));

// Queue with specific queue and delay
Mail::later(now()->addMinutes(5), new UserWelcomeEmail($user));

// Mailable already uses Queueable trait
$mailable = new UserWelcomeEmail($user);
$mailable->onQueue('emails');
$mailable->delay(now()->addMinutes(10));
Mail::queue($mailable);
```

--------------------------------

### Create Email Template (PHP)

Source: https://context7.com/visualbuilder/email-templates/llms.txt

Creates a new email template entry in the database, specifying its key, language, sender details, subject line, content (including HTML and tokens), CC/BCC recipients, logo, and associated theme. This allows for dynamic email content generation.

```php
use Visualbuilder\EmailTemplates\Models\EmailTemplate;
use Visualbuilder\EmailTemplates\Models\EmailTemplateTheme;

$theme = EmailTemplateTheme::where('is_default', true)->first();

$template = EmailTemplate::create([
    'key' => 'order-confirmation',
    'name' => 'Order Confirmation Email',
    'language' => 'en_GB',
    'view' => 'default',
    'from' => [
        'email' => 'orders@company.com',
        'name' => 'Company Orders',
    ],
    'subject' => 'Order Confirmation ##order.reference##',
    'title' => 'Thank You For Your Order!',
    'preheader' => 'Your order has been confirmed',
    'content' => '<p>Hello ##user.name##,</p><p>Your order ##order.reference## has been confirmed.</p>',
    'cc' => ['manager@company.com'],
    'bcc' => ['archive@company.com'],
    'logo' => 'https://yourwebsite.com/logo.png',
    'vb_email_templates_themes_id' => $theme->id,
]);

```

--------------------------------

### Retrieve Email Template by Key (PHP)

Source: https://context7.com/visualbuilder/email-templates/llms.txt

Fetches an email template from the database using its unique key and language. The result is cached for 60 minutes. If a specific language is not found, it falls back to the default locale. Accesses properties like subject, sender details, content, and view path.

```php
use Visualbuilder\EmailTemplates\Models\EmailTemplate;

// Get template by key and language (cached for 60 minutes)
$template = EmailTemplate::findEmailByKey('user-welcome', 'en_GB');

// Falls back to default locale if language not found
$template = EmailTemplate::findEmailByKey('user-welcome', 'es');

// Access template properties
echo $template->subject;      // "Welcome to Our Platform!"
echo $template->from['email']; // "support@company.com"
echo $template->from['name'];  // "Company Support"
echo $template->content;       // HTML content with tokens
echo $template->view_path;     // "vb-email-templates::email.default"

```

--------------------------------

### Default Token Replacement Implementation

Source: https://context7.com/visualbuilder/email-templates/llms.txt

Details the `DefaultTokenHelper` class, which implements the `TokenReplacementInterface`. This class handles the core logic for replacing various types of tokens in email content, including singular tokens, configuration tokens, model attributes, and button elements. It orchestrates the replacement process by calling specific methods for each token type.

```php
// src/DefaultTokenHelper.php
use Visualbuilder\EmailTemplates\Contracts\TokenReplacementInterface;

class DefaultTokenHelper implements TokenReplacementInterface
{
    public function replaceTokens(string $content, $models): string
    {
        // Replace ##tokenUrl##, ##verificationUrl##, ##message##
        $content = $this->replaceSingularTokens($models, $content);

        // Replace ##config.app.name##, ##config.app.url##
        $content = $this->replaceConfigTokens($models, $content);

        // Replace ##user.name##, ##order.id##, ##booking.date##
        $content = $this->replaceModelTokens($models, $content);

        // Replace {{button url='...' title='...'}}
        return $this->replaceButtonTokens($models, $content);
    }
}
```

--------------------------------

### Create Mailable with Attachment (PHP)

Source: https://context7.com/visualbuilder/email-templates/llms.txt

Defines an `InvoiceEmail` Mailable class that includes an attachment. The `BuildGenericEmail` trait automatically handles the attachment based on the provided filepath, filename, and mime type.

```php
namespace App\Mail\Visualbuilder\EmailTemplates;

use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Queue\SerializesModels;
use Visualbuilder\EmailTemplates\Traits\BuildGenericEmail;

class InvoiceEmail extends Mailable
{
    use Queueable, SerializesModels, BuildGenericEmail;

    public string $template = 'invoice-email';
    public string $sendTo;
    public $attachment;
    public $user;
    public $invoice;

    public function __construct($user, $invoice)
    {
        $this->user = $user;
        $this->invoice = $invoice;
        $this->sendTo = $user->email;

        // Attachment must have filepath, filename, and filetype/mime_type properties
        $this->attachment = (object)[
            'filepath' => storage_path("invoices/{$invoice->id}.pdf"),
            'filename' => "Invoice-{$invoice->number}.pdf",
            'filetype' => 'application/pdf',
            'mime_type' => 'application/pdf',
        ];
    }
}

// BuildGenericEmail trait handles attachment automatically

```

--------------------------------

### Add Email Templates Plugin to Filament Panel

Source: https://github.com/visualbuilder/email-templates/blob/3.x/README.md

Integrates the email templates plugin into a Filament 3.0 admin panel by adding it to the `plugins()` method in the `AdminPanelProvider`. Menu group and sort order can be configured in the package's config file.

```php
use Visualbuilder\EmailTemplates\EmailTemplatesPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->plugins([
            EmailTemplatesPlugin::make(),
            // ...
        ]);
}
```

--------------------------------

### Define Allowed Config Keys for Token Replacement

Source: https://github.com/visualbuilder/email-templates/blob/3.x/README.md

This configuration specifies which application configuration keys are allowed to be used within email templates via tokens (e.g., `##config.app.name##`). This helps secure the email templating system by limiting access to sensitive configuration values. The keys are listed in the `config/filament-email-templates.php` file.

```php
    /**
     * Allowed config keys which can be inserted into email templates
     * eg use ##config.app.name## in the email template for automatic replacement.
     */
    'config_keys' => [
        'app.name',
        'app.url',
        'email-templates.customer-services'

```

--------------------------------

### Implement Button Token in Email Templates (HTML/Blade)

Source: https://context7.com/visualbuilder/email-templates/llms.txt

Facilitates the creation of styled buttons within email content using a special token syntax. The button token supports direct URL and title attributes, or dynamic URL replacement using other tokens. The rendering of these buttons respects the defined theme colors from the `EmailTemplateTheme`.

```html
// In email template HTML editor, use button token:
// {{button url='https://example.com/verify' title='Verify Email'}}

// Or with dynamic URL token:
// {{button url='##tokenUrl##' title='Reset Password'}}

// When passing URL to mailable:
class UserVerifyEmail extends Mailable
{
    use BuildGenericEmail;

    public string $template = 'user-verify-email';
    public string $sendTo;
    public $user;
    public $tokenUrl;

    public function __construct($user, $tokenUrl) {
        $this->user = $user;
        $this->tokenUrl = $tokenUrl;
        $this->sendTo = $user->email;
    }
}

// Button is rendered with theme colors from EmailTemplateTheme
```

--------------------------------

### Configure Email Template Settings

Source: https://github.com/visualbuilder/email-templates/blob/3.x/README.md

Defines default settings for email templates in the `config/filament-email-templates.php` file. This includes options for logo, logo size, content width, contact details, and footer links.

```php
//Default Logo
'logo'                    => 'media/email-templates/logo.png',

//Logo size in pixels -> 200 pixels high is plenty big enough.
'logo_width'              => '476',
'logo_height'             => '117',

//Content Width in Pixels
'content_width'           => '600',

//Contact details included in default email templates
'customer-services'  => ['email' => 'support@yourcompany.com',
                         'phone' => '+441273 455702'],

//Footer Links
'links'                   => [
    ['name' => 'Website', 'url' => 'https://yourwebsite.com', 'title' => 'Goto website'],
    ['name' => 'Privacy Policy', 'url' => 'https://yourwebsite.com/privacy-policy', 'title' => 'View Privacy Policy'],
],

```

--------------------------------

### Send User Registration Email (PHP)

Source: https://context7.com/visualbuilder/email-templates/llms.txt

Sends a user registration email. This email is automatically dispatched when the `Registered` event fires, provided it's enabled in the configuration. It can also be sent manually using the `UserRegisteredEmail` Mailable class, passing the user object.

```php
// Automatically sent when Registered event fires (if enabled in config) 
// Listen to: Illuminate\Auth\Events\Registered

// Manual send
use Visualbuilder\EmailTemplates\Mail\UserRegisteredEmail;

$user = User::create([
    'name' => 'John Doe',
    'email' => 'john@example.com',
    'password' => bcrypt('password'),
]);

Mail::send(new UserRegisteredEmail($user));

// Template key: 'user-welcome'
// Tokens: ##user.name##, ##user.email##

```

--------------------------------

### Manually Generate Verification URL and Send Notification

Source: https://github.com/visualbuilder/email-templates/blob/3.x/README.md

This PHP code demonstrates how to manually generate a signed URL for email verification and send a `VerifyEmail` notification to a user. It's useful when you need custom control over the verification process, such as on a custom registration page. The notification must be sent *before* logging in the user.

```php
use Illuminate\Support\Facades\URL;

$notification = new \Filament\Notifications\Auth\VerifyEmail();
$notification->url = URL::temporarySignedRoute(
    'filament.actor.auth.email-verification.verify',
    now()->addMinutes(config('auth.verification.expire', 60)),
    [
        'id' => $user->getKey(),
        'hash' => sha1($user->getEmailForVerification()),
    ]
);

$user->notify($notification);

Auth::login($user);

```

--------------------------------

### EmailTemplatesPlugin Methods

Source: https://context7.com/visualbuilder/email-templates/llms.txt

This section covers methods for the EmailTemplatesPlugin, allowing you to enable navigation conditionally and set a navigation group. It includes checking if navigation should be registered and retrieving the configured navigation group name.

```php
use Visualbuilder\EmailTemplates\EmailTemplatesPlugin;

// Register plugin with conditional navigation
EmailTemplatesPlugin::make()
    ->enableNavigation(fn () => auth()->user()->isAdmin())
    ->navigationGroup('Email Management');

// Check if navigation should be registered
$plugin = EmailTemplatesPlugin::get();
$shouldShow = $plugin->shouldRegisterNavigation(); // boolean

// Get configured navigation group
$group = $plugin->getNavigationGroup(); // "Email Management"
```

--------------------------------

### Configure Multi-Language Support for Email Templates

Source: https://context7.com/visualbuilder/email-templates/llms.txt

Sets the default locale and defines supported languages for multi-language email templates. This configuration allows for internationalization of email content, specifying display names and flag icons for each language.

```php
// config/filament-email-templates.php
'default_locale' => 'en_GB',

'languages' => [
    'en_GB' => ['display' => 'British', 'flag-icon' => 'gb'],
    'en_US' => ['display' => 'USA', 'flag-icon' => 'us'],
    'es' => ['display' => 'Español', 'flag-icon' => 'es'],
    'fr' => ['display' => 'Français', 'flag-icon' => 'fr'],
    'pt' => ['display' => 'Brasileiro', 'flag-icon' => 'br'],
    'in' => ['display' => 'Hindi', 'flag-icon' => 'in'],
],
```

--------------------------------

### Query Templates by Language Scope (PHP)

Source: https://context7.com/visualbuilder/email-templates/llms.txt

Retrieves email templates, prioritizing a specific language and falling back to the default locale if the primary language version is not available. This is useful for multi-language support.

```php
use Visualbuilder\EmailTemplates\Models\EmailTemplate;

// Get templates prioritizing specific language, fallback to default
$templates = EmailTemplate::language('fr')
    ->where('key', 'user-welcome')
    ->get();

// Returns French version if exists, otherwise default locale

```

--------------------------------

### Build Generic Email Trait for Mailable Classes (PHP)

Source: https://context7.com/visualbuilder/email-templates/llms.txt

The BuildGenericEmail trait simplifies email construction in Mailable classes. It automatically handles template loading, attachment management, token replacement, sender/recipient settings, and theme color application. It requires a template key and can optionally handle attachments.

```php
// Used in Mailable classes to build email from template
use Visualbuilder\EmailTemplates\Traits\BuildGenericEmail;

class MyEmail extends Mailable
{
    use BuildGenericEmail;

    public string $template = 'my-template-key';
    public string $sendTo;
    public $user;
    public $attachment; // Optional

    public function __construct($user) {
        $this->user = $user;
        $this->sendTo = $user->email;
    }

    // build() method is provided by trait:
    // - Loads template by key and locale
    // - Handles attachments if present
    // - Replaces tokens in subject, content, title, preheader
    // - Sets from, to, cc, bcc
    // - Applies theme colors
}
```

--------------------------------

### Using Model Attribute Tokens in Email Templates

Source: https://context7.com/visualbuilder/email-templates/llms.txt

Demonstrates how to use model attribute tokens (e.g., ##user.name##) and config value tokens (e.g., ##config.app.name##) within email templates. The provided PHP code shows how to pass models to a Mailable class for token replacement during email sending.

```php
// In email template HTML editor, use tokens like:
// Hello ##user.name##, your account ##user.email## has been verified!
// Order ##order.reference## for ##order.total_amount## is confirmed.
// Booking date: ##booking.date##

// When sending email, pass models to the Mailable constructor
$user = User::find(1);
$order = Order::find(100);

Mail::to($user)->send(new OrderConfirmationEmail($user, $order));
```

--------------------------------

### Build Function for Email Attachments (PHP)

Source: https://github.com/visualbuilder/email-templates/blob/3.x/README.md

This function handles the email building process, including attaching a PDF file to the email. It customizes the attachment's filename and file type, and then proceeds to render and send the email using a specified template and data.

```php
 public function build() {
        $template = EmailTemplate::findEmailByKey($this->template, App::currentLocale());

        if($this->attachment ?? false) {
            $this->attach(
                $this->attachment->filepath, [
                'as'   => $this->attachment->filename,
                'mime' => $this->attachment->filetype
            ]
            );
        }

        $data = [
            'content'       => TokenHelper::replace($template->content, $this),
            'preHeaderText' => TokenHelper::replace($template->preheader ?? '', $this),
            'title'         => TokenHelper::replace($template->title ?? '', $this)
        ];

        return $this->from($template->from['email'],$template->from['name'])
            ->view($template->view_path)
            ->subject(TokenHelper::replace($template->subject, $this))
            ->to($this->sendTo)
            ->with(['data'=>$data]);
    }
```

--------------------------------

### User Login Notification

Source: https://context7.com/visualbuilder/email-templates/llms.txt

This code provides two methods for sending a user login notification. It can be automatically sent when a 'Login' event fires if configured, or manually sent after authentication using 'Mail::send'. The notification uses the 'UserLoginEmail' mailable class.

```php
// Automatically sent when Login event fires (if enabled in config) 
// Listen to: Illuminate\Auth\Events\Login

use Visualbuilder\EmailTemplates\Mail\UserLoginEmail;

// Manual send after authentication
Mail::send(new UserLoginEmail($user));

// Template key: 'user-login'
// Tokens: ##user.name##, ##user.email##
```

--------------------------------

### Register Filament Email Templates Plugin in Admin Panel

Source: https://context7.com/visualbuilder/email-templates/llms.txt

Registers the EmailTemplatesPlugin within the Filament admin panel. This makes the email template management features accessible through the admin interface. Requires importing the plugin class.

```php
// app/Providers/Filament/AdminPanelProvider.php
use Visualbuilder\EmailTemplates\EmailTemplatesPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            EmailTemplatesPlugin::make(),
        ]);
}
```

--------------------------------

### Check Mailable Class Existence (PHP)

Source: https://context7.com/visualbuilder/email-templates/llms.txt

Determines if a corresponding Mailable class file exists for a given email template key. If it exists, the class name can be retrieved; otherwise, it indicates that the class needs to be created, which can be facilitated by tools like Filament.

```php
use Visualbuilder\EmailTemplates\Models\EmailTemplate;

$template = EmailTemplate::findEmailByKey('my-custom-email', 'en_GB');

if ($template->mailable_exists) {
    // Mailable class file exists in app/Mail/Visualbuilder/EmailTemplates/
    $mailableClass = $template->getMailableClass();
    // Returns: "App\Mail\Visualbuilder\EmailTemplates\MyCustomEmail"
} else {
    // Class needs to be created (Filament provides action to generate)
}

```

--------------------------------

### Configure Navigation Options in Filament Email Templates

Source: https://github.com/visualbuilder/email-templates/blob/3.x/README.md

This configuration snippet allows enabling or disabling admin panel navigation for email templates and themes. It also defines sorting, labels, icons, groups, and positions for these navigation items. This setting is managed within the `config/filament-email-templates.php` file.

```php
    /**
     * Admin panel navigation options
     */
    'navigation' => [
        'enabled' => true,
        'templates' => [
            'sort' => 10,
            'label' => 'Email Templates',
            'icon' => 'heroicon-o-envelope',
            'group' => 'Content',
            'cluster' => false,
            'position' => SubNavigationPosition::Top
        ],
        'themes' => [
            'sort' => 20,
            'label' => 'Email Template Themes',
            'icon' => 'heroicon-o-paint-brush',
            'group' => 'Content',
            'cluster' => false,
            'position' => SubNavigationPosition::Top
        ],
    ],

```

--------------------------------

### Create Custom Blade View Template for Emails (HTML/Blade)

Source: https://context7.com/visualbuilder/email-templates/llms.txt

Allows for fully customized email layouts using Blade templates. Developers can define the HTML structure and dynamically inject data, including theme colors, logos, titles, and content, via the `$data` array. The template can be set in configuration or directly on the Mailable class.

```html
// Create custom blade template
// resources/views/vendor/vb-email-templates/email/custom.blade.php
<!DOCTYPE html>
<html>
<head>
    <style>
        body { background-color: {{ $data['theme']['body_bg'] ?? '#ffffff' }}; }
    </style>
</head>
<body>
    <div style="max-width: 600px; margin: 0 auto;">
        <img src="{{ $data['logo'] }}" alt="Logo">
        <h1>{{ $data['title'] }}</h1>
        {!! $data['content'] !!}
    </div>
</body>
</html>

// Set in template view field: 'custom'
// Or update config default_view: 'custom'
```

--------------------------------

### Override Default Token Helper for Custom Logic (PHP)

Source: https://context7.com/visualbuilder/email-templates/llms.txt

Enables customization of how tokens are processed within email templates by extending the `DefaultTokenHelper` class. Developers can add custom logic, such as formatting currency values, to the `replaceModelTokens` method. The custom helper must be registered in the application's configuration.

```php
namespace App\Helpers;

use Visualbuilder\EmailTemplates\DefaultTokenHelper;

class CustomTokenHelper extends DefaultTokenHelper
{
    protected function replaceModelTokens($models, string $content): string
    {
        // Call parent implementation first
        $content = parent::replaceModelTokens($models, $content);

        // Add custom logic - e.g., format currency
        preg_match_all('/##(\w+)\.(\w+)\.currency##/', $content, $matches);
        foreach ($matches[0] as $index => $match) {
            $model = $matches[1][$index];
            $attribute = $matches[2][$index];
            if (isset($models->$model->$attribute)) {
                $formatted = '$' . number_format($models->$model->$attribute, 2);
                $content = str_replace($match, $formatted, $content);
            }
        }

        return $content;
    }
}

// Register in config
'tokenHelperClass' => App\Helpers\CustomTokenHelper::class,

// Use in template: Total: ##order.amount.currency##
```

--------------------------------

### Configure Email Translation Locales and Language Picker Options (PHP)

Source: https://github.com/visualbuilder/email-templates/blob/3.x/README.md

Defines the default locale and lists available languages for the email template language picker. This configuration allows for distinct locales like en_GB and en_US, and specifies display names and flag icons for each language.

```php
    'default_locale'   => 'en_GB',

    //These will be included in the language picker when editing an email template
    'languages'        => [
        'en_GB' => ['display' => 'British', 'flag-icon' => 'gb'],
        'en_US' => ['display' => 'USA', 'flag-icon' => 'us'],
        'es'    => ['display' => 'Español', 'flag-icon' => 'es'],
        'fr'    => ['display' => 'Français', 'flag-icon' => 'fr'],
        'in'    => ['display' => 'Hindi', 'flag-icon' => 'in'],
        'pt'    => ['display' => 'Brasileiro', 'flag-icon' => 'br'],
    ]
```

--------------------------------

### Include Models for Token Replacement in Email Class (PHP)

Source: https://github.com/visualbuilder/email-templates/blob/3.x/README.md

Extends the Mailable class to include additional models like 'Booking' for use in email templates. The constructor now accepts and assigns these models, making their attributes accessible via token replacement (e.g., ##booking.date##).

```php
class MyFunkyNewEmail extends Mailable
{
    use Queueable, SerializesModels, BuildGenericEmail;

    public string $template = 'email-template-key';  //Change this to the key of the email template content to load
    public string $sendTo;
    public Model $booking;

    public function __construct($user, Booking $booking) {
            $this->user       = $user;
            $this->booking    = $booking;
            $this->sendTo     = $user->email;
        }
```

--------------------------------

### Enable Conditional Navigation for Email Templates

Source: https://context7.com/visualbuilder/email-templates/llms.txt

Configures the navigation visibility for email templates based on a closure. This allows for role-based access control, ensuring only authorized users can access the email template management section.

```php
// AdminPanelProvider.php
->plugins([
    EmailTemplatesPlugin::make()
        ->enableNavigation(
            fn () => auth()->user()->can('view_email_templates')
        ),
])
```

--------------------------------

### Password Reset Success Notification

Source: https://context7.com/visualbuilder/email-templates/llms.txt

This snippet shows how to add a password reset success notification to your User model. It utilizes the 'UserPasswordResetNotification' from the package and generates a secure URL for the password reset page, which is then sent to the user.

```php
// Add to User model
use Visualbuilder\EmailTemplates\Notifications\UserPasswordResetNotification;

class User extends Authenticatable
{
    public function sendPasswordResetNotification($token)
    {
        $url = URL::secure(route('password.reset', [
            'token' => $token,
            'email' => $this->email
        ]));

        $this->notify(new UserPasswordResetNotification($url));
    }
}

// Template key: 'user-password-reset-success'
// Tokens: ##user.name##, ##user.email##
```

--------------------------------

### Add PDF Attachment to Mail Class (PHP)

Source: https://github.com/visualbuilder/email-templates/blob/3.x/README.md

Demonstrates how to pass an Order and Invoice model, with the invoice's PDF, to the Mail Class and set it as a public property for attachment. The attachment is retrieved using the getPdf() method.

```php
class SalesOrderEmail extends Mailable
{
    use Queueable, SerializesModels, BuildGenericEmail;

    public string $template = 'email-template-key';
    public string $sendTo;
    public $attachment;
    public User $user;
    public Order $order;
    public Invoice $invoice;

    /**
     * Constructor for SalesOrderEmail.
     *
     * @param User $user User object
     * @param Order $order Order object
     * @param Invoice $invoice Invoice object
     */
    public function __construct($user, $order, $invoice) {
        $this->user = $user;
        $this->order = $order;
        $this->invoice = $invoice;
        $this->attachment = $invoice->getPdf(); // Missing semicolon added
        $this->sendTo = $user->email;
    }
}
```

```php
class SalesOrderEmail extends Mailable
{
    use Queueable, SerializesModels, BuildGenericEmail;

    public string $template = 'email-template-key'; 
    public string $sendTo;
    public $attachment;

    /**
     * Constructor for SalesOrderEmail using PHP 8 constructor property promotion.
     *
     * @param User $user User object
     * @param Order $order Order object
     * @param Invoice $invoice Invoice object
     */
    public function __construct(public User $user, public Order $order, public Invoice $invoice) {
        $this->attachment = $invoice->getPdf(); 
        $this->sendTo = $user->email;
    }
}
```

--------------------------------

### Account Lockout Notification

Source: https://context7.com/visualbuilder/email-templates/llms.txt

This section explains how to send an account lockout notification. It can be triggered automatically when a 'Lockout' event occurs, or sent manually using 'Mail::send'. The 'UserLockedOutEmail' class is used for this notification.

```php
// Automatically sent when Lockout event fires (if enabled in config)
// Listen to: Illuminate\Auth\Events\Lockout

use Visualbuilder\EmailTemplates\Mail\UserLockedOutEmail;

// Manual send
Mail::send(new UserLockedOutEmail($user));

// Template key: 'user-locked-out'
// Tokens: ##user.name##, ##user.email##
```

--------------------------------

### Register Custom Password Reset Page in Filament Panel

Source: https://github.com/visualbuilder/email-templates/blob/3.x/README.md

Configures the Filament admin panel to use the custom `RequestPasswordReset` class for password resets. This is done within the `AdminPanelProvider` by specifying the custom class in the `passwordReset()` method.

```php
use App\Filament\Resources\Auth\RequestPasswordReset;
use Filament\Panel;
use Filament\PanelProvider;

class AdminPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            ->default()
            ->id('admin')
            ->path('admin')
            ->plugins([
                EmailTemplatesPlugin::make(),
            ])
            ->passwordReset(RequestPasswordReset::class);
    }
}

```

--------------------------------

### Configure Outgoing Email Sending Flags

Source: https://github.com/visualbuilder/email-templates/blob/3.x/README.md

This configuration array controls whether specific types of automated emails should be sent. It includes flags for new user registration, email verification, password resets, and successful password resets. These settings determine which events trigger an email notification. They are defined in the email templates configuration file.

```php
  'send_emails'             => [
        'new_user_registered'    => true,
        'verification'           => true,
        'user_verified'          => true,
        'login'                  => true,
        'password_reset_success' => true,
    ],


```

--------------------------------

### Send Custom Password Reset Notification

Source: https://github.com/visualbuilder/email-templates/blob/3.x/README.md

A method to send a password reset notification using the custom `UserResetPasswordRequestNotification`. It generates a secure reset URL and then dispatches the notification to the user.

```php
use Visualbuilder\EmailTemplates\Notifications\UserResetPasswordRequestNotification;

/**
 * @param $token
 *
 * @return void
 */
public function sendPasswordResetNotification($token)
{
    $url = \Illuminate\Support\Facades\URL::secure(route('password.reset', ['token' => $token, 'email' =>$this->email]));

    $this->notify(new UserResetPasswordRequestNotification($url));
}

```

--------------------------------

### Request Password Reset

Source: https://context7.com/visualbuilder/email-templates/llms.txt

This code overrides Filament's default RequestPasswordReset page to use a custom notification for password reset requests. It ensures that the 'UserResetPasswordRequestNotification' is sent when a user requests a password reset and shows how to register this custom page in the AdminPanelProvider.

```php
// Override Filament's RequestPasswordReset page
namespace App\Filament\Pages\Auth;

use Filament\Facades\Filament;
use Illuminate\Support\Facades\Password;
use Visualbuilder\EmailTemplates\Notifications\UserResetPasswordRequestNotification;

class RequestPasswordReset extends \Filament\Pages\Auth\PasswordReset\RequestPasswordReset
{
    public function request(): void
    {
        $data = $this->form->getState();

        $status = Password::broker(Filament::getAuthPasswordBroker())->sendResetLink(
            $data,
            function ($user, $token) {
                $tokenUrl = Filament::getResetPasswordUrl($token, $user);
                $user->notify(new UserResetPasswordRequestNotification($tokenUrl));
            },
        );
    }
}

// Register in AdminPanelProvider
->passwordReset(RequestPasswordReset::class)

// Template key: 'user-request-reset'
// Tokens: ##user.name##, ##tokenUrl##
```

--------------------------------

### Toggle Built-in Email Sending Functionality

Source: https://context7.com/visualbuilder/email-templates/llms.txt

Controls whether specific built-in email sending events are active. This configuration allows you to enable or disable the automatic sending of emails for various actions like user registration, verification, and password resets.

```php
// config/filament-email-templates.php
'send_emails' => [
    'new_user_registered' => true,
    'verification' => true,
    'user_verified' => true,
    'login' => true,
    'password_reset_success' => true,
    'locked_out' => true,
],
```

--------------------------------

### Define Accessor for Full Name in Model (PHP)

Source: https://github.com/visualbuilder/email-templates/blob/3.x/README.md

Demonstrates how to define an accessor for a 'fullName' attribute within a model. This allows derived attributes to be directly used in email templates via token replacement, such as ##user.full_name##.

```php
public function getFullNameAttribute()
{
  return $this->firstname.' '.$this->lastname;
}
```

```php
protected function fullName(): Attribute
{
    return Attribute::make(
        get: fn () => $this->firstname.' '.$this->lastname,
    );
}
```
Tokens:
Raw