ggEmailPlugin
1.0.1stable
for sf 1.4sf 1.3 MIT
ggEmailPlugin helps using the symfony template/layout system for emails. The template and the layout directory can be configured, and the templates and the layouts can be accessed from everywhere in a symfony project, either application or task.
It also provides an easy way to add alternative text and html message parts to an email.
Developers
| Name |
Status |
Email |
Georg Gell |
lead |
moc.2evah <<ta>> GeG
|
License
Copyright (c) 2010 Georg Gell
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.
ggEmailPlugin
This plugin helps you to use the MVC pattern for emails also. This means that you can send the same email from any application or task, with or without decoration by a layout.
It also provides the functionality to combine plain text and html mail parts in one mail (nearly) automatically.
This plugin is stable and unsed in production without issues. Please discuss all issues on http://forum.symfony-project.org/viewtopic.php?f=12&t=29462.
Installation
Install the plugin
symfony plugin:install ggEmailPlugin
Add the plugin to config/ProjectConfiguration.class.php
[php]
public function setup() {
$this->enablePlugins(/* already enabled plugins */, 'ggEmailPlugin');
}
Configuration
You will find an app.yml.dist file in the plugin's config directory with the default settings.
Just copy it in your main config directory and remove the comments from the settings you
want to change.
app_ggEmail_layoutDir is the directory where the plugin will look for the layouts (default: lib/email/templates).app_ggEmail_templateDir is the directory where it will look for the templates (default: lib/email/modules). The
tempates in this directory need to be organized the same way like in the apps module folder, for example in app_ggEmail_templateDir/mymodule/templates/
all templates for this module.
Usage
To send an email, initialize the mailer first(call $this->getMailer(), which initializes the Swift auto loader) and then create the email message
<?php
$mailer = $this->getMailer(); // this works in actions and in tasks the same way
$message = new ggEmailMessage('The subject');
This message is a normal Swift_Message with one additional method setBodyFromTemplate().
<?php
public function setBodyFromTemplate(sfController $controller, $module, $name,
array $params, $layout = null, $contentType = null, $charset = null) {}
If you compose a message in an action like this
<?php
$mailer = $this->getMailer();
$message = new ggEmailMessage('Serious break in attempt');
$message->setBodyFromTemplate($this->getController(), // controller
'emergency', // name of the module
'serious_break_in', // name of the template
array('user' => 'georg', 'attempt' => 'SQL injection'), // variables for the template
'emergenceny_layout' // name of the layout
);
the plugin works like this:
- try to find the template with the name
serious_break_in.php in the current application in the module emergency and use it as the template.
- if it is not found, the plugin tries to find
app_ggEmail_templateDir/emergency/templates/serious_break_in.php and use it as the template.
- if this is not found, ggEmailPlugin looks for two further templates,
app_ggEmail_templateDir/emergency/templates/serious_break_in_html.php and app_ggEmail_templateDir/emergency/templates/serious_break_in_text.php and uses them.
If it finds both, the html message and the text template are added as alternative parts.
- It puts the params in the template.
- Now it looks in the layout dir of the current application, if it finds
emergenceny_layout.php there.
- If not, it uses
app_ggEmail_layoutDir/emergceny_layout.php to decorate the template (the text part is not decorated).
In a task, you would use it like this:
<?php
class sendAlertsTask extends sfDoctrineBaseTask {
protected function configure() {
$this->addOptions(array(
new sfCommandOption('application', null, sfCommandOption::PARAMETER_REQUIRED,
'The application name',
'app_where_to_look_for_templates')
));
}
protected function execute($arguments = array(), $options = array()) {
$mailer = $this->getMailer();
$controller = sfContext::createInstance($this->configuration)->getController();
$message = new ggEmailMessage('Serious break in attempt');
$message->setBodyFromTemplate($controller, 'emergency', 'serious_break_in',
array('user' => 'georg', 'attempt' => 'SQL injection'), 'emergceny_layout');
}
}
In this case the plugin would first try to find the template and layout in the directories of the application app_where_to_look_for_templates, and they are not found, in the directories defined by it's configuration.
In this way you can always override the standard templates from the plugin's configuration with the templates in the application/module template directory.
