Skip to content

mail.md

Latest commit

 

History

History
310 lines (243 loc) · 9.04 KB

mail.md

File metadata and controls

310 lines (243 loc) · 9.04 KB
Raw

Mailer

Zero Framework ships with a lightweight SMTP mailer that follows Laravel-style configuration while keeping the implementation dependency free. Messages are dispatched through the Zero\Lib\Mail\Mailer facade (Mail).

Implementation: Mailer.php, Message.php, Transport/SmtpTransport.php.

Mailer API

use Zero\Lib\Mail\Mailer;
// or via the kernel alias:
use Mail;

Mailer::send(Closure $callback): void

Build and send a message inside a closure. The closure receives a fresh Message (with the configured default from already applied).

Mail::send(function ($message) {
    $message
        ->to('user@example.test', 'Tofik')
        ->subject('Welcome!')
        ->html(view('mail.welcome', ['name' => 'Tofik']));
});

Mailer::raw(string $to, string $subject, string $body, bool $isHtml = false): void

Shortcut for one-line emails with no extra headers/attachments.

Mail::raw('ops@example.test', 'Heartbeat', 'still alive');
Mail::raw('user@example.test', 'Hi', '<b>hello</b>', isHtml: true);

Mailer::instance(): self

Get the underlying singleton. Rarely needed — send() and raw() cover the common cases.

$mailer = Mailer::instance();

Mailer::reset(): void

Drop the singleton (mainly for tests when config has changed).

Mailer::reset();

->dispatch(Closure $callback): void

Instance form of send(). The static Mailer::send() ultimately calls this.

Mailer::instance()->dispatch(function ($message) {
    $message->to($to)->subject($subject)->text($body);
});

Both send() and dispatch() validate that the message has a From address (either configured default or set via ->from()) and at least one recipient; otherwise they throw Zero\Lib\Mail\MailException.

Message API

The Message instance is what you build inside the send() callback. Every setter returns $this for chaining.

Recipients

->from(string $address, ?string $name = null): self

Override the configured default from.

$message->from('no-reply@example.test', 'Zero Framework');

->replyTo(string $address, ?string $name = null): self

$message->replyTo('support@example.test', 'Support Team');

->to(string $address, ?string $name = null): self

Add a recipient. Call multiple times to send to multiple addresses.

$message->to('alice@example.test')->to('bob@example.test', 'Bob');

->cc(string $address, ?string $name = null): self

$message->cc('manager@example.test', 'Manager');

->bcc(string $address, ?string $name = null): self

$message->bcc('audit@example.test');

Subject & body

->subject(string $subject): self

$message->subject('Your invoice is ready');

->text(string $body): self

Plain-text body.

$message->text("Hi Tofik,\n\nThanks for signing up.\n");

->html(string $body): self

HTML body. Pair with view() for templates.

$message->html(view('mail.welcome', ['user' => $user]));

->body(string $body, string $contentType): self

Low-level body setter (use this for non-text/html content types).

$message->body($json, 'application/json');

Headers

->header(string $name, string $value): self

Add a custom header.

$message
    ->header('X-Mailer', 'Zero/1.0')
    ->header('X-Priority', '1');

Attachments

->attach(string $filename, string $content, string $contentType = 'application/octet-stream'): self

Attach in-memory bytes. Build a multipart/mixed message automatically.

$pdf = file_get_contents(storage_path('invoices/INV-42.pdf'));
$message
    ->subject('Your invoice')
    ->html(view('mail.invoice', ['user' => $user]))
    ->attach('INV-42.pdf', $pdf, 'application/pdf');

For a file on disk:

$message->attach('report.csv', file_get_contents($path), 'text/csv');

Inspectors (used by transports / tests)

Method Returns
->getFrom() ?array{address, name}
->getReplyTo() ?array{address, name}
->getTo() / ->getCc() / ->getBcc() array<int, array{address, name}>
->getSubject() string
->getBody() string
->getContentType() string
->getCustomHeaders() array<string, string>
->getAttachments() array<int, array{filename, content, contentType}>
->getEnvelopeRecipients() unique To + Cc + Bcc list
->toMimeString() full MIME representation (multipart when attachments present) 
$envelope = $message->getEnvelopeRecipients();
$rfc822   = $message->toMimeString();

Configuration

