Homepage
Main navigation
Main content
Additional information
Login / Sign up
Quality Guidelines
About
GitHub
Propose new content
Winter CMS resources and help articles
Simple and to the point. Optimized by the community.
×
Login / Sign up
Quality Guidelines
About
GitHub
Propose new content
Edit trick
Changes will be published after manual review
Title
Give your trick a describing title. Do
not
start with «How to...».
Your trick
Keep it short and concise! Markdown is supported.
Written with AI for additional context # Rebrand vendor plugin mails without touching the plugin **Category:** Mail / Events **Works with:** Winter CMS 1.1+ (any plugin that sends view-based mails, e.g. Winter.User) ## The problem Plugins like **Winter.User** send transactional mails (`winter.user::mail.restore`, `winter.user::mail.activate`) using their own bundled templates. They look generic, and you usually want them in your own branding, layout and tone of voice. The usual options all have downsides: - **Editing the vendor views** — gone on the next `composer update`. - **Overriding templates in the backend (Settings → Mail templates)** — works, but the content now lives in the database instead of your git repository. No code review, no deploys, no history, and every environment (local, staging, production) has to be kept in sync by hand. - **Forking the plugin** — a maintenance burden for what is essentially a cosmetic change. What you actually want: the vendor plugin keeps *triggering* its mails exactly as it does today, but the *content* comes from your own git-tracked templates in your own plugin. ## The trick Winter's own mail system renders view-based mails through the global `mailer.beforeAddContent` event — the System module listens to it to resolve and render the template, and Winter.Translate listens to it for localization. Because event listeners run in priority order and returning `false` halts propagation, you can register your own listener at a **higher priority**, swap the vendor view code for your own, add the content yourself, and return `false` so the default handlers never run — but *only* for the mails you map. Everything else falls through untouched. In your plugin's `boot()` method: ```php Event::listen('mailer.beforeAddContent', function ($mailer, $message, $view, $data, $raw, $plain) { static $map = [ 'winter.user::mail.restore' => 'acme.site::mail.restore', 'winter.user::mail.activate' => 'acme.site::mail.activate', ]; // Only the two view-based vendor mails we rebrand; leave raw mails and // everything else to the default handlers. if ($raw !== null || !is_string($view) || !isset($map[$view])) { return; } $code = $map[$view]; MailManager::instance()->addContentToMailer($message, $code, $data); return false; // branded content added — skip the vendor template }, 100); ``` Your own templates (`acme.site::mail.restore`, …) are registered the normal way via `registerMailTemplates()` in your Plugin.php and live as `.htm` files in your plugin — versioned, reviewable, deployable. ## How it works 1. Winter.User calls `Mail::send('winter.user::mail.restore', …)` as usual — nothing changes on the vendor side. 2. The Mailer fires `mailer.beforeAddContent` before resolving the template content. 3. Your listener runs **first** (priority 100 beats the default priority 0 of the System/Translate listeners). 4. For unmapped views or raw mails it returns nothing, so propagation continues and the framework behaves exactly as stock. 5. For a mapped view it renders *your* template into the message via `MailManager::addContentToMailer()` and returns `false`, halting the event — so the vendor template is never rendered. ## Bonus: keep localization If you run a multilingual site with Winter.Translate, you also bypass its localization handler — so resolve the locale-suffixed variant yourself before adding content: ```php $locale = !empty($data['_current_locale']) ? $data['_current_locale'] : App::getLocale(); // Prefer a locale-suffixed variant (restore-fr, activate-en, …), else the base. $localized = EventRegistry::instance()->getLocalizedView($mailer->getViewFactory(), $code, $locale); MailManager::instance()->addContentToMailer($message, $localized ?: $code, $data); ``` (`EventRegistry` here is `Winter\Translate\Classes\EventRegistry` — the same class Winter.Translate uses internally, so your naming convention for localized templates stays identical to the rest of your site.) ## When to use this - You want vendor transactional mails in your own branding **and** you want those templates in version control rather than in the database. - You're rebranding a *subset* of mails and want everything else to keep stock behavior. - You can't or don't want to fork/patch the vendor plugin. ## When *not* to use this - If database-managed templates are fine for your workflow, simply overriding the template content in **Settings → Mail templates** is less code. - If you need to change *when* or *to whom* a mail is sent (not just its content), look at the plugin's own events instead — this hook only controls content. ## Gotchas - Guard against `$raw` mails and non-string views (Winter also supports `['html' => …, 'text' => …]` view arrays) — the early return in the snippet handles this. - Keep the listener registration in `boot()`, not `register()`, so all mail infrastructure is available. - If another plugin also registers a high-priority listener on this event, priorities decide who wins — pick a number consciously
References
Add additional online resources to your trick
+ Add reference
Topics
If your trick fits more than one topic select multiple. Select at least one.
Backend
Plugin Development
CMS
Twig
Themes
Deployment
Tags
You can use existing tags or create new ones. Add at least one.
Submit for review
Cancel
We use cookies to measure the performance of this website. Do you want to accept these cookies?
Accept
Decline