Mailhookbundle Laravel Package

Getting Started

MailHookBundle is a Symfony bundle that intercepts outgoing mail and enforces a recipient whitelist (with pluggable providers such as SES) — think of it as a safety net so staging/preprod environments can never accidentally email real customers. Version 3.0.2 is a maintenance release: it adds Symfony 5 compatibility, refreshes the SES provider, fixes the TreeBuilder::root deprecation, and cleans up CI. There are no breaking changes from 3.0.1, so upgrades are low-risk.

Where to look first:

1. The bundle's DI extension and Configuration class — this is where the TreeBuilder::root fix landed in this release (prepend, redirect_to, provider settings live here). Read it before touching config so you know the exact keys and defaults.
2. The provider implementations — especially the SES provider touched in PR #12. If you send via SES, verify the new provider behaviour against your existing mailer setup before deploying.
3. composer.json of the bundle — confirm the Symfony constraint now allows ^5.0. If your app is still on Symfony 4.x, the constraint range will tell you whether 3.0.2 is a drop-in or whether you should stay on 3.0.1.

First use case: install the bundle, register it in config/bundles.php (Symfony) or adapt the equivalent wiring for your framework, and set a dev/staging config that redirects all mail to a single inbox. Send one test mail and confirm the redirect fires before wiring anything else.

If you're on Laravel rather than Symfony, note the bundle targets Symfony's Mailer/Swiftmailer component. You can still use the underlying provider classes manually (register a listener that rewrites to/cc/bcc before send, or a MessageSent listener for audit), but the bundle auto-wiring won't apply — plan for a small adapter.

Implementation Patterns

Environment-scoped redirect config. Keep the bundle enabled only in dev and staging config packs, and set a single redirect_to address there. Production config should not import the bundle's config at all — that's the cleanest guarantee against accidental sends.

# config/packages/dev/mail_hook.yaml
mail_hook:
    redirect_to: '[email protected]'
    # provider-specific keys — check the refreshed SES provider (3.0.2) for exact names

Provider selection per environment. If your team uses SES in staging, wire the SES provider there (post-PR #12 it has updated handling); if local dev uses a different transport, swap providers per env rather than trying to make one provider cover both. This keeps the SES upgrade risk contained to staging.

Whitelist plus redirect, not redirect alone. Use the bundle's whitelist so that internal domains pass through untouched while everything external gets funnelled to the dev inbox. This preserves realistic internal-routing tests without exposing customers.

Pair with a mail-log listener. Add a small listener that records every outbound mail (to/cc/bcc/subject/timestamp) to a local log or a mail_logs table. The bundle controls where mail goes; the listener tells you what the app tried to send, which is invaluable when debugging "the email never arrived" during feature work.

CI smoke test. In a pipeline step, boot the app in the staging-equivalent env and assert that a synthesized message's to is rewritten. This turns the redirect guarantee into a regression test — worth setting up now that upstream CI (PR #11) has stabilised.

Upgrade path from 3.0.1. Bump the constraint to ^3.0.2, run the test suite, and diff your app config against the bundle's Configuration class — the TreeBuilder::root change (PR #14) can surface config-tree errors if you had non-root nodes configured. If you were relying on Symfony 5 compatibility being absent, 3.0.2 is what unblocks that upgrade.

Gotchas and Tips

• Symfony-first design. The bundle's listeners and providers assume Symfony's Mailer/Swiftmailer pipeline. In Laravel you'll need to bridge manually — don't assume config/mail.php settings reach the provider.
• The SES provider changed in 3.0.2 (PR #12). Behavioural changes here can silently alter how recipients are resolved or how bounces/returns are handled. Test SES sends end-to-end in staging after upgrading, not just unit-level.
• Symfony 5 support is newly added. Check the bundle's composer.json constraint carefully — "allows Symfony 5" may still permit 4.x ranges. Pin explicitly if your app mixes versions across packages.
• Config-tree errors after the TreeBuilder::root fix. If you previously had a root node named something other than the extension alias, the corrected root call may now reject your config. Error message will point at the node name; rename or drop the stray root key.
• Silent failure mode. If the bundle isn't registered (missing bundle entry, wrong env), nothing throws — mail just goes out for real. Verify with an actual send in each environment right after install; a misconfigured staging box is exactly the scenario this bundle exists to prevent.
• Whitelist vs. redirect precedence. Decide and document whether an address matching the whitelist bypasses redirect entirely, or is still redirected. Ambiguity here causes "internal emails work in dev but not staging" confusion.
• Extension point: custom providers. Implement the bundle's provider interface for transports it doesn't ship (Mailgun, Postmark, Laravel's MailManager). Keep it thin — a provider should only decide recipient rewriting, not transport config.
• Debugging: when mail isn't intercepted, check (in order) bundle registration, env config import, service autowiring, and finally whether the mailer is bypassing Symfony's mailer event (e.g. raw PHP mail() calls). That last case is unfixable by any bundle and a common source of "the hook didn't work".
• Version watch: 3.0.2 is a maintenance release. Track the SES provider and Symfony 5 issues upstream — these are the two areas most likely to need follow-up patches.