This bundle provides a lower level support for mail manipulation on Symfony2. It is supported to deal with composing, sending and dealing with bounced messages in an abstract API.
Installing this bundle can be done through these simple steps:
-
Add this bundle to your project as a composer dependency:
// composer.json { // ... require: { // ... "instaclick/base-mail-bundle": "dev-master" } }
-
Add this bundle in your application kernel:
// application/ApplicationKernel.php public function registerBundles() { // ... $bundles[] = new IC\Bundle\Base\MailBundle\ICBaseMailBundle(); return $bundles; }
By default, any composed message contains a sender name and address. This simplifies the implementation time and cleaner code. You are allowed to change these values anytime, but if negative, you can globally configure this support.
To define the default sender name and address, do the following:
ic_base_mail:
composer:
default_sender:
name: "InstaClick Mail Delivery"
address: "[email protected]"
This bundle also comes with a bounced email handler. For any reasons, when
dealing with delivery of messages to users' mailbox, you also need to handle
possible failures that users may have done. The best example is mispelled email
addresses.
To configure the bounced email handler, configure the mail_bounce
section in
bundle's configuration:
ic_base_mail:
mail_bounce:
mailhost: "imap.gmail.com"
port: 993
username: "%mailer_gmail_username%"
password: "%mailer_gmail_password%"
service: "imap"
option: "ssl"
mailbox: "INBOX"
The purpose of this bundle is to simplify mail creation, sending and handling possible failures. These three sections derived into three services that can be used by any application that consumes this bundle.
Responsible to compose messages. Configured default sender automatically
injects sender name and address to any message that gets created out of this
service. The methods setDefaultSenderName
and setDefaultSenderAddress
provide an ability to modify the values at runtime if necessary.
Apart from the before mentioned methods, this service only contains one method:
createMessage
; it initializes a new message to be prepared for sending.
$composerService = $this->getContainer()->get('ic_base_mail.service.composer');
$message = $composerService->createMessage();
A message instance contains a lot of options that can be defined by consuming
its API. By default, any message is configured to be a text/html
message and
the method setContentType
provides an ability to modify this behavior.
The interface for Message API is the following one:
interface MessageInterface
{
/**
* Get the subject.
*
* @return string
*/
public function getSubject();
/**
* Set the subject.
*
* @param string $subject
*/
public function setSubject($subject);
/**
* Get the recipient.
*
* @return string
*/
public function getRecipient();
/**
* Set the recipient.
*
* @param string $recipient
*/
public function setRecipient($recipient);
/**
* Get the senderName.
*
* @return string
*/
public function getSenderName();
/**
* Set the senderName.
*
* @param string $senderName
*/
public function setSenderName($senderName);
/**
* Get the senderAddress.
*
* @return string
*/
public function getSenderAddress();
/**
* Set the senderAddress.
*
* @param string $senderAddress
*/
public function setSenderAddress($senderAddress);
/**
* Get the sender (as a composite value of name and address)
*
* @return array
*/
public function getSender();
/**
* Get the replyTo address.
*
* @return array
*/
public function getReplyTo();
/**
* Set the repylTo address.
*
* @param string $replyTo
*/
public function setReplyTo($replyTo);
/**
* Get the returnPath.
*
* @return array
*/
public function getReturnPath();
/**
* Set the returnPath.
*
* @param string $returnPath
*/
public function setReturnPath($returnPath);
/**
* Get the templateName.
*
* @return string
*/
public function getTemplateName();
/**
* Set the templateName.
*
* @param string $templateName
*/
public function setTemplateName($templateName);
/**
* Get the parameterList.
*
* @return array
*/
public function getParameterList();
/**
* Set the parameterList.
*
* @param array $parameterList
*/
public function setParameterList(array $parameterList = array());
/**
* Get the contentType.
*
* @return string
*/
public function getContentType();
/**
* Set the contentType.
*
* @param string $contentType
*/
public function setContentType($contentType);
/**
* Check if this message is usable.
*
* @return boolean
*/
public function isUsable();
}
After your message is composed, it is time to send it. Sender service provides
this support by exposing a public method called send
. This method returns a
boolean value in case of successful delivery or failure. It does not take into
consideration bounced mail, since this is an asynchronous action that must be
implemented by a consumer of BounceMail Service.
// ...
$composerService = $this->getContainer()->get('ic_base_mail.service.composer');
$senderService = $this->getContainer()->get('ic_base_mail.service.sender');
$message = $composerService->createMessage();
$message->setSubject('Email Delivery Service');
$message->setRecipient('[email protected]');
$message->setTemplateName('ICCoreSiteBundle:EmailTemplates:welcome.html.twig');
$message->setParameterList(array('username' => 'Guilherme Blanco'));
$sentSuccessfully = $senderService->send($message);
TBD