Download the PHP package glueful/email-notification without Composer

Email Notification Extension for Glueful

Overview

The EmailNotification extension provides a modern email delivery system for the Glueful Framework's notification system. Built on Symfony Mailer, it features robust multi-provider support, failover, and an extensible transport architecture.

Built on Symfony Mailer with modern provider-bridge support. Implements the framework's notification channel contract (RichNotificationChannel) with structured NotificationResults.

Deprecation notice

• manifest.json is deprecated and removed in favor of Composer discovery (extra.glueful.provider).
• The top-level EmailNotification class has been removed; use the ServiceProvider-driven registration. Code that previously referenced Glueful\\Extensions\\EmailNotification should instead use the framework's notification system and/or resolve EmailNotificationProvider via DI.

Features

• ✅ Modern Symfony Mailer Integration - Enterprise-grade email infrastructure
• ✅ Multi-Provider Support - Brevo, SendGrid, Mailgun, Amazon SES, Postmark, and custom providers
• ✅ Provider Bridges - Native API integrations for optimal performance and reliability
• ✅ Failover - Multiple transport support with automatic failover
• ✅ Extensible Architecture - Support for any Symfony Mailer provider bridge
• ✅ Advanced Template System - Responsive templates with auto-escaped variable substitution and conditional logic
• ✅ Recipient Domain Policy - Allow-list / block-list enforcement on every recipient (primary, cc, bcc) before send
• ✅ Attachment Path Confinement - Attachment/embed paths confined to allowed directories
• ✅ Developer Experience - Clear error messages, debugging tools, and type safety

Requirements

• PHP 8.3 or higher with strict typing
• Glueful Framework 1.51.0 or higher
• OpenSSL PHP extension
• Symfony Mailer (included)
• Composer for provider bridge dependencies

Installation

Install via Composer (Recommended)

Enabling the extension

Installing the package does not auto-load it — its provider must be in config/extensions.php's enabled allow-list.

