Sending mail with BowPHP

Introduction

Sending emails in an application is commonplace. BowPHP ships with an easy-to-use email sending system. You can use this system through several drivers:

• smtp — Direct sending via an SMTP server
• ses — Sending via Amazon SES
• mail — Uses PHP's native mail() function
• log — Writes the mail to the logs (handy during development)

Configuration

You will find the configuration in the config/mail.php file, which is relatively simple. All the options are commented.

SES Driver

Install the aws/aws-sdk-php package if you want to use ses as the mail driver.

composer require aws/aws-sdk-php

Switching driver at runtime

use Bow\Mail\Mail;

Mail::setDriver('log');     // route all sends to the log
Mail::setDriver('smtp');    // back to the configured driver

Usage

To use the service, call the Bow\Mail\Mail class. It exposes the following static methods:

Method	Usage
send($view, $data, $cb)	Sends an email based on a view
raw($to, $subject, $message, $headers = [])	Sends plain text
queue($view, $data, $cb)	Queues the send
queueOn($queue, $view, $data, $cb)	Named queue
later($delay, $view, $data, $cb)	Deferred send (in seconds)
laterOn($delay, $queue, $view, $data, $cb)	Deferred on a named queue
setDriver($driver)	Switch driver on the fly

The send method

send lets you send emails based on a view.

Prototype

Mail::send(string $view, array|callable $data, ?callable $cb = null): bool

Parameter	Type	Description
$view	string	The name of the view to use
$data	array or callable	Data passed to the view. If you omit it and pass the builder directly as the 2nd argument, that is also valid.
$cb	?callable	Envelope builder (see Envelop below)

The callback receives an instance of Bow\Mail\Envelop which lets you add the recipient, the subject, the attachments, the sender, and so on.

Example

Consider the email-view.tintin.php view:

templates/email-view.tintin.php

Bonjour {{ $name }},

Nous vous informons que votre compte vient d'être crédité de 100.000.000 F.

Cordialement,

The code that sends the mail:

use Bow\Mail\Mail;
use Bow\Mail\Envelop;

$data = ['name' => 'Franck'];

Mail::send('email-view', $data, function (Envelop $envelop) {
  $envelop->to('info@exemple.com');
  $envelop->subject('Paiement !');
  $envelop->from('info@exemple.com', 'Bow');
});

Short form (without data for the view):

Mail::send('email-view', function (Envelop $envelop) {
  $envelop->to('info@exemple.com')
          ->subject('Bonjour')
          ->from('info@exemple.com', 'Bow');
});

The Envelop API

The Bow\Mail\Envelop object accumulates recipients, headers and the message body. All of its methods return $this, which allows chaining.

Recipients

$envelop->to('info@exemple.com');               // one recipient
$envelop->to(['a@x.com', 'b@x.com']);            // multiple recipients
$envelop->addCc('cc@x.com', 'Nom CC');
$envelop->addBcc('bcc@x.com');
$envelop->addReplyTo('reply@x.com');
$envelop->addReturnPath('bounces@x.com');

Aliases

The short methods cc(), bcc(), replyTo(), returnPath() are aliases of their addCc/addBcc/addReplyTo/addReturnPath counterparts and have the same signature.

Subject and sender

$envelop->subject('Objet du message');
$envelop->from('noreply@x.com', 'Mon App');

Message body

$envelop->html('<h1>Bonjour</h1>');   // HTML content (text/html type)
$envelop->text('Bonjour');             // plain text content
$envelop->view('emails.welcome', ['user' => $user]); // renders a view

Custom headers

$envelop->withHeader('X-Custom-Header', 'valeur');

Attachments

$envelop->addFile('/chemin/vers/fichier.pdf');

Priority

// X-Priority : 1 (highest) to 5 (lowest)
$envelop->setPriority(1);     // or $envelop->addPriority(1)

The raw method

raw lets you send a raw message (without a view):

Mail::raw(string|array $to, string $subject, string $data, array $headers = []): mixed

Parameter	Type	Description
$to	string|array	Recipient email(s)
$subject	string	Mail subject
$data	string	Message body
$headers	array	Additional headers

use Bow\Mail\Mail;

Mail::raw(
  'hello@exemple.com',
  'Hello, world',
  "C'est juste un email de test"
);

Queued sending

To avoid blocking the HTTP request, put the send in a queue. The (view, data, cb) signature is identical to send.

use Bow\Mail\Mail;
use Bow\Mail\Envelop;

// Default queue
Mail::queue('email-view', ['name' => 'Franck'], function (Envelop $e) {
  $e->to('info@exemple.com')->subject('Bonjour')->from('app@x.com');
});

// Named queue (high priority, for example)
Mail::queueOn('high', 'email-view', $data, $callback);

// Deferred send of 60 seconds
Mail::later(60, 'email-view', $data, $callback);

// Deferred on a named queue
Mail::laterOn(3600, 'mails', 'email-view', $data, $callback);

Worker required

Do not forget that a worker must be running (php bow run:worker) to process the queued jobs.

Is something missing?

If you run into problems with the documentation or have suggestions to improve the documentation or the project in general, please open an issue for us, or send a tweet mentioning the Twitter account @bowframework or directly on github.