Download the PHP package azine/email-bundle without Composer

Azine Email Bundle

Symfony2 Bundle provides an infrastructure for the following functionalities:

• simplify the rendering and sending of nicely styled html-emails from within your application
• send notifications/update-infos to your recipients, immediately or aggregated and scheduled.
• send newsletters to the recipients which wish to recieve it.
• preview the email-rendering in your browser and sent test mails to you, to view in your favorite email client.
• view sent emails in a web-view in the browser, for the case the email isn't displayed well in the users email-client.
• link campaign tracking with your analytics tool (google analytics or piwik or ...)
• track email opens with your analytics tool (google analytics or piwik or ...)
• works nicely with transactional email services like mailgun.com.

Table of contents

• Quick start guide & examples
• Requirements
  • 1. Swift-Mailer with working configuration
  • 2. Doctrine for notification spooling
  • 3. FOSUserBundle
• Installation
• Configuration options
• Customise the content and subjects of your emails
• Customise the layout of your emails
  • Your own implementation of TemplateProviderInterface
  • Your own Images
  • Your own Twig-Templates
  • 1. the wrapper-templates
  • 2. the content item-templates
• Make your emails available in the web-view and web-pre-view
  • Configuring the web-view and web-pre-view
  • Implement WebViewServiceInterface
  • Update your database
  • Define which mails to store for web-view
  • Deleting old "SentEmails"
• Operations
  • Deleting failed mail-files from spool-folder
  • Examples of Cron-Jobs we use in operation.
• TWIG-Filters
  • textWrap
  • urlEncodeText
  • stripAndConvertTags
  • addCampaignParamsForTemplate
• Use two different mailers for "normal" and for "urgent" emails
• Use transactional email services e.g.e mailgun.com
• GoogleAnalytics & Piwik: Customize the tracking values in email links
• Email-open-tracking with a tracking image (e.g. with piwik or google-analytics)
• Build-Status etc.

Quick start guide & examples

• How to configure
• Examples on how to use the plugin

Requirements

1. Swift-Mailer with working configuration

Mails are sent using the Swiftmailer with it's configuration.

So the symfony/swiftmailer-bundle must be installed and properly configured.

https://github.com/symfony/SwiftmailerBundle

2. Doctrine for notification spooling

For spooling notifications and for the web-view, Notification-/SentEmail-Objects (=>Azine\EmailBundle\Entity\Notification/Azine\EmailBundle\Entity\SentEmail ) are stored in the database. So far only doctrine-storage is implemented.

3. FOSUserBundle

In its current Version it depends on the FOSUserBundle, as it also "beautyfies" the mails sent from the FOSUserBundle and uses the Users to provide recipient information (name/email/notification interval/newsletter subscription) for the mails to be sent.

Installation

To install AzineEmailBundle with Composer just add the following to your composer.json file:

Then, you can install the new dependencies by running Composer’s update command from the directory where your composer.json file is located:

