 |
VOOZH | about |
|
VOOZH | about |
This document describes the core interfaces (contracts) that define the public API of the hypervel/mail package. These contracts establish the fundamental behaviors required for sending mail, defining mail messages, and queue integration. Understanding these interfaces is essential for implementing custom transports, creating mailables, or extending the mail system.
For information about concrete implementations of these contracts, see Core Architecture. For guidance on creating mailable classes that implement the Mailable contract, see Working with Mailables. For queue integration details, see Queue Integration.
The mail system defines three primary contracts that work together to provide a complete mail sending abstraction:
Sources: src/Contracts/Mailable.php src/Contracts/Mailer.php src/Contracts/MailQueue.php
The Mailable contract defines the interface for classes that represent email messages. It combines message definition, recipient configuration, and dispatch methods into a single fluent interface.
| Method | Parameters | Return Type | Purpose |
|---|---|---|---|
send() | Factory|Mailer $mailer | ?SentMessage | Send the message immediately |
queue() | QueueFactory $queue | mixed | Queue the message for async delivery |
later() | DateInterval|DateTimeInterface|int $delay, QueueFactory $queue | mixed | Queue with delay |
to() | array|object|string $address, ?string $name | static | Set primary recipients |
cc() | array|object|string $address, ?string $name | static | Set carbon copy recipients |
bcc() | array|object|string $address, ?string $name | static | Set blind carbon copy recipients |
locale() | string $locale | static | Set message locale |
mailer() | ?string $mailer | static | Set mailer instance to use |
Sources: src/Contracts/Mailable.php12-53
The contract defines three dispatch methods:
send(Factory|Mailer $mailer) - Sends the message immediately using the provided mailer or factory. Accepts either a Factory (which resolves to a Mailer) or a Mailer instance directly. Returns a SentMessage on success or null if sending is prevented by event listeners.
queue(QueueFactory $queue) - Queues the message for asynchronous delivery. The message is wrapped in a SendQueuedMailable job and pushed to the configured queue. Returns the job ID or queue-specific identifier.
later(DateInterval|DateTimeInterface|int $delay, QueueFactory $queue) - Similar to queue(), but delays execution. The $delay parameter accepts an integer (seconds), DateInterval, or DateTimeInterface.
Sources: src/Contracts/Mailable.php14-27
Recipient methods (to(), cc(), bcc()) accept flexible address formats:
"user@example.com")"user@example.com", "John Doe")["user1@example.com", "user2@example.com"])__toString() or having email propertyAll three methods return static for fluent chaining.
Sources: src/Contracts/Mailable.php29-42
locale(string $locale) - Sets the locale for rendering the message content. This affects view translation and localized date/time formatting. Returns static for chaining.
mailer(?string $mailer) - Specifies which mailer configuration to use. Corresponds to keys in the mail.php mailers array. Pass null to use the default mailer. Returns static for chaining.
Sources: src/Contracts/Mailable.php44-52
The Mailer contract defines the interface for components that send mail. It provides both low-level sending methods and high-level fluent interfaces for building messages.
| Method | Parameters | Return Type | Purpose |
|---|---|---|---|
to() | mixed $users | PendingMail | Begin fluent mail to recipients |
bcc() | mixed $users | PendingMail | Begin fluent mail with BCC |
raw() | string $text, mixed $callback | ?SentMessage | Send plain text message |
send() | array|Mailable|string $view, array $data, Closure|string|null $callback | ?SentMessage | Send message with view |
sendNow() | array|Mailable|string $mailable, array $data, Closure|string|null $callback | ?SentMessage | Send synchronously |
Sources: src/Contracts/Mailer.php11-37
to(mixed $users) - Initiates a fluent mail building interface. Returns a PendingMail instance that allows chaining recipient configuration before sending. The $users parameter accepts the same flexible formats as the Mailable contract recipient methods.
bcc(mixed $users) - Similar to to(), but initializes with BCC recipients. Returns a PendingMail instance for fluent chaining.
Sources: src/Contracts/Mailer.php13-21
raw(string $text, mixed $callback) - Sends a plain text email without view rendering. The $text parameter contains the raw message body. The $callback can be a closure that receives a message instance for configuration, or a string specifying the recipient address.
send(array|Mailable|string $view, array $data, Closure|string|null $callback) - Sends a message using a view template. Accepts three usage patterns:
Mailable instance: Sends the mailable directly$data and configures via $callback['html' => 'view.html', 'text' => 'view.text'] for dual-part messagessendNow(array|Mailable|string $mailable, array $data, Closure|string|null $callback) - Forces synchronous sending, bypassing queue configuration. Useful when a mailable class has queue settings but you need immediate delivery.
Sources: src/Contracts/Mailer.php23-37
The Mailer acts as the sending engine, while Mailable represents the message. A Mailable requires a Mailer to send, but application code can interact with either interface depending on the use case.
Sources: src/Contracts/Mailer.php src/Contracts/Mailable.php
The MailQueue contract defines queue-specific mail operations. This interface is typically implemented alongside the Mailer interface to provide queue integration.
| Method | Parameters | Return Type | Purpose |
|---|---|---|---|
queue() | array|MailableContract|string $view, ?string $queue | mixed | Queue message to default queue |
later() | DateInterval|DateTimeInterface|int $delay, array|MailableContract|string $view, ?string $queue | mixed | Queue with delay |
Sources: src/Contracts/MailQueue.php11-22
queue(array|MailableContract|string $view, ?string $queue) - Queues an email for asynchronous sending. The $view parameter accepts the same formats as Mailer::send(). The optional $queue parameter specifies which queue to use (e.g., 'emails', 'high-priority'), defaulting to the configured default queue.
later(DateInterval|DateTimeInterface|int $delay, array|MailableContract|string $view, ?string $queue) - Similar to queue(), but adds a delay before processing. The delay can be specified as:
Sources: src/Contracts/MailQueue.php13-21
The MailQueue contract enables the Mailer implementation to create queue jobs that wrap mailables for deferred processing.
Sources: src/Contracts/MailQueue.php
The Factory contract defines the interface for creating and resolving Mailer instances. While not provided as a separate file, it is referenced in the Mailable contract.
Based on the Mailable interface src/Contracts/Mailable.php17 the Factory contract is used as an alternative to Mailer in the send() method signature:
This union type allows mailables to accept either:
Factory instance (e.g., MailManager) that resolves the appropriate mailerMailer instance for explicit controlThe Factory contract enables the manager pattern, where a single factory creates multiple mailer instances based on configuration. For implementation details, see Mail Manager and Factory Pattern.
Sources: src/Contracts/Mailable.php17
The following table maps each contract to its primary implementation(s):
| Contract | Primary Implementation | Location | Notes |
|---|---|---|---|
Mailable | Mailable trait | src/Mailable.php | Mixed into custom mailable classes |
Mailer | Mailer class | src/Mailer.php | Instantiated by MailManager |
MailQueue | Mailer class | src/Mailer.php | Same class implements both contracts |
Factory | MailManager class | src/MailManager.php | Singleton factory service |
Sources: src/Contracts/Mailable.php src/Contracts/Mailer.php src/Contracts/MailQueue.php
The contracts work together to provide flexible mail sending patterns:
This diagram illustrates three primary usage patterns:
Factory to create PendingMail, configure recipients, then sendMailable instance, call send() with a Factory or MailerMailable, call queue() with a QueueFactorySources: src/Contracts/Mailable.php src/Contracts/Mailer.php src/Contracts/MailQueue.php
To implement the Mailable contract without using the provided trait:
To implement the Mailer contract with custom sending logic:
Sources: src/Contracts/Mailable.php src/Contracts/Mailer.php
All contracts use specific return types that convey important information:
| Return Type | Meaning | Null Allowed? | Use Case |
|---|---|---|---|
?SentMessage | Sent message or prevented | Yes | May return null if event listener prevents sending |
PendingMail | Fluent configuration | No | Always returns for chaining |
static | Fluent self-reference | No | Enables method chaining on instance |
mixed | Queue job ID | No | Queue-specific identifier format varies |
The ?SentMessage return type in send() methods indicates that sending can be prevented by event listeners:
For more information on event-based sending prevention, see Event System.
Sources: src/Contracts/Mailable.php17 src/Contracts/Mailer.php26-36
The hypervel/mail package defines four core contracts that establish clear separation of concerns:
Mailable: Defines message structure and dispatch methodsMailer: Provides sending engine and fluent interfacesMailQueue: Enables queue integration for async deliveryFactory: Creates and resolves mailer instances from configurationThese contracts enable:
For concrete usage examples, see Working with Mailables. For transport implementation details, see Transport System Overview.
Sources: src/Contracts/Mailable.php src/Contracts/Mailer.php src/Contracts/MailQueue.php
Refresh this wiki