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
[php]
nahoMail::send('My subject', 'My body', 'recipient@mail.com');
### Sending a simple mail, getting body from a partial
[php]
# 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
[php]
# 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]
TODO
----
* Enhance usability, add shortcuts, etc...
Changelog
---------
### 2009-01-31 | Trunk
* naholyr: Initial release