nahoMailPlugin - 1.0.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

Signin


Forgot your password?
Create an account

Tools

Stats

advanced search
Information Readme Releases Changelog Contribute
Show source

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

  • naholyr: Initial release