Mail settings live in config/mail.php and are driven by environment variables. Populate the required keys in your .env file:

MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=your-username
MAIL_PASSWORD=secret
MAIL_ENCRYPTION=tls # tls, ssl, or leave blank for none
MAIL_FROM_ADDRESS=hello@example.com
MAIL_FROM_NAME="Zero Framework"
MAIL_TIMEOUT=30
MAIL_HELO_DOMAIN=my-app.local
MAIL_ALLOW_SELF_SIGNED=false
MAIL_VERIFY_PEER=true

Key options:

  • MAIL_MAILER – only the smtp driver is available today.
  • MAIL_HOST / MAIL_PORT – the SMTP endpoint and port (587 for TLS, 465 for SSL).
  • MAIL_ENCRYPTION – tls, ssl, or leave empty for plain connections.
  • MAIL_USERNAME / MAIL_PASSWORD – leave blank for unauthenticated relays.
  • MAIL_FROM_* – default sender information applied to every message.
  • MAIL_TIMEOUT – socket timeout in seconds (default 30).
  • MAIL_HELO_DOMAIN – override the domain used in the EHLO/HELO handshake.
  • MAIL_ALLOW_SELF_SIGNED / MAIL_VERIFY_PEER – toggle TLS certificate verification behaviour.

Sending Mail

Use the Mail facade (registered in core/kernel.php) to compose messages. The callback receives a Zero\Lib\Mail\Message instance with fluent helpers for addressing, headers, and content. The default from address is pulled from configuration, but you can override it per message.

use Mail;

Mail::send(function ($mail) {
    $mail->to('user@example.com', 'Test User')
         ->subject('Welcome to Zero Framework')
         ->html('<p>Thanks for signing up!</p>');
});

Override the From Address

Mail::send(function ($mail) {
    $mail->from('team@example.com', 'Support Team')
         ->to('user@example.com')
         ->subject('We updated your account')
         ->text('Your preferences were updated successfully.');
});

Plain Text

Mail::send(function ($mail) {
    $mail->to('ops@example.com')
         ->subject('Queue is backlogged')
         ->text("Check the workers.\nNothing is being processed.");
});

Reply-To, CC, and BCC

Mail::send(function ($mail) {
    $mail->to('customer@example.com')
         ->cc('support@example.com')
         ->bcc('auditor@example.com')
         ->replyTo('noreply@example.com')
         ->subject('Invoice #2024')
         ->html(view('emails.invoice', ['invoice' => $invoice]));
});

Attachments

Mail::send(function ($mail) use ($pdfName, $pdfContents) {
    $mail->to('customer@example.com')
         ->subject('Invoice PDF')
         ->html('<p>Your invoice is attached.</p>')
         ->attach($pdfName, $pdfContents, 'application/pdf');
});

Custom Headers

Mail::send(function ($mail) {
    $mail->to('partner@example.com')
         ->subject('Webhook verification')
         ->header('X-Request-Id', $requestId)
         ->header('X-Environment', app_env())
         ->text('Verification payload attached.');
});

Multiple Recipients

Each call to to, cc, or bcc appends a recipient, so you can chain or loop.

Mail::send(function ($mail) use ($recipients) {
    foreach ($recipients as $recipient) {
        $mail->to($recipient['email'], $recipient['name'] ?? null);
    }

    $mail->subject('Weekly status')
         ->text('Team, here is the weekly status update.');
});

Raw Convenience Helper

For quick notifications you can skip the callback entirely:

Mail::raw('alerts@example.com', 'Deployment finished', 'All services are green.');

Set the fourth argument to true to treat the body as HTML.

Error Handling

The mailer throws Zero\Lib\Mail\MailException when configuration is missing, the server rejects authentication, or a transport error occurs. Wrap calls in a try/catch block if you want to surface user-friendly feedback.

try {
    Mail::raw('ops@example.com', 'Heartbeat failed', 'Database is unreachable.');
} catch (Zero\Lib\Mail\MailException $e) {
    logger()->error('Failed to send alert email', ['error' => $e->getMessage()]);
}

Limitations & Future Work

  • Only the SMTP driver is implemented; queues and local sendmail integrations are on the roadmap.
  • Multipart/alternative payloads are not yet supported.
  • TLS verification defaults to secure settings—loosen them only for local development.

Contributions are welcome! See todo.md for potential enhancements.