voilab / mailer
Small mailer tool.
Requires
- php: >=5.6.0
Requires (Dev)
README
Transactional mailer
Basic usage
Create the main mailer transport object
use voilab\mailer\Transport;
use voilab\mailer\adapter;
use voilab\mailer\renderer;
$mailer = new Transport();
$mailer->setAdapterFn(function (Transport $mail, array $createParams) {
return new adapter\SomeAdapter();
});
Stuff the mail with data...
$adapter = $mailer
->create(['customParam' => 1])
->setFrom('from@email.com')
->addTo('to@email.com')
->setSubject('A subject from James')
->setHtml('<p>Hello John</p>');
... or use global datas, templates and renderers to introduce variations
Please check below for more explanations about renderers and templates.
$mailer->setRenderer(new renderer\File('/path'));
$adapter = $mailer
->create()
->setFrom('from@email.com')
->addTo('to@email.com')
->setTemplate('some-file.php')
->setGlobalData([
'me' => 'James',
'you' => 'John'
]);
<!-- /path/some-file.php -->
<h1 data-renderer-subject>A subject from <?= $me; ?></h1>
<p>Hello <?= $you; ?></p>
Send the mail
try {
$mailer->send($adapter);
echo "mail is sent";
} catch (\Exception $e) {
echo $e->getMessage();
}
Templates
When using templates, subjects, html or text are ignored. They are all inside the template. You need to set a template ID in the adapter:
$adapter->setTemplate('some-template-id');
Note that if you use network templates, like with Sparkpost or Sendgrid, you can mix inline html with variables. The above restriction applies only when you use renderers (with Twig, for example).
With templates and renderers, you set the content automatically right before the email is sent. You can set html or text content at anytime using these methods:
$adapter = $mailer
->setRenderer(new renderer\File('/path/files'))
->create();
$mailer
->setHtml($adapter, 'file_html.php')
->setText($adapter, 'file_text.php');
// then send the email
File
File renderer is a fast and simple loader for PHP files. The global datas you gave to your adapter are injected in the file (with extract) and you can use them with raw PHP, includes, etc.
There are no check of any kind with variables. Use this templating mode at your own risks.
$renderer = new renderer\File('/path/to/files');
$mailer->setRenderer($renderer);
$adapter = $mailer
->create()
->setTemplate('file.php');
<h1 data-renderer-subject>This is the mail subject <?= $some_param; ?></h1>
<p>
All the rest will be the mail body, with all html needed, and access to all
params and functions from PHP.
</p>
<blockquote>
The <strong>p</strong> tag is absolutely not required. You can start your
message body (after the first h1) with anything you want, even an other h1
or no html tag at all.
</blockquote>
Twig
Twig renderer is more advanced as file renderer. You don't load a classic PHP file, but a twig template. The global datas you gave to your adapter are used as params when rendering the twig template.
$twig = new \Twig_Environment();
// configure your environment as you want
$renderer = new renderer\Twig($twig);
$mailer->setRenderer($renderer);
$mailer->create()->setTemplate('some_file.twig');
<h1 data-renderer-subject>This is the mail subject {{ some_param }}</h1>
<p>
All the rest will be the mail body, with all html needed, and access to all
params and functions from your <em>twig</em> environment.
</p>
<blockquote>
The <strong>p</strong> tag is absolutely not required. You can start your
message body (after the first h1) with anything you want, even an other h1
or no html tag at all.
</blockquote>
Note that you'll need to add this dependency into your own package.json:
"twig/twig": "1.*"
Adapters
Native mail function
To use native mail function, you can use the Zend2 or Zend3 adapter with the
right transport mechanism, as shown below.
$zend = new \Zend\Mail\Transport\Sendmail();
$mailer = new Transport();
$mailer->setAdapterFn(function () use ($zend) {
return new adapter\Zend2($zend);
});
Note that you'll need to add these dependencies into your own package.json:
"zendframework/zend-mail": "2.*""zendframework/zend-servicemanager": "3.*"
Zend Mail 3
// create the zend transport that fit your needs
$zend = new \Zend\Mail\Transport\Smtp(
new \Zend\Mail\Transport\SmtpOptions([
// smtp config
])
);
$mailer = new Transport();
$mailer->setAdapterFn(function () use ($zend) {
return new adapter\Zend3($zend);
});
Note that you'll need to add these dependencies into your own package.json:
"zendframework/zend-mail": "2.*""zendframework/zend-servicemanager": "3.*"
Zend Mail 2
// create the zend transport that fit your needs
$zend = new \Zend\Mail\Transport\Smtp(
new \Zend\Mail\Transport\SmtpOptions([
// smtp config
])
);
$mailer = new Transport();
$mailer->setAdapterFn(function () use ($zend) {
return new adapter\Zend2($zend);
});
Note that you'll need to add these dependencies into your own package.json:
"zendframework/zend-mail": "2.*""zendframework/zend-servicemanager": "3.*"
Sparkpost
$client = new \Http\Adapter\Guzzle6\Client(new \GuzzleHttp\Client());
$sparkpost = new SparkpostTransport($client, [
'key' => 'api key'
]);
$mailer = new Transport();
$mailer->setAdapterFn(function () use ($sparkpost) {
return new adapter\Sparkpost2($sparkpost);
});
Note that you'll need to add these dependencies into your own package.json:
"sparkpost/sparkpost": "2.*""php-http/guzzle6-adapter": "1.*"
SendGrid
$client = new \SendGrid('api key');
$mailer = new Transport();
$mailer->setAdapterFn(function () use ($client) {
return new adapter\Sendgrid5($client);
});
Note that you'll need to add this dependency into your own package.json:
"sendgrid/sendgrid": "5.*"
Mandrill
$client = new \Mandrill('api key');
$mailer = new Transport();
$mailer->setAdapterFn(function () use ($client) {
return new adapter\Mandrill($client);
});
Note that you'll need to add this dependency into your own package.json:
"mandrill/mandrill": "1.*"
Tests
First, copy tests/phpunit_default.xml to tests/phpunit.xml and fill in the
right values. Then, in the vagrant ssh, simply do this:
cd /vagrant
./vendor/bin/phpunit -c tests/phpunit.xml
To let phpunit send mails, just set true in the corresponding constant in the
phpunit.xml file.