Email

Prerequisites

What will you learn?

Sending a basic e-mail
Sending an e-mail using SMTP
Use a template as an e-mail body

Features

Wether your application is large or small, at one point or another you will need e-mail functionality. SpoonEmail provides a fast and easy way to deal with this.
It supports sending e-mail with PHP (using mail()) or SMTP (using fsockopen()) with or without SSL/TLS.

Basics

So let's start with the most basic e-mail you can send. This will send the contents to two recipients (one regular, one in CC):

// required classes
require_once 'spoon/spoon.php';

// new e-mail instance
$email = new SpoonEmail();

// this is the folder your compiled e-mail templates will end up in
$email->setTemplateCompileDirectory('/path/to/your/preferred/compile/directory');

// set e-mail headers
$email->setFrom('crimson.king@thunderclap.mw', 'The Crimson King');
$email->addRecipient('roland.deschain@gilead.mw');
$email->addCC('eddie.dean@brooklyn.ny');

// set variables
$variables = array();
$variables['replaceMe'] = 'e-mail';

// set e-mail contents
$email->setSubject("It's all 19");
$email->setHTMLContent('<strong>This is an {$replaceMe}</strong>.', $variables);

// send the e-mail
$email->send();

All but two functions in the above example are self-explanatory: setTemplateCompileDirectory() and setHTMLContent().

setTemplateCompileDirectory()

The reason why we have to set a compile directory is because internally, SpoonEmail will generate a template file with the e-mail contents, which in turn will be compiled. These files need to be written in a directory of choice.

This makes the use of SpoonTemplate mechanics available; building up an array to assign variables, iterations and options.

setHTMLContent()

This function has two parameters:

$content: This can be either the full body of an e-mail or the path to a template file.
$variables: The array with variables to be parsed in the contents.

For more information about the buildup of the $variables array, there are the SpoonTemplate tutorials.

SMTP example - Gmail

Now that you know the basics, let's take the same e-mail used above with three important changes:

We connect to Gmail with SMTP using their TLS security layer.
We use an external template file as our e-mail body.
The debug mode is set to true, so we can use getOutput()

// required classes
require_once 'spoon/spoon.php';

// new e-mail instance
$email = new SpoonEmail();

// enable the debug mode, this will let you use getOutput()
$email->setDebug(true);

// this is the folder your compiled e-mail templates will end up in
$email->setTemplateCompileDirectory('/path/to/your/preferred/compile/directory');

// SMTP info, remember to use your Gmail account credentials
$email->setSMTPSecurity('tls');
$email->setSMTPConnection('smtp.gmail.com', '587');
$email->setSMTPAuth('youraccount@gmail.com', 'yourpassword');

// set e-mail headers
$email->setFrom('crimson.king@thunderclap.mw', 'The Crimson King');
$email->addRecipient('roland.deschain@gilead.mw');
$email->addCC('eddie.dean@brooklyn.ny');

// set variables
$variables = array();
$variables['replaceMe'] = 'e-mail';

// set e-mail contents
$email->setSubject("It's all 19");
$email->setHTMLContent('/path/to/templates/email.tpl', $variables);

// send the e-mail
$email->send();

// check what response we got from the SMTP server
echo $email->getOutput();

The purpose of setSMTPSecurity() is to set the security layer used for your SMTP connection. Depending on the server this function is optional, but not for Gmail.

After executing the example you will receive output along these lines, meaning all went well:

220 mx.google.com ESMTP 7sm8987948eyg.17
250 mx.google.com at your service
220 2.0.0 Ready to start TLS
334 VXKlbn4wbBR6
334 UGFqv3dvcmS7
235 2.7.0 Accepted
250 2.1.0 OK 7sm8987948eyg.17
250 2.1.5 OK 7sm8987948eyg.17
250 2.1.5 OK 7sm8987948eyg.17
354 Go ahead 7sm8987948eyg.17
250 2.0.0 OK 1263983463 7sm8987948eyg.17

getOutput() will only work when you're connecting with SMTP. (There is no specific output for the mail() function.)