soflomo / mail
Module to to ease the use of sending e-mail messages in Zend Framework 2
Installs: 100 865
Dependents: 1
Suggesters: 1
Security: 0
Stars: 5
Watchers: 5
Forks: 8
Open Issues: 1
Requires
- php: ^5.6 || ^7.0
- zendframework/zend-mail: ^2.0 || ^3.0
- zendframework/zend-servicemanager: ^2.7 || ^3.0
Requires (Dev)
- phpunit/phpunit: ^5.0
- squizlabs/php_codesniffer: ^2.0
- zendframework/zendframework: ^2.7 || ^3.0
This package is not auto-updated.
Last update: 2024-10-26 14:20:20 UTC
README
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
Installation
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.
Requirements
- Zend Framework 2: the
Zend\Mail
component - Zend Framework 2: the
Zend\ServiceManager
component
Usage
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' => 'bob@acme.com', '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' => 'bob@acme.com', 'subject' => 'Just want to say hi', 'template' => 'email/test', )); }
Additional options
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' => 'bob@acme.com', 'subject' => 'Just want to say hi', 'template' => 'email/test', 'to_name' => 'Bob', 'from' => 'alice@acme.com', 'from_name' => 'Alice', 'cc' => 'mike@acme.com', 'cc_name' => 'Mike', 'bcc' => 'john@acme.com' 'bcc_name' => 'John', 'reply_to' => 'internals@acme.com', 'reply_to_name' => 'ACME Corp internals mailing list' ));
Send to multiple recipients
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( 'bob@acme.com' => 'Bob', 'alice@acme.com' => '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('bob@acme.com' => null, 'alice@acme.com' => null)
Send custom headers
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' => 'bob@acme.com', 'subject' => 'Just want to say hi', 'template' => 'email/test', 'headers' => array( 'X-Send-By' => 'MyCustomApp' ), ));
Add attachments
Attachments is sent 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' => 'bob@acme.com', 'subject' => 'Just want to say hi', 'template' => 'email/test', 'attachments' => array( 'filename.ext' => '/absolute/path/to/file' ), ));
Use template variables
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' => 'bob@acme.com', 'subject' => 'Just want to say hi', 'template' => 'email/test', ), array( 'name' => 'Bob', ));
Use your own message object
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('alice@acme.com'); $service = $serviceLocator->get('Soflomo\Mail\Service\MailService'); $service->send(array( 'to' => 'bob@acme.com', 'subject' => 'Just want to say hi', 'template' => 'email/test', ), array(), $message);
Layout
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.
Configuration
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.
SMTP sending with the default transport
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.
Use an existing alternative transport service
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', ), ),
Use your custom transport factory
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', ), ),