Soflomo\Mail is a facade module that integrates various components to send e-mails in Zend Framework 2. It allows users to compose messages, render templates and configure transports in one call. Every component is loosly coupled and can be replaced at runtime.
Soflomo\Mail offers:
- A single
send()
to configure a message, render the templates and send it - A default message objects with pre-filled variables like the "From" field
- A default transport which can by configured inside your configuration files
- All parts can be replaced by any of your own
Soflomo\Mail works with Composer. Make sure you have
the composer.phar downloaded and you have a composer.json
file at the root of
your project. To install it, add the following line into your composer.json
file:
"require": {
"soflomo/mail": "~0.3"
}
After installation of the package, you need to complete the following steps to use Soflomo\Mail:
- Enable the module by adding
Soflomo\Mail
to yourapplication.config.php
file. - Copy the
soflomo_mail.global.php.dist
(you can find this file in theconfig
folder of Soflomo\Mail) into your config/autoload folder and apply any setting you want.
- Zend Framework 2: the
Zend\Mail
component - Zend Framework 2: the
Zend\ServiceManager
component
Soflomo\Mail uses a central MailService
facade. This service exposes a single
send()
method to send an email based on some variables:
// $serviceLocator is an instance of Zend\Service\ServiceManager
$service = $serviceLocator->get('Soflomo\Mail\Service\MailService');
$service->send(array(
'to' => '[email protected]',
'subject' => 'Just want to say hi',
'template' => 'email/test',
));
The three keys are required to send an email. In the above example, template
is the name of the template which is resolved by the PhpRenderer and set as body
in the message.
The send()
configures the message, renders the email/test
template and sends
the message with a configured transport.
For controllers, a controller plugin exist to proxy to the email service:
public function sendAction()
{
$this->email(array(
'to' => '[email protected]',
'subject' => 'Just want to say hi',
'template' => 'email/test',
));
}
You can use, besides to
, also from
, cc
, bcc
and reply_to
. For every
addressee you can suffix the option with _name
to set the name of the address
part.
// $serviceLocator is an instance of Zend\Service\ServiceManager
$service = $serviceLocator->get('Soflomo\Mail\Service\MailService');
$service->send(array(
'to' => '[email protected]',
'subject' => 'Just want to say hi',
'template' => 'email/test',
'to_name' => 'Bob',
'from' => '[email protected]',
'from_name' => 'Alice',
'cc' => '[email protected]',
'cc_name' => 'Mike',
'bcc' => '[email protected]'
'bcc_name' => 'John',
'reply_to' => '[email protected]',
'reply_to_name' => 'ACME Corp internals mailing list'
));
You can make all of the addressees a key/value array. This allows you to send
to multiple persons in one send()
call.
// $serviceLocator is an instance of Zend\Service\ServiceManager
$service = $serviceLocator->get('Soflomo\Mail\Service\MailService');
$service->send(array(
'to' => array(
'[email protected]' => 'Bob', '[email protected]' => 'Alice'
),
'subject' => 'Just want to say hi',
'template' => 'email/test',
));
At this moment, the array must be a key/value pair. Non-associative arrays are
not recognized. If you want to leave the name blank, use null
:
array('[email protected]' => null, '[email protected]' => null)
You can add additional headers to the email message object with the headers
key.
// $serviceLocator is an instance of Zend\Service\ServiceManager
$service = $serviceLocator->get('Soflomo\Mail\Service\MailService');
$service->send(array(
'to' => '[email protected]',
'subject' => 'Just want to say hi',
'template' => 'email/test',
'headers' => array(
'X-Send-By' => 'MyCustomApp'
),
));
Attachment support is planned and not yet implemented. Attachments will be send
via the attachments
key and should be an associative array where key is the filename to be used in the email
and value is the absolute path to the attachment.
// $serviceLocator is an instance of Zend\Service\ServiceManager
$service = $serviceLocator->get('Soflomo\Mail\Service\MailService');
$service->send(array(
'to' => '[email protected]',
'subject' => 'Just want to say hi',
'template' => 'email/test',
'attachments' => array(
'filename.ext' => '/absolute/path/to/file'
),
));
The send()
method accepts a second paramter to inject variables in the view
template.
// Your template
<p>Welcome <?= $name?></p>
// $serviceLocator is an instance of Zend\Service\ServiceManager
$service = $serviceLocator->get('Soflomo\Mail\Service\MailService');
$service->send(array(
'to' => '[email protected]',
'subject' => 'Just want to say hi',
'template' => 'email/test',
), array(
'name' => 'Bob',
));
If you happen to have a message object already, you can set it as the third parameter. You can have a message object which you have already configured partially or you need to reuse an instantiated message.
// $messaga is an instance of Zend\Mail\Message
// $serviceLocator is an instance of Zend\Service\ServiceManager
$message->setFrom('[email protected]');
$service = $serviceLocator->get('Soflomo\Mail\Service\MailService');
$service->send(array(
'to' => '[email protected]',
'subject' => 'Just want to say hi',
'template' => 'email/test',
), array(), $message);
In your config file you can set the path to a layoutfile and your email will be sent with that layout.
To echo the content in the layout file you'll just use <?= $this->content; ?>
You could also change the layout pr. email, by using the key layout
in the options array.
Soflomo\Mail is completely configurable to your needs. The module utilizes dependency injection. This allows any user to drop in their own parts replacing the default services from Soflomo\Mail. In the usage section, some examples are given for these situations.
The transport Soflomo\Mail uses (called Soflomo\Mail\Transport
) is an alias for
the default transport (Soflomo\Mail\DefaultTransport
). You can use the default
transport for configuration-based SMTP transports. Just copy this to your local
config file in the config/autoload
directory:
'soflomo_mail' => array(
'transport' => array(
'type' => 'smtp',
'options' => array(
'name' => 'myserver.com',
'host' => 'smtp.myserver.com',
'connection_class' => 'login',
'connection_config' => array(
'ssl' => 'tls',
'username' => 'my-username',
'password' => 'my-password',
),
),
),
),
The 'type' can be a class from Zend\Mail\Transport\*
(so either "file", "smtp"
or "sendmail"). The options
array is used to instantiate an options object
corresponding to the type (for "smtp" an SmtpOptions
class is used).
soflomo_mail.global.php.dist
has more examples of different transport types and configurations.
Alternatively, give the type a FQCN and it utilizes that class for the transport. Be aware this FQCN is a simple solution and cannot implement dependency injection. For more advanced usage, see how to configure your own custom transport.
SlmMail is a module which implements the API for various third party email providers like Mailgun, Postmark and Amazon SES.
All SlmMail transports are services in the service manager which you can use to inject in any other class. For Soflomo\Mail, set the alias to the SlmMail transport you use and it's automatically injected.
'service_manager' => array(
'aliases' => array(
'Soflomo\Mail\Transport' => 'SlmMail\Mail\Transport\SendGridTransport',
),
),
When you have a custom transport and your factory registered, you can utilize it as well. Take the service name of your factory and set is as an alias.
'service_manager' => array(
'factories' => array(
'MyApp\Mail\Transport\MyTransport' => 'MyApp\Mail\Transport\MyTransportFactory'
),
'aliases' => array(
'Soflomo\Mail\Transport' => 'MyApp\Mail\Transport\MyTransport',
),
),