Contributte Mailing

packagist.org/packages/contributte/mailing

# Content

Setup
Configuration - layouts, templates, options
Usage - building & sending

# Info

The main goal of this package is send emails easily. It has 4 main classes, MailBuilder, MailBuilderFactory, MailSender and MailTemplateFactory.

# Setup

composer require contributte/mailing

extensions:
	mailing: Contributte\Mailing\DI\MailingExtension

1
2

# Configuration

Default configuration looks like this.

mailing:
	template:
		defaults:
			layout: @@default
		config:
			layout: @@default

1
2
3
4
5
6

Templating and template options are under key template. At this moment, there's a default theme (https://github.com/leemunroe/responsive-html-email-template/ (opens new window)), simple but good looking. This default default layout is located in this package, you don't need to change anything. Unless you want your own layout.

The defaults should be untouched and it can be considered as base class. Your theme will be extending the default one.
The config can be considered as child class, define your own theme.

Typical configuration would be override the default theme with some extra features.

template:
	defaults:
		layout: @@default
	config:
		layout: @@mylayout

1
2
3
4
5

There are double @ because of NEON resolving.

# Usage

Example is better then 1k words.

# Builder

/** @var Contributte\Mailing\IMailBuilderFactory @inject */
public $mailBuilderFactory;

1
2

Thanks to MailBuilderFactory we use create MailBuilder to setup and finally send email.

// Builder
$mail = $this->mailBuilderFactory->create();
$mail->setSubject('It is awesome');
$mail->addTo($user->email);
$mail->addBcc($user->email);
$mail->addCcs($user->email);

// Template
$mail->setTemplateFile(__DIR__ . '/../../resources/awesome.latte');
$mail->setParameters([
	'username' => $user->logname,
]);

// Sending
$mail->send();

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

At first moment it looks the MailBuilder break the SRP, but it's not true. MailBulderFactory creates the MailBuilder and provides the IMailSender and IMailTemplateFactory. The MailBuilder is just tiny wrapper/builder with enjoyable API.

# Template

Each template has many internal variables:

$_defaults - refer default configuration
$_config - refer custom configuration
$_mail - refer mail configuration (can overrides subject, from, bcc, etc..)

{layout $_config->layout}

{block #header}
    Awesome emails.
{/block}

{block #content}
    Hello!
{/block}

1
2
3
4
5
6
7
8
9

Each template has many blocks, take a look to source.