everlutionsk / email-bundle-2
Everlution email bundle for Symfony framework
Installs: 9 815
Dependents: 2
Suggesters: 0
Security: 0
Stars: 2
Watchers: 9
Forks: 3
Open Issues: 2
Type:everlution-bundle
Requires
- php: >=5.4.0
- doctrine/orm: ^2.3
- symfony/config: ^2.6 || ~3.0 || ~4.0 || >=5.0
- symfony/dependency-injection: ^2.6 || ~3.0 || ~4.0 || >=5.0
- symfony/http-kernel: ^2.6 || ~3.0 || ~4.0 || >=5.0
README
This Symfony bundle provides mechanism for sending and receiving email messages through various mail systems.
Installation
composer require everlutionsk/email-bundle-2
Enable the bundle
// app/AppKernel.php public function registerBundles() { return array( // ... new Everlution\EmailBundle\EverlutionEmailBundle() ); }
Configure the bundle
Following configuration snippet describes how to configure the bundle. Configuration requires a names of services, which implements corresponding interfaces. Only exception is doman_name, where you should set something like appdomain.com
# app/config/config.yml # Doctrine Configuration doctrine: orm: entity_managers: default: mappings: EverlutionEmailBundle: ~ # EmailBundle Configuration everlution_email: domain_name: APP_DOMAIN enforced_delivery_address: EMAIL_ADDRESS|NULL mail_system: Implementation of Outbound\MailSystem\MailSystem async_stream: Implementation of Support\Stream\Stream attachment_swappers: inbound: Implementation of Inbound\Attachment\AttachmentSwapper outbound: Implementation of Outbound\Attachment\AttachmentSwapper request_processors: inbound: Implementation of Inbound\RequestProcessor outbound_message_event: Implementation of Outbound\MessageEvent\RequestProcessor
mail_system - Name of service, which will be used for sending email messages. This service usually comunicate with SMTP server or with some transactional email platform like Mandrill.
enforced_delivery_address - [Optional] Email address, which will be used to override recipient address in every outbound message.
async_stream - Bundle allows to send email messages asynchronously. Email messages is stored in memory unil some value is added into this Stream. Good example is a Stream of Symfony's kernel.terminate events.
attachment_swappers - After sending or receiving a message, bundle try to save the message's attachments by using this attachment swappers. This swappers can save attachments in various ways.
request_processors - Bundle provide common mechanism to handle inbound messages and outbound message events. This events may occur for example when external mail system try to send scheduled messages. However, different mail systems sending data in different format. Request processors transform this data into format, which is known for this bundle.
Routing
Bundle provides controllers for handling inbound messages and outbound message events.
# Handle outbound message events. everlution.email.outbound_message_event: pattern: CUSTOM_PATTERN defaults: { _controller: everlution.email.outbound.message_event.controller:handleMessageEvent } methods: POST # Handle inbound messages. everlution.email.inbound: pattern: CUSTOM_PATTERN defaults: { _controller: everlution.email.inbound.controller:handleInbound } methods: POST
Basic Usage
Create new outbound message
$message = new OutboundMessage(); $message->setSubject('Subject'); $message->setText('Message text.'); // Text for basic insight in email client. $message->setHtml('<img src="cid:logo">'); // Email body. $message->setFromEmail('support@example.com'); $message->setFromName('Sender name'); $message->setReplyTo('reply@example.com'); $message->setRecipients([ new ToRecipient('recipient@mail.com', 'Recipient name'), new CcRecipient('cc-recipient@mail.com', 'Cc recipient name'), new BccRecipient('bcc-recipient@mail.com', 'Bcc recipient name'), ]); $image = new BasicAttachment('image/png', 'logo', file_get_contents('logo.png')); $attachment = new BasicAttachment('application/pdf', 'document.pdf', file_get_contents('document.pdf')); $message->setImages([$image]); // Images included into email body. $message->setAttachments([$attachment]);
Get mailer
Synchronous mailer - Mail system is called immediately.
$mailer = $this->get('everlution.email.outbound.synchronous_mailer');
Asynchronous mailer - Mail system is called after adding value into corresponding Stream.
$mailer = $this->get('everlution.email.outbound.asynchronous_mailer');
Send / Schedule message
$mailer->sendMessage($message);
$mailer->scheduleMessage($message, new \DateTime('+ 30 minutes'));
Advanced usage
Message transformers
Every message could be modified before it is forwarded into mail system.
Transforming outbound messages
Register service, which implements OutboundMessageTransformer and add following tag:
everlution.email.outbound.message_transformer
Transforming inbound messages
Register service, which implements InboundMessageTransformer and add following tag:
everlution.email.inbound.message_transformer
Message templates
Some mail systems supports message templates, which are defined in this systems. The following code shows how to use this templates.
$parameter = new Parameter('PARAMETER_NAME', 'PARAMETER_VALUE'); $template = new Template('TEMPLATE_NAME', [$parameter]); $message->setTemplate($template);
Handle Inbound messages
Inbound messages can be handled by listeners, which listening to everlution.email.inbound
events.
Events are instances of InboundEvent and contains information about Inbound message and about
its storable version, which has been saved into database.
Caution: If application doesn't need to create associations with inbound message in database, then storable version of message should be ignored.
Mock a mail system
Use everlution.email.mock.mail_system
service as mail system (see Configure the bundle section).