Now, Composer will automatically download all required files, and install them for you. All that is left to do is to update your AppKernel.php file, and register the new bundle. AzineEmailBundle has a dependency on KnpPaginatorBundle, so it`s also nessesary to add it to AppKernel.php file after installing.

Register the routes of the AzineEmailBundle:

Configuration options

For the bundle to work with the default-settings, no config-options are required, but the swiftmailer must be configured.

This is the complete list of configuration options with their defaults.

Some actions in AzineEmailBundle use iframe (e.g. email dashboard), make sure that X-Frame-Options is not set to DENY

It should be set to SAMEORIGIN to allow iframes from your domain

For more information about X-Frame-Options please follow:

https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Frame-Options

Customise the content and subjects of your emails

You must implement your version of the notifier service in which you pull the content of you notification- or newsletter-emails together. In you subclass of AzineNotifierService you can/should implement the following functions:

• getVarsForNotificationsEmail => variables you use in your twig-templates that are the same for all notification recipients
• getRecipientVarsForNotificationsEmail => variables you use in twig-templates for notifications that are specific for a recipient
• getRecipientSpecificNotificationsSubject => the notification-email subject
• getGeneralVarsForNewsletter => variable you use in twig-templates that are the same for all newsletter recipients
• getNonRecipientSpecificNewsletterContentItems => content items that are the same for all newsletter recipients
• getRecipientSpecificNewsletterParams => variables you use in twig-templates that are specific for a recipient
• getRecipientSpecificNewsletterContentItems => content items for a specific recipient
• getRecipientSpecificNewsletterSubject => newsletter subject for a specific recipient

See ExampleNotifierService.php for an example.

Customise the layout of your emails

You can/must customize the layout of your email in three ways:

• define your own styles by writing your own implementation of the TemplateProviderInterface
• use your own images
• create your own html and txt twig-templates.

A general overview is given here and the classes you should extend contain more inline-documentation on how stuff works.

Your own implementation of TemplateProviderInterface

This bundle includes a default implementation of a TemplateProvider ( => Services/AzineTemplateProvider) and also an example how to customize things (Services/ExampleTemplateProvider).

Remember that css-styles don't work in most email viewers. You need to embed everything into the attributes (e.g. "style") of your html-elements and do not use div-elements as they are not properly displayed in many viewers. Use Tables instead (<table><tr><td> etc.) to layout your emails.

e.g. <table width="100%"><tr><td height="20" style="font-size: 12px; color: blue;">Bla bla</td></tr></table>

You can define styles you would like to use in your emails and and also blocks of html-code. E.g. a drop-shadow implemented with td-elements with different shades of grey as background color. => see "leftShadow" and "cellSeparator" in the AzineTemplateProvider class.

Your own Images

You can use your own images which will be embeded into the emails. To do this, just define the path to your image-folder in your config.yml. => see above.

Some (web-) mail clients (gmail/thunderbird) will show those embeded images properly without aksing the recipient if he would like to show the attached images.

BUT as far as I can tell, this only works if there is only one email recipient visible to the client and the "from"-address matches the account that the mails have been send from. There are many reasons why the images might not get displayed, so make sure your mails look good without the images too.

Your own Twig-Templates

There are two kinds of templates required for this bundle, and both kinds for html- and for txt-content.

1. the wrapper-templates

These templates contain a header-section (logo etc.), header-content-section ("This is our newsletter blablabla"), main content (see "content-item-templates" below) and footer (links etc.).

They contain stuff that is usually exactly the same (except the greeting) for each of your recipients of this email.

This bundle will render email that consist of a html-part and a plain-text part.

The supplied baseEmailLayout-template in this bundle is split into two files baseEmailLayout.txt.twig and baseEmailLayout.html.twig to make them more easy to extend and manage. The .txt.twig with the required blocks and the .html.twig which is included in the body_html-block of the *.txt.twig template.

The "*.txt.twig" is the template that will be called for rendering. It must contain the following blocks:

• subject
• body_txt
• body_html

2. the content item-templates

In a newsletter- or notification-email you probably have different kind of items you would like to include.

For example in an update-email to your users you could mention 6 private messages, 3 events and 2 news-articles.

For those three types of content items you can define different "content-item-templates" and also differenct styles.

An example for "Private-Messages" is included => Resources/views/contentItem/message.txt.twig and Resources/views/contentItem/message.html.twig.

For a type of content-item you must allways provide a html and a txt-version. They will be referenced by their full ID withour the format.twig-ending.

=> "AzineEmailBundle:contentItem:message" for Resources/views/contentItem/message.txt.twig and Resources/views/contentItem/message.html.twig

When rendering those templates you have access to the styles and snippets defined for this template in your TemplateProvider.

Make your emails available in the web-view and web-pre-view

In the "web-pre-view" you can take a look at the content and layout of your email before sending them and you can send test-emails to your own email-address to view it in your favorite email-client.

In the "web-view" users reading you email can take a look at the email in their browser, if their favorite email client messes up the layout. The bundle adds a link at the top of you email to direct your users to the web-view : "If this email isn't displayed properly, see the web-version"

Configuring the web-view and web-pre-view

In order to use the web-view you must: 1) implement your version of WebViewServiceInterface. To minimize your effort, you can subclass the AzineWebViewService. 2) configure it as service in your services.yml and 3) set it in your config.yml as azine_email_web_view_service.

You can define how many days the sent mails shall be kept available by setting the value for azine_email_web_view_retention. The default is 90 days.

The web-view uses the following routes:

To use web-view you must enable these routes by including the routing file in you config.

Implement WebViewServiceInterface

The easiest way for you is to extend the AzineWebViewService and implement the three public functions

• public function getTemplatesForWebPreView()
• public function getTestMailAccounts()
• public function getDummyVarsFor($template, $locale) and maybe the
• public function __constructor(...) if you need any extra services to gather the dummy-data to populate the web-pre-view.

You can take a look at the ExampleWebViewService what to do in those functions.

Update your database

The web-view stores all sent emails in the database. In order to do so, the entity SentEmail must be available.

It is defined in SentEmail.orm.yml and you can update you database either with the command doctrine:schema:update or via migrations.

Define which mails to store for web-view

You can decide which mails you want to make available in web-view by overriding the function saveWebViewFor($template) in your TemplateProvider.

See ExampleTemplateProvider for hints on how to do this.

Deleting old "SentEmails"

Sent emails that are available in the web-view are stored in the database. As you want to get rid of old emails, there is a Symfony command to handle this for you.

The symfony console-command emails:remove-old-web-view-emails will remove all "SentEmail" that are older than the number of days you defined in azine_email_web_view_retention in your config.yml.

You can configure a cron-job to call this command regularly. See Cron-Job examples below.

Operations

Deleting failed mail-files from spool-folder

Some emails you want to send might fail and if you configured the swiftmailer to use file spooling, the spool-files for these mails will stay in you spool-folder named *.message.sending.

Running the swiftmailer:spool:send command will try to send those files again, but if sending fails repeatedly, you might end up with a spool-folder filled with mail-files that will allways fail.

To delete those files, you can use the emails:clear-and-log-failures command from this package.

Add a cron-job to do this for your application once per day, or if you have a lot of failing messages, once per hour. See Cron-Job examples below.

Using the date parameter for the command, you can define the duration during which the mailer should attempt to send those mails, before they are deleted by this command.

Examples of Cron-Jobs we use in operation.

Here are some examples how to configure your cronjobs to send the emails and cleanup periodically.

TWIG-Filters

This bundle also adds some twig filters that are useful when writing emails.

textWrap

The textWrap filter allows you to wrap text using the php function wordwrap. It defaults to a line width of 75 chars.

urlEncodeText

This filter will url encode text. With url encoded text, you can, for example, create mailto-links that will create an email with the subject and body already pre-filled.

stripAndConvertTags

When writing html emails, you should always supply a reasonably similar text version of your email.

If you do not have a text version of your html content, you can convert the html-code into something acceptable with this filter.

This will:

• replace all "a" html elements with text built as follows: "link text: url" or just "url", depending on the link text.
• strip all html tags => see strip_tags
• replace htmlentites with their original character => see html_entity_decode

addCampaignParamsForTemplate

This filter will get the tracking campaign parameters and values for the given twig-template and merge them with the given campaign parameters. Then all links in the template will be complemented with the campaign parameters that are not yet present.

Use two different mailers for "normal" and for "urgent" emails

In most cases you'll probably prefer UI-performance over speed of email-delivery. But for example for the password-reset- or for email-confirmation-emails you want the user to receive the mail a.s.a.p and not after the next spool-mailing.

To achieve this you must do two things: 1) configure multiple swiftmailers in you config.yml-files (see example below and http://symfony.com/doc/2.6/reference/configuration/swiftmailer.html#using-multiple-mailers) 2) define which emails should be delivered immediately in your TemplateProvider.

Here are extracts from config.yml-files:

And in your implementation of the TemplateProviderInterface, you can define emails from which templates should be sent immediately instead of spooled:

Use transactional email services e.g.e mailgun.com

To send and track your emails with a transactional email service
like mailgun.com, postmarkapp.com or madrill.com, you can set the swiftmailer configuration to use their smpt server to send emails.

If you are sending mails with mailgun on a free account and would like to be able to check the logs etc. for more than only two days, also check out the AzineMailgunWebhooksBundle. Mailgun deletes logs etc. from free accounts after aprox. two days. With this bundle you can store the events in your own database and keep them as long as you like.

PS: make sure your application is allowed to connect to the other smpt. This might be blocked on shared hosting accounts. => ask your admin to un-block it.

GoogleAnalytics & Piwik: Customize the tracking values in email links

In your implementation of the TemplateProvider, you can implement the function getCampaignParamsFor($templateId, $params) to define the values for the campaign tracking parameters in the links inside your emails.

You can define the values for each tracking parameter on an email template level and for emails that are composed from multiple nested content items, you can define values for these content item templates as well. And finally inside all the templates you can add campaign parameter values manually to individual links.

In this hierarchy (email template > content item template > individual link) values are not overwritten if they are defined on the more granular level. You can check the resulting links in the WebPreView of the email.

Email-open-tracking with a tracking image (e.g. with piwik or google-analytics)

To be able to track with Piwik or GoogleAnalytics (or the like) if an email has been opened, you can specify an image tracking url in your configuration.

If you configure the email_open_tracking_url in your config.yml, then the provided url will be complemented with the tracking parameters and values and a html img tag will be inserted into the html code at the end of your email.

If you wan't to change the way the tracking image url is complemented with the tracking parameters and values, then you can create and use your own implementation of the EmailOpenTrackingCodeBuilderInterface and update your config.yml to use that implementation.

See these links for more details on email tracking with images:

• GoogleAnalytics: https://developers.google.com/analytics/devguides/collection/protocol/v1/email
• Piwik: http://piwik.org/docs/tracking-api/#image-tracker-code
• Blogpost: http://dyn.com/blog/tracking-email-opens-via-google-analytics/

The tracking-image will also be inserted in the WebPreView of your emails, but to avoid false tracking events, the url will be modified to not point to your email-open-tracking system.

Contribute

Contributions are very welcome. Please fork the repository and issue your pull-request against the master branch.

The PR should:

• contain a description what the PR solves or adds to the bundle (reference existing issues if applicable)
• contain clean code with some iniline documentation and phpdocs, no "pure whitespace" changes.
• respect the Symfony best practices and coding style
• have phpunit tests covering the new feature or fix
• result in a 'green' build for your branch on travis-ci.org before you issue the PR

Code style

You can check the code style with the php-cs-fixer. Optionally you can set up a pre-commit hook which contains the php-cs-fixer check. Also see https://github.com/FriendsOfPHP/PHP-CS-Fixer

All you have to do is to move pre-commit.sample file from commit-hooks/ to .git/hooks/ folder and rename it to pre-commit.

php-cs-fixer will check the style of your new added code each time you commit and apply fixes to the commit.

To run php-cs-fixer manually, install dependencies (composer install) and execute php vendor/friendsofphp/php-cs-fixer/php-cs-fixer --diff --dry-run -v fix --config=.php_cs.dist .

Build-Status etc.