nahoMailPlugin - 1.1.2

The `nahoMailPlugin` is a symfony plugin that provides an easy way of sending emails in Symfony 1.1 and further.

You are currently browsing
the website for symfony 1

Visit the Symfony2 website

« Back to the Plugins Home


Forgot your password?
Create an account



advanced search
Information Readme Releases Changelog Contribute
Show source

nahoMail plugin


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


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.


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', '');

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, '');

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/', 'filename' => '' ),
// Embedded image can be magically used in the HTML body with <img src="%%IMG_logo%%" />
nahoMail::send('My subject', $body, '', $options);


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.


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
  #  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
  #  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
  #  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
  #  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:         # 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 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
  - # 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.

  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 + address
  • array("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", "")            // single address
array(array("my name", ""))     // list of only one single address
array("", "") // list of two addresses


  • Enhance usability, add shortcuts, etc...


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

  • naholyr: fixed package

2009-01-31 | Trunk

  • naholyr: first release