Development (recommended): the CLI edits config/extensions.php and recompiles the cache for you (it validates the change first, so it won't leave the config broken):

By hand / in production: add the provider as a plain string FQCN (no ::class) to the enabled list, then build the manifest in your deploy step:

Verify discovery and state:

Note: enable/disable are dev-only conveniences and are disabled in production — there, manage the enabled list in config and run extensions:cache.

Provider Bridge Installation

Install required Symfony provider bridges based on your email providers:

Configuration

Environment Variables

Configure your email providers in your .env file:

Services Configuration

Configure multiple email providers in config/services.php:

Custom Provider Support

The extension supports any Symfony Mailer provider bridge through three methods:

1. Custom DSN (Most Flexible)

2. Auto-Configuration (Standard Patterns)

3. Explicit Support (Built-in)

Already supported providers work without additional configuration.

Usage

Basic Email Sending

The extension integrates seamlessly with Glueful's notification system:

Template-Based Emails

Use professional templates for rich email experiences:

Key Benefits of this Approach:

• ✅ Clean and Simple - Minimal code required for template-based emails
• ✅ Automatic Global Variables - Variables like app_name, current_year, logo_url are automatically available
• ✅ Template Mappings - Use friendly template names that map to actual template files
• ✅ No Duplication - Each piece of data specified only once
• ✅ Type Safety - All template variables are validated and type-checked

Global Variables Available in All Templates:

Advanced Email Features

Leverage Symfony Mailer's advanced capabilities:

Asynchronous Delivery

This extension does not manage its own queue. Whether emails are sent synchronously or queued is decided by the framework's notification dispatcher — push notifications onto the framework queue at the dispatch layer and run workers (php glueful queue:work) per the framework's queue documentation. The channel itself sends a single message when invoked.

Retry tuning

Delivery-failure retry behavior is configured under emailnotification.retry (env MAIL_RETRY_ENABLED, MAIL_RETRY_MAX_ATTEMPTS, MAIL_RETRY_DELAY, MAIL_RETRY_BACKOFF, MAIL_RETRY_JITTER). On boot the extension surfaces this under the framework's channel-agnostic notifications.retry key (Framework 1.51.0+), so the core retry service picks it up. A transport failure returns a retryable transport_exception result; configuration errors return the non-retryable transport_misconfigured result and are not retried.

Transport Features

Multi-Transport Support

Configure failover so a send falls through to the next mailer when one is unavailable:

Transport Health Monitoring

Template System

The extension provides registered, definition-first templates. Installed extensions register template definitions through Glueful\Extensions\Contracts\Email\EmailTemplateRegistry; this extension owns the built-ins and stores operator overrides in the email_templates table. Absence of an override means "use the registered default"; reset deletes the row.

Built-in Templates

The extension registers 6 responsive built-in definitions:

1. Default (default)

• Use Case: General notifications, alerts, and multi-purpose emails
• Features: OTP support, action buttons, customizable styling
• Variables: {{name}}, {{message}}, {{action_url}}, {{action_text}}, {{otp}}, {{expiry_minutes}}

2. Welcome (welcome)

• Use Case: User onboarding and welcome emails
• Features: Friendly greeting, getting started guidance
• Variables: {{name}}, {{app_name}}, {{message}}, {{action_url}}, {{action_text}}

3. Alert (alert)

• Use Case: Security alerts, important notifications, warnings
• Features: Attention-grabbing design, urgency indicators
• Variables: {{message}}, {{details}}, {{action_url}}

4. Password Reset (password-reset)

• Use Case: Password reset functionality
• Features: Secure reset process, expiry warnings
• Variables: {{name}}, {{otp}}, {{expiry_minutes}}, {{reset_url}}

5. Verification (verification)

• Use Case: Account verification, email confirmation
• Features: Verification codes, confirmation links
• Variables: {{otp}}, {{expiry_minutes}}

6. Two-Factor PIN (two-factor-pin)

• Use Case: Two-factor authentication one-time codes
• Features: Prominent PIN display, expiry warning
• Variables: {{pin}}, {{ttl_minutes}}

Registering Templates From Another Extension

Extensions should register definitions during boot by soft-resolving the registry. Consumers do not bind defaults under the shared contract; only the email-notification extension binds the registry.

Admin API

All endpoints require auth plus email.templates.manage through the email_permission middleware:

• GET /email/templates
• PUT /email/templates/{key}
• DELETE /email/templates/{key}
• POST /email/templates/{key}/test
• GET /email/settings
• PUT /email/settings
• POST /email/settings/test

Template subjects are template-owned and rendered with the same placeholder engine as bodies. Unknown keys fail loudly; payload-supplied template names no longer select files.

Settings Precedence

Transport settings resolve per send: DB row -> services.mail config/env fallback. SMTP password rows are encrypted at rest with EncryptionService using AAD email.smtp_password, and API responses expose only password_set. Deployment-owned policy config (security.allowed_domains, security.blocked_domains, attachment confinement, debug/logging) remains in config/emailnotification.php and is not DB-managed.

Overriding Template Content

Operators override a registered template by saving a subject and body through PUT /email/templates/{key}. Resetting a template deletes the override row and returns the definition to its registered defaults. The renderer validates unbalanced {{#if}} blocks on save, and all interpolation keeps the escaping rules below.

Template Features

Variable Substitution:

• Simple variables: {{variable_name}}
• Default values: {{variable_name|default_value}}
• Nested variables: {{user.profile.name}}

Auto-escaping (security): every {{variable}} (and its default literal) is HTML-escaped with htmlspecialchars(ENT_QUOTES | ENT_HTML5), so notification data (display names, messages) cannot inject markup into outgoing mail. For slots that intentionally receive pre-rendered HTML, use the raw triple-mustache {{{variable}}} — the shipped layout's {{{content}}} is the only such slot; only use it for values you fully control. The action_url/reset_url values are blanked unless their scheme is http/https (relative URLs pass; javascript:/data: and malformed URLs are rejected).

Conditional Blocks:

Partials (Template Includes):

Global Variables: All templates automatically have access to configured global variables like {{app_name}}, {{logo_url}}, {{current_year}}, etc.

Template Inheritance

Create a base layout in partials/layout.html:

Templates without <!DOCTYPE html> automatically use this layout.

Security Features

Recipient Domain Policy

EmailChannel enforces an optional recipient-domain policy before sending. A recipient whose domain is disallowed yields a non-retryable NotificationResult failure (blocked_domain) and no mail is sent.

With neither set, all recipient domains are allowed. Both also accept an array in config/emailnotification.php under security.allowed_domains / security.blocked_domains.

The policy is enforced on every recipient — the primary address plus all cc/bcc entries — so an allowlist cannot be bypassed via a cc/bcc field; any disallowed (or non-string) entry fails the whole send closed. Matching is asymmetric by design: the blocklist also matches subdomains (blocking evil.com blocks sub.evil.com), while the allowlist is exact-match only (allowlisting company.com does not permit sub.company.com).

Attachment Path Confinement

Attachment and embedded-image paths come from notification data, so they are confined to allowed base directories before reaching Symfony: a path is accepted only when realpath() resolves it inside an allowed base (sibling-dir-safe — /app/storage-evil cannot pass for /app/storage). Configure via security.attachment_allowed_paths (array) in config/emailnotification.php; when null/empty it defaults to the application storage directory. A rejected path is a loud, non-retryable invalid_attachment failure with an ERROR log naming the path — never a silent skip.

Transport security

• Symfony Mailer: transport built on Symfony's mailer security.
• Provider isolation: isolated transport creation per send.
• Fail-loud misconfiguration: a missing SMTP host, missing provider-bridge credentials, or any transport-factory failure is a non-retryable transport_misconfigured failure (ERROR log, config keys only) — the channel never silently falls back to a null sink that would report success while discarding mail. An explicitly configured null sink (transport: 'null' or a null:// DSN) remains supported for development.
• Error sanitization: send failures return a structured NotificationResult (error code + message) and never throw SMTP credentials into the dispatcher. Logs never carry payload values (OTP pins, reset tokens/URLs, PII) — only payload keys plus the subject/type/template_name identifiers; diagnostics (getExtensionInfo()) return a credential-free config summary.

Monitoring and Debugging

Health & Metrics

Delivery metrics (per-channel delivery times, retry counts and distributions) are owned by the framework's notification system — use NotificationService::getMetricsService() (Glueful\Notifications\Services\NotificationMetricsService), which is fed by the structured NotificationResult this channel returns for every send.

Debug Mode

Enable detailed logging for troubleshooting:

Migration from PHPMailer

Breaking Changes in v1.0.0

1. Transport Configuration: New multi-mailer structure required
2. Queue System: File-based queue replaced with framework queue
3. Provider Specification: Explicit transport types required (e.g., brevo+api)
4. Dependencies: Symfony Mailer replaces PHPMailer

Migration Steps

1. Update Dependencies:

2. Update Configuration:

3. Update Environment Variables:

4. Verify Configuration:

Troubleshooting

Common Issues

1. Transport Creation Errors

   • Verify provider bridge is installed: composer require symfony/brevo-mailer
   • Check configuration structure in services.php
   • Review error logs for specific transport issues

2. Emails Not Sending Asynchronously

   • Async delivery is governed by the framework's notification dispatcher/queue, not this extension — see the framework queue documentation
   • Start queue workers: php glueful queue:work

3. Provider Bridge Issues

   • Verify API credentials are correct
   • Check transport specification (e.g., brevo+api vs brevo+smtp)
   • Review provider-specific documentation
4. Configuration Path Issues
   • Ensure the provider is discovered (composer-installed) and, if needed, enabled in config/extensions.php
   • Verify services.mail configuration exists
   • Check from address is configured

Health Checks

This extension registers no HTTP routes. Diagnose configuration from PHP/CLI instead:

Provider-Specific Setup

Brevo (Sendinblue)

SendGrid

Amazon SES

Mailgun

License

This extension is licensed under the MIT License.

Support

For issues, feature requests, or questions about the EmailNotification extension:

• Create an issue in the repository
• Consult the Symfony Mailer documentation
• Check the extension health monitoring for diagnostics

📚 Documentation: Glueful Framework Documentation
🔧 Provider Bridges: Symfony Mailer Bridges