nahoMailPlugin
1.0.1stable
for sf 1.2sf 1.1sf 1.0 MIT
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.
Example :
nahoMail::send('My subject',
nahoMail::getBody('partial', 'myModule/myPartial'),
'recipient@mail.com');
Developers
License
Copyright (c) 2009 Nicolas Chambrier
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
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]
TODO
- Enhance usability, add shortcuts, etc...
Changelog
2009-01-31 | Trunk
Nicolas Chambrier 