nahoMail plugin
Overview
As of Symfony 1.2, sending emails has become more verbose and less structured.
nahoMail comes to help you using the new (lack of) mailing system:
* Inclusion of Swift Mailer (as adviced in mail documentation) directly in the plugin as an external.
* A centralized configuration : you won't have to redefine your SMTP access and call all those nested Swift classes. It's all done in your app.yml once.
* A nahoMail class with a simple "send" method which allows you to send an e-mail with (almost) one call.
* A shortcut to ease the construction of your mail body using partials or components.
* Abstraction of image-embedding
Installation
Follow usual instructions for installation of a plugin.
The prefered installation for this plugin should use SVN, as SwiftMailer is then included as a svn:externals.
Usage
There is only one method to send emails, all the alternative usage are implemented with an associative array of options.
As of an example, mail parts (for your alternative body), attachments, and embedded images will be described in this
array and then handled by the nahoMail class.
Sending a simple mail
nahoMail::send('My subject', 'My body', 'recipient@mail.com');
Sending a simple mail, getting body from a partial
# Load body from myModule/templates/_myPartial.php
$body = nahoMail::getBody('partial', 'myModule/myPartial');
nahoMail::send('My subject', $body, 'recipient@mail.com');
Full example : Sending a mail with two alternate bodies, and an attached image used in a template
# Load body from components myModule : myComponentHTML and myComponentPLAIN
list($body, $part) = nahoMail::getBodyAndAlternate('component', 'myModule/myComponentHTML', 'myModule/myComponentPLAIN');
# Build options array, with the message parts, add embedded images, and attach a ZIP file
$options = array(
'parts' => array( $part ),
'embed-images' => array(
'logo' => 'logo.gif', // will be computed to "/path/to/web/images/logo.gif"
),
'attachments' => array(
array( 'path' => '/tmp/myZip991287.zip', 'filename' => 'archive.zip' ),
),
);
// Embedded image can be magically used in the HTML body with <img src="%%IMG_logo%%" />
nahoMail::send('My subject', $body, 'recipient@mail.com', $options);
Configuration
In the $options array you can define many things. Some are intended to be defined only once, and should
be placed in your app.yml, under the mailer_defaults key. Others are intended to be defined on each call.
General options
These options will be usually defined in the app.yml, and rarely overridden by $options.
Connection
The first and most complex is the connection. Default method for sending emails is using the native mail feature
of PHP. This is the default behavior in nahoMail, but you can use all the rich connection system of Swift.
connection: # default connection uses mail() native function
type: native # can be native, smtp, sendmail, multi or rotator, see examples below
params: []
# Using a SMTP server
#type: smtp
#params:
# server: smtp-server
# port: 25
# encryption: OFF # can be SSL, TLS, or OFF
# authentication: # only if there is an authentication required
# username: smtp-user
# password: smtp-pwd
# timeout: 10 # connection failed after this time (seconds)
# requires_ehlo: off # depending on the target server
# Using a sendmail-like binary
#type: sendmail
#params:
# command
# flags
# timeout: 10 # connection failed after this time (seconds)
# requires_ehlo: off # depending on the target server
# Using multiple connections as a collection
#type: sendmail
#params:
# connections: {...} # list of connections, configured as this one (type, params, etc...)
# timeout: 10 # connection failed after this time (seconds)
# requires_ehlo: off # depending on the target server
# Using a collection of connections, keeping track of down servers
#type: sendmail
#params:
# connections: {...} # list of connections, configured as this one (type, params, etc...)
# timeout: 10 # connection failed after this time (seconds)
# requires_ehlo: off # depending on the target server
General options
from: you@mail.com # define your default sender's email
reply-to: ~
return-path: ~
subject-template: "%s" # Change this to customize all your subjects, exemple "[My Company] %s"
i18n-catalogue: messages # Catalogue used to translate subject
# About I18N : note that the subject_template AND the subject will be individually passed into the i18n process.
Per-sending options
Those options are generally defined only when you send the email, and the shouldn't defined in the app.yml.
However, it's still possible, and could be useful for some particular cases (example: you always insert your
logo as embedded images in all your mails, you will be able to define this once for all).
Attachments
Attachments are files which will be attached in the mail, and downloadable by the recipient.
attachments: # list of attached files
- # You can only give the file's path
"/path/to/file"
- # Or be more complete
path: "/path/to/another_file" # file's path
filename: "another_name" # file's name as attached in the mail
mime-type: ~ # mime-type of the file (can usually be guessed by PHP)
Embedded images
Embedded images will be attached in the mail, and will be able to be referenced in the HTML part of the mail,
using the "CID".
You set an associative array of images, and for each one :
- The key will be used to reference image in the view, using "%%IMG_key%%".
- The value will be passed into image_path() so you can use the shortened path you're used to.
embed-images:
name-of-image1: "myImage" # "/path/to/symfony-project/web/images/myImage.png"
name-of-image2: "myOtherImage"
...
# any reference to %%IMG_name-of-image1%% in your body or parts will be replaced by the corresponding CID.
Message parts
You can add different parts to your message, for example an HTML file (as a statistics report) should be attached
as a message part more than as an attached file.
parts: # List of additional message parts
- # A simple direct string of text/plain content
"Hello, world"
- # A more complex way of describing the same thing
content-type: text/plain # Content-type for plain text
content: "Hello, world" # Content, as direct string
encoding: UTF-8 # Encoding
charset: UTF-8 # Charset
-
content-type: text/html # Content-type for HTML contents
content: # Complex content
type: component # Type of the content : component or partial
name: myMod/myComp # Module/Partial or Module/Component
vars: { ... } # Variables passed to the view
Additional recipients
You can define "cc" and "bcc" in the options array.
cc: recipient or [recipients]
bcc: recipient or [recipients]
Address format
Any address (sender or recipient) can be of one of the following formats :
"email@domain.dlt" for a single address"name <email@domain.dlt>" for a name + addressarray("name", "email@domain.dlt") or array("email@domain.dlt", "name") for a name + address
For any recipient address, you can use an address or an array of addresses. The lib will be smart enough
to make the difference between the following possibly-confusing cases :
array("my name", "my@email.com") // single address
array(array("my name", "my@email.com")) // list of only one single address
array("my@email.com", "my_other@email.com") // list of two addresses
TODO
- Enhance usability, add shortcuts, etc...
Changelog
2009-03-18 | Trunk
- naholyr: added support for names in recipients and senders (supports "email", "name <email>" or array("name", "email")
- naholyr: added support for list of addresses for every recipients (single address or array of addresses, format below)
2009-02-24 | Trunk
- naholyr: fixed bug preventing usage of components (thanks to Nicolas for report)
2009-02-08 | Trunk
- naholyr: fixed a few notices
- naholyr: wrote simple unit tests
2009-01-31 | Trunk
- naholyr: fixed an error when sending e-mail with just a string body as second parameter
- naholyr: fixed the way helpers are loaded for versions lower than 1.2
- naholyr: proper disconnection when exception catched when sending mail
2009-01-31 | Trunk
2009-01-31 | Trunk
Nicolas Chambrier 