Custom Transport Drivers

Purpose and Scope

This document explains how to extend the hypervel/mail package with custom transport drivers. It covers the registration mechanism via MailManager::extend(), the TransportInterface contract requirements, configuration integration, and optional connection pooling support for custom transports.

For information about the built-in transport drivers (SMTP, SES, Mailgun, etc.), see Transport Drivers. For details on the transport pooling system, see Transport Pooling.

---

Overview

The mail system provides an extension mechanism that allows developers to register custom transport drivers without modifying the core codebase. Custom transports are registered via the MailManager::extend() method and stored in the $customCreators array src/MailManager.php61 When creating a transport, the system checks for custom creators before attempting to instantiate built-in drivers src/MailManager.php162-171

Architecture Flow

Sources: src/MailManager.php155-188

---

Registering Custom Drivers

The extend() Method

Custom transport drivers are registered using the MailManager::extend() method src/MailManager.php516-525 This method accepts three parameters:

Parameter	Type	Description
$driver	string	The driver name used in configuration (e.g., 'custom-api')
$callback	Closure	A closure that receives the configuration array and returns a TransportInterface
$poolable	bool	Whether the transport supports connection pooling (default: false)

The method signature:

Registration Flow

Sources: src/MailManager.php516-525

Example Registration

Custom drivers are typically registered in a service provider's boot or register method:

Sources: src/MailManager.php516-525

---

Implementing TransportInterface

Contract Requirements

All transport implementations must implement Symfony's TransportInterface src/MailManager.php38 The interface requires a single method:

Transport Implementation Structure

Sources: src/MailManager.php38 src/Transport/SesTransport.php src/Transport/LogTransport.php

Implementation Example

A custom transport typically:

1. Accepts configuration parameters in the constructor
2. Implements the send() method to dispatch messages
3. Returns a SentMessage instance with the message ID
4. Handles errors by throwing exceptions

Sources: src/Transport/SesTransport.php src/Transport/LogTransport.php

---

Configuration Integration

Configuration File Structure

Custom transports are configured in the mail.php configuration file alongside built-in drivers. The transport name must match the registered driver name:

Configuration Resolution Flow

Sources: src/MailManager.php155-171 src/MailManager.php459-475

Configuration Array Contents

The configuration array passed to the custom creator closure contains all keys from the mailer configuration:

Key	Type	Description
transport	string	The driver name (e.g., 'my-api')
pool	array	Optional pooling configuration
Custom keys	mixed	Any additional configuration values

Sources: src/MailManager.php162-171

---

Connection Pooling Support

Enabling Pooling

Custom transports can opt into connection pooling by setting the third parameter of extend() to true src/MailManager.php518-520 This adds the driver name to the $poolables array src/MailManager.php71-73

Pool Proxy Wrapping

When a poolable transport is resolved with a pool name, the system wraps it in a TransportPoolProxy src/MailManager.php163-168:

Sources: src/MailManager.php163-168 src/MailManager.php179-184

Pool Configuration

Pool settings are specified in the pool key of the mailer configuration:

These settings are passed to createPoolProxy() src/MailManager.php167 or src/MailManager.php183

Sources: src/MailManager.php163-168 src/MailManager.php179-184

---

Custom Creator Lookup Process

Transport Creation Algorithm

The createSymfonyTransport() method src/MailManager.php155-188 follows this decision tree:

Sources: src/MailManager.php155-188

Priority Order

The system resolves transports in this priority order:

1. Custom creators registered via extend() src/MailManager.php162
2. Built-in methods following the naming convention create{Transport}Transport src/MailManager.php174
3. Exception thrown if neither exists src/MailManager.php176

Sources: src/MailManager.php162-177

---

Built-in Transport Method Naming

Convention Pattern

Built-in transport methods follow the naming pattern src/MailManager.php174:

create{StudlyCase(transport)}Transport

Examples from the codebase:

Transport Key	Method Name
smtp	createSmtpTransport src/MailManager.php193
sendmail	createSendmailTransport src/MailManager.php241
ses	createSesTransport src/MailManager.php251
ses_v2	createSesV2Transport src/MailManager.php270
mailgun	createMailgunTransport src/MailManager.php309
postmark	createPostmarkTransport src/MailManager.php332
failover	createFailoverTransport src/MailManager.php355
roundrobin	createRoundrobinTransport src/MailManager.php380
log	createLogTransport src/MailManager.php405
array	createArrayTransport src/MailManager.php421

Sources: src/MailManager.php173-176

---

Best Practices

Error Handling

Custom transports should throw exceptions that extend Symfony's mailer exceptions for consistent error handling:

Configuration Validation

Validate required configuration keys in the constructor:

Pooling Considerations

When implementing poolable transports:

• Ensure the transport maintains minimal state
• Make connection establishment idempotent
• Handle connection errors gracefully
• Consider implementing proper cleanup in destructors

Testing Custom Transports

Custom transports should be tested independently:

Sources: src/Transport/ArrayTransport.php src/Transport/LogTransport.php

---

Complete Registration Example

Service Provider Registration

Sources: src/MailManager.php516-525 src/MailManager.php155-188

Full Implementation Example

Registration in Service Provider

Configuration

Sources: src/MailManager.php516-525 src/MailManager.php155-188