 |
VOOZH | about |
|
VOOZH | about |
This document explains the configuration system for the Hypervel Mail package. It covers the structure of the mail.php configuration file, available transport drivers, global address settings, and how the MailManager resolves and applies configuration at runtime.
For information about setting up the package initially, see Installation and Setup. For details on how transports are created and managed, see Transport System Overview and Transport Drivers.
The mail configuration is stored in config/mail.php (published from publish/mail.php). The configuration is divided into three main sections:
| Section | Purpose | Config Key |
|---|---|---|
| Default Mailer | Specifies which mailer to use by default | mail.default |
| Mailer Configurations | Defines individual mailer instances with transport settings | mail.mailers.* |
| Global Settings | Sets application-wide email addresses and rendering options | mail.from, mail.reply_to, mail.to, mail.return_path, mail.markdown |
The MailManager reads this configuration through the ConfigInterface and uses it to create configured Mailer instances with appropriate transports.
Sources: publish/mail.php1-135 src/MailManager.php78-82
The following diagram shows how the MailManager resolves configuration when creating a mailer instance:
Sources: src/MailManager.php87-92 src/MailManager.php105-108 src/MailManager.php115-148 src/MailManager.php459-475 src/MailManager.php480-487
The default mailer is specified using the mail.default configuration key or the MAIL_MAILER environment variable:
The MailManager retrieves the default driver name via getDefaultDriver() src/MailManager.php480-487 which checks for a legacy mail.driver configuration first for backwards compatibility, then falls back to mail.default.
When no mailer name is specified in mailer() or driver() calls, the default mailer is used automatically.
Sources: publish/mail.php20 src/MailManager.php87-92 src/MailManager.php480-487
The mail.mailers array defines individual mailer configurations. Each mailer must specify a transport key that determines which email delivery mechanism to use.
Each mailer configuration is an associative array with the following structure:
| Key | Type | Description |
|---|---|---|
transport | string | Transport driver name (required) |
url | string | Alternative URL-based configuration |
| Additional keys | mixed | Transport-specific options |
The following diagram shows the supported transport types and their configuration keys:
Sources: publish/mail.php35-38 src/MailManager.php155-188
The SMTP transport is created by createSmtpTransport() src/MailManager.php193-216 and configured by configureSmtpTransport() src/MailManager.php221-236 It supports:
tls or ssl via the encryption keyencryption and port, or explicitly set via schemesource_iptimeoutThe SES transport is created by createSesTransport() src/MailManager.php251-265 Configuration is merged with services.ses settings. The addSesCredentials() method src/MailManager.php289-296 formats credentials for the AWS SDK.
Created by createSesV2Transport() src/MailManager.php270-284 using the AWS SES V2 API client.
Created by createMailgunTransport() src/MailManager.php309-325 Falls back to services.mailgun configuration if secret is not provided in the mailer config.
Created by createPostmarkTransport() src/MailManager.php332-350 Falls back to services.postmark.token if not specified.
Created by createSendmailTransport() src/MailManager.php241-246
Created by createLogTransport() src/MailManager.php405-416 Logs emails instead of sending them. Useful for development.
Created by createArrayTransport() src/MailManager.php421-424 Stores emails in memory for testing purposes.
Created by createFailoverTransport() src/MailManager.php355-375 Attempts to send through each listed mailer in order until one succeeds.
Created by createRoundrobinTransport() src/MailManager.php380-400 Distributes emails across the listed mailers in a round-robin fashion for load balancing.
Sources: publish/mail.php41-99 src/MailManager.php193-424
The following diagram shows how transports are created from configuration:
The following transports support connection pooling via TransportPoolProxy:
smtpsendmailmailgunsesses_v2postmarkresendfailoverroundrobinPooling is enabled automatically for these transports when a named mailer is resolved. The pool configuration can be specified in the pool key of the mailer configuration.
Sources: src/MailManager.php71-73 src/MailManager.php155-188
Global addresses can be set at the application level and are applied to all emails sent through a mailer. These addresses are configured in the mail.php file or can be overridden in individual mailer configurations.
| Type | Config Key | Mailer Method | Purpose |
|---|---|---|---|
| From | mail.from | alwaysFrom() | Default sender address |
| Reply-To | mail.reply_to | alwaysReplyTo() | Default reply-to address |
| To | mail.to | alwaysTo() | Force all emails to this address (useful for staging) |
| Return-Path | mail.return_path | alwaysReturnPath() | Default return-path for bounce handling |
Each global address can be specified as an array with address and name keys:
The setGlobalAddress() method src/MailManager.php447-454 applies these settings when creating a mailer. It first checks the mailer-specific configuration, then falls back to the global mail.* configuration.
Sources: publish/mail.php112-115 src/MailManager.php143-145 src/MailManager.php447-454
The mail.markdown section configures the Markdown rendering system used for email templates:
| Key | Type | Description |
|---|---|---|
theme | string | Name of the CSS theme to use for HTML emails |
paths | array | Custom paths to search for mail components |
The theme key specifies which CSS theme to apply when rendering Markdown emails to HTML. Themes are located at mail::themes.{theme} and provide the styling for the email. The default theme provides a clean, responsive layout.
The paths array allows you to register custom directories containing mail component views. These paths are loaded by the Markdown class via loadComponentsFrom() src/Markdown.php136-139 The Markdown instance is created by MarkdownFactory which reads this configuration.
For more details on how Markdown rendering works, see Markdown Rendering.
Sources: publish/mail.php128-134 src/Markdown.php31-37 src/Markdown.php136-139
The mail system supports a legacy configuration format for backwards compatibility with Laravel 6.x and earlier. In this format, the entire mail.* configuration is used as the driver configuration, and mail.driver specifies the transport:
The getConfig() method src/MailManager.php459-475 detects this format by checking for the existence of mail.driver. When present, it returns the entire mail.* configuration instead of looking for mail.mailers.{name}.
Similarly, getDefaultDriver() src/MailManager.php480-487 checks mail.driver before falling back to mail.default.
Modern applications should use the mail.mailers.* format, which allows multiple mailer configurations and cleaner separation of concerns.
Sources: src/MailManager.php459-475 src/MailManager.php480-487
Mailer configurations support URL-based configuration through the url key. This provides a convenient way to specify all connection parameters in a single string:
Example URL formats:
smtp://user:pass@smtp.example.com:587?encryption=tlsmailgun://key@domain?endpoint=api.eu.mailgun.netThe getConfig() method src/MailManager.php459-475 detects the url key and uses ConfigurationUrlParser to parse it into individual configuration parameters. The parsed driver is moved to transport for consistency.
Sources: publish/mail.php44 src/MailManager.php468-472
The default configuration file uses environment variables extensively for configuration values. This allows different settings per environment without modifying the configuration file.
| Variable | Default | Description |
|---|---|---|
MAIL_MAILER | log | Default mailer name |
MAIL_URL | - | Complete mail configuration URL |
MAIL_HOST | 127.0.0.1 | SMTP server hostname |
MAIL_PORT | 2525 | SMTP server port |
MAIL_ENCRYPTION | tls | SMTP encryption method |
MAIL_USERNAME | - | SMTP authentication username |
MAIL_PASSWORD | - | SMTP authentication password |
MAIL_EHLO_DOMAIN | APP_URL host | SMTP EHLO domain |
MAIL_FROM_ADDRESS | hello@example.com | Default from address |
MAIL_FROM_NAME | Example | Default from name |
MAIL_LOG_CHANNEL | - | Log channel for log transport |
MAIL_SENDMAIL_PATH | /usr/sbin/sendmail -bs -i | Sendmail binary path |
AWS_ACCESS_KEY_ID | - | AWS access key for SES |
AWS_SECRET_ACCESS_KEY | - | AWS secret key for SES |
AWS_DEFAULT_REGION | us-east-1 | AWS region for SES |
MAILGUN_DOMAIN | - | Mailgun domain |
MAILGUN_SECRET | - | Mailgun API key |
MAILGUN_ENDPOINT | api.mailgun.net | Mailgun API endpoint |
POSTMARK_TOKEN | - | Postmark server token |
POSTMARK_MESSAGE_STREAM_ID | - | Postmark message stream ID |
Sources: publish/mail.php20-135
The MailManager supports registering custom transport drivers via the extend() method src/MailManager.php516-525:
When a custom driver is registered, it is stored in the $customCreators array src/MailManager.php61 The createSymfonyTransport() method src/MailManager.php162-171 checks for custom creators before attempting to call built-in creation methods.
The optional $poolable parameter indicates whether the transport should support connection pooling via TransportPoolProxy.
For more details on creating custom transports, see Custom Transport Drivers.
Sources: src/MailManager.php61 src/MailManager.php162-171 src/MailManager.php516-525
Refresh this wiki