openclerk / emails
A library for sending emails and email management
Requires
- openclerk/config: ^0.1
- openclerk/events: ^0.2
- openclerk/templates: ^0.1
- pelago/emogrifier: >=0.1
- phpmailer/phpmailer: >=5.2.9
- soundasleep/html2text: >=0.2.1
Requires (Dev)
- soundasleep/component-tests: dev-master
This package is auto-updated.
Last update: 2024-10-14 10:39:19 UTC
README
A library for sending emails and email management.
Installing
Include openclerk/emails
as a requirement in your project composer.json
,
and run composer update
to install it into your project.
Or, run composer require openclerk/emails
.
{ "require": { "openclerk/emails": "^0.1" } }
Features
- Send either text or HTML emails
- Generate text multipart automatically with html2text
- Automatically inline CSS styles with emogrifier for clients like Gmail
- Track e-mails sent with the
email_sent
event - Send emails to raw addresses or to User objects that return
getEmail()
Using
This project uses openclerk/config for config management.
First configure the component with site-specific values (assumes SMTP):
Openclerk\Config::merge(array( "phpmailer_host" => "mail.example.com", "phpmailer_username" => "mailer", "phpmailer_password" => "password", "phpmailer_from" => "mailer@example.com", "phpmailer_from_name" => "Example Mailer", "phpmailer_reply_to" => "mailer@example.com", "phpmailer_bcc" => "copy@example.com", // if set, send a copy of all emails to this address // optional values // "emails_templates" => __DIR__ . "/../emails", // "emails_additional_css" => __DIR__ . "/../config/custom.css", ));
Now define templates in emails/<id>.html
:
<title>Test email sent {$now}</title> <h1>Hi {$email},</h1> <p>This is a test email sent {$now}.</p>
You can optionally specify a wrapping layout HTML file in emails/layout.html
, and CSS
styles in emails/layout.css
:
<link href="layout.css" media="all" rel="stylesheet" type="text/css" /> <div class="content"> {$content} </div>
html, body { background: #eee; font-family: 'Arial', sans-serif; margin: 0; padding: 0; } .body { background: #eee; padding: 15px; } .content { padding: 15px; background: white; border: 1px solid #ccc; color: #111; line-height: 130%; }
Now you can send e-mails immediately:
$user = Users\User::findUser(db(), 1); if (!$user) { $user = "test@example.com"; } $result = Emails\Email::send($user, "<id>", array( "now" => date('r'), ));
Tracking emails sent
The email_sent
event can be used to track
emails that have been sent, for example by inserting them into an emails
database table:
Openclerk\Events::on('email_sent', function($email) { // insert in database keys $q = db()->prepare("INSERT INTO emails SET user_id=:user_id, to_name=:to_name, to_email=:to_email, subject=:subject, template_id=:template_id, arguments=:arguments"); $q->execute(array( "user_id" => $email['user_id'], "to_name" => $email['to_name'], "to_email" => $email['to_email'], "subject" => $email['subject'], "template_id" => $email['template_id'], "arguments" => serialize($email['arguments']), )); });
Mock mailing
You can set a mock mailer by calling Emails\Email::setMockMailer($callback)
with a valid
callback
function setUp() { Emails\Email::setMockMailer(array($this, "mockMailer")); } function tearDown() { Emails\Email::setMockMailer(null); } function mockMailer($to_email, $to_name, $subject, $template, $html_template) { // do your mock tests... }
TODO
- Queueing up/batch emails
- Properly escape templates
- i18n
- Failure notifications
Other versions
- actionmailer-html2text is a Ruby e-mail framework that automatically generates text multiparts for ActionMailer