- Опубликовано: 26 фев 2025
- 285
Эффективная разработка и отправка HTML-писем с помощью Maizzle 5 и Laravel 11
1. Зачем совмещать Maizzle 5 и Laravel 11?
- Maizzle упрощает верстку email-шаблонов, используя Tailwind CSS и «инлайнинг» стилей, оптимизацию HTML и удобные конструкции (layouts, partials, условия, циклы).
- Laravel предоставляет гибкую систему отправки писем (Mailables, Notifications, Queues) и всю бизнес-логику.
- При интеграции вы можете легко генерировать кросспочтово совместимые шаблоны и распределять их с помощью Laravel, не заботясь об инлайне CSS вручную.
2. Общая структура проекта
Обычно рекомендуют держать Maizzle-шаблоны в отдельной папке email-templates, рядом или внутри вашего Laravel-проекта. Структура может быть следующей:
laravel-app/
├── app/
├── config/
├── resources/
│ └── views/
│ └── emails/
├── routes/
└── ...
email-templates/ (корень Maizzle-проекта)
├── components/
│ ├── button.html
│ ├── divider.html
│ ├── spacer.html
│ └── v-fill.html
├── emails/
│ ├── images/
│ └── transactional.html
├── images/
│ └── logo.png
├── layouts/
│ └── main.html
├── node_modules/
├── .editorconfig
├── .gitignore
├── config.js
├── config.production.js
├── package-lock.json
├── package.json
├── README.md
└── tailwind.config.js
3. Установка и инициализация Maizzle 5
Перейдите в корень вашего репозитория Laravel:
cd /path/to/laravel
Затем инициализируйте Maizzle:
# Установка CLI (если ещё не установлено)
npm install --save-dev @maizzle/cli
# Создание базового проекта (скелета)
npx @maizzle/cli new
Установочный скрипт задаст несколько вопросов:
create-maizzle
│
◇ Where should we create your project?
│ ./email-templates
│
◇ Select a Starter
│ Default
│
◇ Install dependencies?
│ Yes
│
◇ Created project in ./email-templates
│
◇ Installed dependencies 17.373s
│
◇ Next steps: ──────────╮
│ │
│ cd ./email-templates │
│ npm run dev │
│ │
├────────────────────────╯
После выполнения в email-templates/ появится каталог с файлами:
email-templates/ (корень Maizzle-проекта)
├── components/
│ ├── button.html
│ ├── divider.html
│ ├── spacer.html
│ └── v-fill.html
├── emails/
│ ├── images/
│ └── transactional.html
├── images/
│ └── logo.png
├── layouts/
│ └── main.html
├── node_modules/
├── .editorconfig
├── .gitignore
├── config.js
├── config.production.js
├── package-lock.json
├── package.json
├── README.md
└── tailwind.config.js
4. Настройка путей сборки
4.1 Базовый пример
В config.production.js задайте, куда Maizzle должен складывать скомпилированные письма:
export default {
build: {
output: {
path: "../resources/views",
extension: "blade.php",
},
},
// А для неэкранированного вывода используем {!! !!}
expressions: {
unescapeDelimiters: ['{!!', '!!}']
},
css: {
inline: true,
purge: true,
shorthand: true,
},
prettify: true,
};
Что делает unescapeDelimiters: ['{!!', '!!}']?
- Если в вашем шаблоне появится
{!! какой-то HTML !!}, Maizzle не экранирует угловые скобки<,>и т.п. То есть вы получаете «чистый» HTML-вставку. - По аналогии с
{{ }}, где содержимое экранируется,{!! !!}(в Laravel/Blade) выводит HTML без экранирования. Maizzle даёт похожую возможность на своём уровне (до Blade), если вы хотите сохранить HTML-теги нетронутыми. После выполнения команды
npm run build production
Maizzle возьмёт файлы из emails/ и сгенерирует (скопилирует) их в директорию Laravel ../resources/views/emails/.
5. Игнорирование синтаксиса Blade в Maizzle
Laravel использует директивы Blade вида {{ }} (а также @if, @foreach и т.д.), которые могут конфликтовать с Maizzle, так как Maizzle по умолчанию тоже применяет {{ }} для своих выражений.
Maizzle в своей документации предлагает несколько основных способа сохранить/пропустить фигурные скобки, чтобы они «перешли» в финальную версию и были интерпретированы позднее в Laravel . Рассмотрим все:
5.1 @{{ }} для «единовременных» случаев
Если в каком-то месте вам надо, чтобы Maizzle не интерпретировал {{ }}, можно использовать Blade-вдохновлённый синтаксис @{{ }}. В этом случае в итоговом HTML @ будет удалён, а скобки останутся нетронутыми.
Например, в emails/example.html (Maizzle-шаблон):
<x-main>
@{{ $page->markup }}
</x-main>
Результат после сборки Maizzle:
<x-main>
{{ $page->markup }}
</x-main>
То есть Maizzle «убирает» символ @, а всё, что осталось в {{ }}, останется для следующего шага (например, обработки Blade).
5.2 Тег <raw> для множественных выражений
Если у вас целый блок кода, где есть несколько {{ }}-конструкций (Blade-тегов, чужой движок и т.п.), можно обернуть его в тег <raw>:
<raw>
<p>The quick brown {{ 1 + 2 }} jumps over the lazy {{ 3 + 4 }}.</p>
</raw>
В финальном HTML тег <raw> будет удалён, а содержимое не будет интерпретироваться Maizzle:
<p>The quick brown {{ 1 + 2 }} jumps over the lazy {{ 3 + 4 }}.</p>
6. Сборка
cd email-templates
npm run build production
В результате Maizzle отдаст готовый HTML, где «на уровне Maizzle» стили будут заинлайнены, а Blade-директивы «дойдут» в Laravel неизменёнными..
3. Использование в Laravel
Допустим, итоговый файл welcome.html лежит в resources/views/emails/welcome.html. Мы можем вызвать:
Route::get('/test-mail', function () {
$user = (object)['name' => 'Иван Петров', 'email' => 'test@example.com'];
Mail::send('emails.welcome', ['user' => $user], function ($message) use ($user) {
$message->to($user->email)
->subject('Привет!');
});
return 'Письмо отправлено!';
});
Blade увидит {{ $user->name }} и подставит 'Иван Петров' в письмо.
7. Итоговая схема сборки и отправки
- Разрабатываете шаблоны в
email-templates/emails. - Используете один (или несколько) способов «игнорировать» Blade-директивы в Maizzle:
@{{ }}для единичных случаев,<raw>для больших блоков,
- Собираете Maizzle-проект (обычно
nmp run build production), результат идёт в папку Laravelresources/views/emails. - Отправляете письма через Laravel Mailables. Blade-движок обрабатывает оставшиеся директивы
{{ }}и формирует конечный результат для отправки.
8. Заключение
- Maizzle решает боль верстки писем, инлайна CSS и адаптивности,
- Laravel заботится о бизнес-логике рассылки, валидации данных, очередях и пр.
Чтобы не конфликтовать с Blade-синтаксисом (или любым другим движком, который использует
{{ }}), вы можете:
- Использовать
@{{ }}для одиночных игнорирований. - Применять тег
<raw>для целых блоков.
Таким образом, вы получаете мощный, но гибкий процесс: Maizzle занимается версткой email-шаблонов, а Blade — динамикой и данными при отправке писем. Это упрощает разработку и снижает риск конфликтов при сборке. Удачи в реализации!
Была статья полезной:
