Exponent v2.7.2

expMail
in package

This is the class expMail expMail is an integrator class, bringing the flexibility of SwiftMail into Exponent gracefully.

More docs to follow as I become more familiar with SwiftMail.

Tags
subpackage

Subsystems

Table of Contents

$bcc  : mixed
$cc  : mixed
$from  : mixed
$subject  : mixed
$to  : mixed
$errStack  : mixed
$log  : mixed
$mailer  : mixed
$message  : mixed
$postcalldata  : mixed
$postcallfunction  : mixed
$precalldata  : mixed
$precallfunction  : mixed
$transport  : mixed
__construct()  : mixed
__construct() - This function constructs the message to be send in this object, filling it out with connection information based on the site config.
__destruct()  : mixed
expMail class destructor
addBcc()  : mixed
addBcc() - This adds Blind Carbon Copy addresses to the message one at a time, so if you want to add multiple BCC's it is best to run through a loop in order to put them in.
addCc()  : mixed
addCc() - This adds Carbon Copy addresses to the message one at a time, so if you want to add multiple CC's it is best to run through a loop in order to put them in.
addFrom()  : mixed
addFrom() - This adds the singular From address, if you call it twice, it will replace the old from address.
addHeaders()  : mixed
addHeaders() - Add text headers to the message. Limited to text headers for now.
addHTML()  : mixed
addHTML() - This function is similar to setHTMLBody except that it includes the HTML in the message body rather than sets it as default. Many mail clients will read the HTML over plain text as default behavior, so even if you use setTextBody and addHTML, they will default to reading the HTML.
addRaw()  : mixed
addRaw() - This is a wrapper around setHTMLBody for backwards compatibility
addSubject()  : mixed
subject() - This will set the subject of the message, ensuring first that message has been instantiated.
addText()  : mixed
addText() - This function is similar to the addHTML function above, it adds a plain text part to the message in case your recipient cannot receive HTML email, if you have added a text version of the email, they will have this to fall back on.
addTo()  : mixed
addTo() - This adds people to the Recipient List in the To Field.
attach_file_on_disk()  : mixed
attach_file_on_disk() - This function will utilize the swift mailer's ability to attach files that are on disk, unlike the one above, which just attached one that is available in memory.
batchSend()  : void
batchSend() - Does not seem to be working correctly. Use at your own risk!
clearBody()  : mixed
clearBody() - This function will set the body of the message to empty, a blank text string
flushRecipients()  : mixed
flushRecipients() - this will clear all of the recipients in the To array, ignoring CC and BCC
messageId()  : array<string|int, mixed>
messageId() - This will return the unique ID of the mail message.
quickBatchSend()  : bool|int
quickBatchSend() - a quick way to send a batch of emails one at a time This function is similar to quickSend, but sends each email separately to protect others identity in the mailing
quickSend()  : int
quickSend() - This is a quick method for sending email messages. It only requires a message value be passed in an associative array, (or else the message fails immediately).
send()  : int
send() - This is the main method for sending email messages.If there is not a from address, it defaults to the one stored in the Exponent config.
setHTMLBody()  : mixed
setHTMLBody() - This function sets the main version of the message to HTML.
setTextBody()  : mixed
setTextBody() - This function sets the main version of the message to plain text. No HTML
test()  : mixed
test() - Does the mail system seem to be working correctly? This is useless for the Native mail system

Properties

$subject

public mixed $subject = \null

$errStack

private mixed $errStack = \null

$mailer

private mixed $mailer = \null

$message

private mixed $message = \null

$postcalldata

private mixed $postcalldata = \null

$postcallfunction

private mixed $postcallfunction = \null

$precalldata

private mixed $precalldata = \null

$precallfunction

private mixed $precallfunction = \null

$transport

private mixed $transport = \null

Methods

__construct()

__construct() - This function constructs the message to be send in this object, filling it out with connection information based on the site config.

public __construct([array<string|int, mixed> $params = array() ]) : mixed
Parameters
$params : array<string|int, mixed> = array()

You can specify which method by which you would like to send mail.

Tags
author

Tyler Smart tyleresmart@gmail.com

example

You can specify how you would like to send mail, overriding the system default.

//Here you are using the system default, whether it is smtp, php mail, sendmail, exim, native, or rotator.

$emailItem = new expMail();

//Here you are trying different types of connections: $emailItem = new expMail(array('method'=>'smtp')); $emailItem = new expMail(array('method'=>'sendmail'); $emailItem = new expMail(array('method'=>'exim'); $emailItem = new expMail(array('method'=>'native'); $emailItem = new expMail(array('method'=>'rotator');

todo

add support for telling the constructor where the system specific Mail Transit Authority is: i.e. where sendmail or exim is if not in the default /usr/sbin

todo

drop support for passing in custom "connections", a Swift 3.x relic that we do not need.

todo

add further documentation for using settings other than the system default

Return values
mixed —

__destruct()

expMail class destructor

public __destruct() : mixed
Return values
mixed —

addBcc()

addBcc() - This adds Blind Carbon Copy addresses to the message one at a time, so if you want to add multiple BCC's it is best to run through a loop in order to put them in.

public addBcc(string|array<string|int, mixed> $email[, string $name = null ]) : mixed
Parameters
$email : string|array<string|int, mixed>

This is the email address for the BCC.

$name : string = null

This is the name associated with the above email address.

Tags
author

Tyler Smart tyleresmart@gmail.com

example

This will send a basic message, looping through an array of email addresses add adding them to the BCC list.

$emailItem = new expMail();

$emailItem->addText('My Text '); $emailItem->addText('Line Two '); $emailItem->addText('Line Three ');

$bccs = array('a@website.com'=>'Mr A.', 'b@website.com'=>'Mr B.', 'c@website.com'=>'Mr C.', 'd@website.com'=>'Mr D.', 'e@website.com'=>'Mr E.', 'f@website.com'=>'Mr F.');

//add multiple bcc recipients to the email foreach ($bccs as $email => $name) { $emailItem->addBcc($email, $name); }

$emailItem->addTo(array('myemail@mysite.com', 'secondemail@website.com', 'third@emailsite.com')); $emailItem->addFrom('from@sender.com'); //setting the From field using just the email. $emailItem->subject('Hello World!');

$emailItem->send();

Return values
mixed —

addCc()

addCc() - This adds Carbon Copy addresses to the message one at a time, so if you want to add multiple CC's it is best to run through a loop in order to put them in.

public addCc(string|array<string|int, mixed> $email[, string $name = null ]) : mixed
Parameters
$email : string|array<string|int, mixed>

This is the email address for the CC.

$name : string = null

This is the name associated with the above email address.

Tags
author

Tyler Smart tyleresmart@gmail.com

example

This will send a basic message, looping through an array of email addresses add adding them to the CC list.

$emailItem = new expMail();

$emailItem->addText('My Text '); $emailItem->addText('Line Two '); $emailItem->addText('Line Three ');

$ccs = array('a@website.com'=>'Mr A.', 'b@website.com'=>'Mr B.', 'c@website.com'=>'Mr C.', 'd@website.com'=>'Mr D.', 'e@website.com'=>'Mr E.', 'f@website.com'=>'Mr F.');

//add multiple cc recipients to the email foreach ($ccs as $email => $name) { $emailItem->addCc($email, $name); }

$emailItem->addTo(array('myemail@mysite.com', 'secondemail@website.com', 'third@emailsite.com')); $emailItem->addFrom('from@sender.com'); //setting the From field using just the email. $emailItem->subject('Hello World!');

$emailItem->send();

Return values
mixed —

addFrom()

addFrom() - This adds the singular From address, if you call it twice, it will replace the old from address.

public addFrom([string|array<string|int, mixed> $email = null ]) : mixed

It also sets the private var from with whatever you desire. This is a relic from the Swift 3.x days and should be gutted out the next time someone upgrades the mailer.

Parameters
$email : string|array<string|int, mixed> = null

This is the email address you want to use as the sender.

Tags
author

Tyler Smart tyleresmart@gmail.com

example

This will send a basic message, but you can see how the subject line works. $emailItem = new expMail(); $emailItem->addText('My Text '); $emailItem->addText('Line Two '); $emailItem->addText('Line Three '); $emailItem->addTo(array('myemail@mysite.com', 'secondemail@website.com', 'third@emailsite.com')); $emailItem->addFrom('from@sender.com'); //setting the From field using just the email. $emailItem->addFrom('from@sender.com', 'Mr. Sender'); //resetting the From field using the email and the name. $emailItem->subject('Hello World!'); $emailItem->send();

Return values
mixed —

addHeaders()

addHeaders() - Add text headers to the message. Limited to text headers for now.

public addHeaders(array<string|int, mixed> $headers) : mixed
Parameters
$headers : array<string|int, mixed>

Array of text headers to add to the message

Tags
author

Tyler Smart tyleresmart@gmail.com

example

This will include the passed HTML and will set it as an addition to the message body.

$emailItem = new expMail();

$emailItem->addHTML('

My Text

'); //This adds an alternate version if your email in HTML format

$emailItem->addTo('myemail@mysite.com'); $emailItem->addFrom('from@sender.com'); $emailItem->subject('Hello World!');

$headersToAdd = array('Your-Header-Name' => 'the header value', 'SecondHeader-Name' => '2nd header value'); $emailItem->addHeaders($headersToAdd);

$emailItem->send();

todo

add support for other types of headers mentioned below, and a second pass in value/switch to specify what kind headers you are adding

Text Headers

Text headers are the simplest type of Header. They contain textual information with no special information included within it for example the Subject header in a message.

Parameterized Headers

Parameterized headers are text headers that contain key-value parameters following the textual content. The Content-Type header of a message is a parameterized header since it contains charset information after the content type.

Date Headers

Date headers contains an RFC 2822 formatted date (i.e. what PHP's date('r') returns). They are used anywhere a date or time is needed to be presented as a message header.

Mailbox (e-mail address) Headers

Mailbox headers contain one or more email addresses, possibly with personalized names attached to them. The data on which they are modeled is represented by an associative array of email addresses and names.

ID Headers

ID headers contain identifiers for the entity (or the message). The most notable ID header is the Message-ID header on the message itself.

Path Headers

Path headers are like very-restricted mailbox headers. They contain a single email address with no associated name. The Return-Path header of a message is a path header.

Return values
mixed —

addHTML()

addHTML() - This function is similar to setHTMLBody except that it includes the HTML in the message body rather than sets it as default. Many mail clients will read the HTML over plain text as default behavior, so even if you use setTextBody and addHTML, they will default to reading the HTML.

public addHTML(string $html) : mixed

setHTMLBody is to be preferred as the default for setting the body of the email.

Parameters
$html : string

This is the html that you want added to the message.

Tags
author

Tyler Smart tyleresmart@gmail.com

example

This will include the passed HTML and will set it as an addition to the message body.

$emailItem = new expMail();

$emailItem->addHTML('

My Text

'); //This adds an alternate version if your email in HTML format

$emailItem->addTo('myemail@mysite.com'); $emailItem->addFrom('from@sender.com'); $emailItem->subject('Hello World!');

$emailItem->send();

You can also call the addHTML multiple times to append to the message:

$emailItem = new expMail();

$emailItem->addHTML('My HTML
'); $emailItem->addHTML('Line Two
'); $emailItem->addHTML('Line Three
');

$emailItem->addTo('myemail@mysite.com'); $emailItem->addFrom('from@sender.com'); $emailItem->subject('Hello World!');

$emailItem->send();

Return values
mixed —

addRaw()

addRaw() - This is a wrapper around setHTMLBody for backwards compatibility

public addRaw( $body) : mixed
Parameters
$body :
Tags
author

Tyler Smart tyleresmart@gmail.com

Return values
mixed —

addSubject()

subject() - This will set the subject of the message, ensuring first that message has been instantiated.

public addSubject(string $subj) : mixed
Parameters
$subj : string

This is the string that you want to be used as the subject for the message, it must be plain text.

Tags
author

Tyler Smart tyleresmart@gmail.com

example

This will send a basic message, but you can see how the subject line works. $emailItem = new expMail();

$emailItem->addText('My Text '); $emailItem->addText('Line Two '); $emailItem->addText('Line Three ');

$emailItem->addTo(array('myemail@mysite.com', 'secondemail@website.com', 'third@emailsite.com')); $emailItem->addFrom('from@sender.com'); $emailItem->subject('Hello World!');

$emailItem->send();

Return values
mixed —

addText()

addText() - This function is similar to the addHTML function above, it adds a plain text part to the message in case your recipient cannot receive HTML email, if you have added a text version of the email, they will have this to fall back on.

public addText(string $text) : mixed

Every email send out should have an HTML version and a TEXT version.

Parameters
$text : string

This is the text version of the email you are sending along with the HTML

Tags
author

Tyler Smart tyleresmart@gmail.com

example

This will set the message body in HTML and also include a text counterpart in case the recipient cannot view HTML.

$emailItem = new expMail();

$emailItem->setHTMLBody('My Text '); //This is an HTML version of the message $emailItem->addText('My Text '); //This adds a Text version in case they cannot read HTML

$emailItem->addTo('myemail@mysite.com'); $emailItem->addFrom('from@sender.com'); $emailItem->subject('Hello World!');

$emailItem->send();

Return values
mixed —

addTo()

addTo() - This adds people to the Recipient List in the To Field.

public addTo([array<string|int, mixed>|string $email = null ]) : mixed

If the first variable passed is an array, it assumes you are sending messages to multiple people. If you want to add people with their names associated with the email, you must use an outside for loop. This function does not yet support the parsing of associative arrays for a quick add to the To recipient list.

Parameters
$email : array<string|int, mixed>|string = null

This is the string or array to send email to

Tags
author

Tyler Smart tyleresmart@gmail.com

example

This will send a basic message, looping through an array of email addresses add adding them to the BCC list. $emailItem = new expMail(); $emailItem->addText('My Text '); $emailItem->addText('Line Two '); $emailItem->addText('Line Three '); $to_array = array('a@website.com'=>'Mr A.', 'b@website.com'=>'Mr B.', 'c@website.com'=>'Mr C.', 'd@website.com'=>'Mr D.', 'e@website.com'=>'Mr E.', 'f@website.com'=>'Mr F.'); //add multiple bcc recipients to the email foreach ($to_array as $email => $name) { $emailItem->addBcc($email, $name); } $emailItem->addFrom('from@sender.com'); $emailItem->subject('Hello World!'); $emailItem->send(); //You can also just specify the email without the name, like so: $emailItem = new expMail(); $emailItem->addText('My Text '); $emailItem->addText('Line Two '); $emailItem->addText('Line Three '); $emailItem->addTo('bob@smith.com'); $emailItem->addFrom('from@sender.com'); $emailItem->subject('Hello World!'); $emailItem->send(); //You can also send an array of email addresses as the first argument, like so: $emailItem = new expMail(); $emailItem->addText('My Text '); $emailItem->addText('Line Two '); $emailItem->addText('Line Three '); $emailItem->addTo(array('myemail@mysite.com', 'secondemail@website.com', 'third@emailsite.com')); $emailItem->addFrom('from@sender.com'); $emailItem->subject('Hello World!'); $emailItem->send();

todo

A nice future feature addition would be to allow the passing in of associative arrays like so: $emailsToSendTo = array('bob@smith.com'=>'Bob Smith', 'mary@smith.com'=>'Mary Smith'); $emailItem->addTo($emailsToSendTo); OR $emailItem->addTo('array('myemail@mysite.com'=>'Website Owner', 'secondemail@website.com'=>'Frank Jones'); Actually, cleanup should be done so that this function only takes associative arrays, and nothing else.

Return values
mixed —

attach_file_on_disk()

attach_file_on_disk() - This function will utilize the swift mailer's ability to attach files that are on disk, unlike the one above, which just attached one that is available in memory.

public attach_file_on_disk(string $file_to_attach, string $file_type) : mixed
Parameters
$file_to_attach : string

This is the path to the file that you want to attach to the message

$file_type : string

This is the MIME type of the file that you are attaching

Tags
author

Tyler Smart tyleresmart@gmail.com

example

This will show three different ways to attach files, two from a path on disk, and one from a url. //Create the attachment // * Note that you can technically leave the content-type parameter out $attachment = Swift_Attachment::fromPath('/path/to/image.jpg', 'image/jpeg');

//Attach it to the message $message->attach($attachment);

//The two statements above could be written in one line instead $message->attach(Swift_Attachment::fromPath('/path/to/image.jpg'));

//You can attach files from a URL if allow_url_fopen is on in php.ini $message->attach(Swift_Attachment::fromPath('http://site.tld/logo.png'));

Return values
mixed —

batchSend()

batchSend() - Does not seem to be working correctly. Use at your own risk!

public batchSend() : void

This should probably be taken out as it look like a failed attempt to use the old-school AntiFlood plugin This is leftover code from Swift 3.x

Tags
todo

Update this section to use batch processing properly

author

Tyler Smart tyleresmart@gmail.com

Return values
void —

clearBody()

clearBody() - This function will set the body of the message to empty, a blank text string

public clearBody() : mixed
Tags
author

Tyler Smart tyleresmart@gmail.com

Return values
mixed —

flushRecipients()

flushRecipients() - this will clear all of the recipients in the To array, ignoring CC and BCC

public flushRecipients() : mixed
Tags
author

Tyler Smart tyleresmart@gmail.com

example

This will set some recipients and then clear them $emailItem = new expMail();

$emailItem->addText('My Text '); $emailItem->addText('Line Two '); $emailItem->addText('Line Three ');

$emailItem->addTo('bob@smith.com', 'Bob Smith'); $emailItem->addTo('bob2@smith.com', 'Bob2 Smith'); $emailItem->addTo('bob3@smith.com', 'Bob3 Smith');

$emailItem->flushRecipients();

$emailItem->addTo('whataboutbob@smith.com', 'Frank Smith');

$emailItem->send();

Return values
mixed —

messageId()

messageId() - This will return the unique ID of the mail message.

public messageId() : array<string|int, mixed>

Courtesy of the underlying Swift mailer:

ID headers contain identifiers for the entity (or the message). The most notable ID header is the Message-ID header on the message itself.

An ID that exists inside an ID header looks more-or-less less like an email address. For example, 1234955437.499becad62ec2@example.org. The part to the left of the @ sign is usually unique, based on the * current time and some random factor. The part on the right is usually a domain name.

Tags
author

Tyler Smart tyleresmart@gmail.com

example

This returns the Message ID on the mail

$emailItem = new expMail();

$emailItem->addText('My Text '); $emailItem->addText('Line Two '); $emailItem->addText('Line Three ');

$emailItem->addTo(array('myemail@mysite.com', 'secondemail@website.com', 'third@emailsite.com')); $emailItem->addFrom('from@sender.com'); $emailItem->subject('Hello World!');

echo "$emailItem->messageID()";

$emailItem->send();

Return values
array<string|int, mixed> —

quickBatchSend()

quickBatchSend() - a quick way to send a batch of emails one at a time This function is similar to quickSend, but sends each email separately to protect others identity in the mailing

public quickBatchSend([array<string|int, mixed> $params = array() ]) : bool|int
Parameters
$params : array<string|int, mixed> = array()
Tags
author

Tyler Smart tyleresmart@gmail.com

Return values
bool|int —

quickSend()

quickSend() - This is a quick method for sending email messages. It only requires a message value be passed in an associative array, (or else the message fails immediately).

public quickSend([array<string|int, mixed> $params = array() ]) : int
Parameters
$params : array<string|int, mixed> = array()

This is the associative array required to send the email. The minimum basics for sending an email are: -html_message or -text_message If a from or a to is not specified, the send method will pull the default SMTP_FROMADDRESS from the site config. Usable parameters include: -to -from -subject -html_message -text_message -headers

Tags
todo

May add allowing a string param to be passed as the message (text_message) using all defaults to mail it.

author

Tyler Smart tyleresmart@gmail.com

example

This will send a quick message, showing you what basic fields are required.

$body = "My body."; $tos = explode(',', str_replace(' ', '', COMMENTS_NOTIFICATION_EMAIL)); //pull list of CSV emails from the site config $subject = "My subject";

$mail = new expMail(); $mail->quickSend(array( 'html_message'=>$body, 'to'=>$tos, 'from'=>trim(SMTP_FROMADDRESS), //pull EMAIL from site config 'subject'=>$subject, ));

(or even simpler) $mail = new expMail(); $mail->quickSend(array('html_message'=>'Hello'));

Return values
int —

number of recipients to which the email was successfully sent.

send()

send() - This is the main method for sending email messages.If there is not a from address, it defaults to the one stored in the Exponent config.

public send() : int
Tags
todo

This function needs some work, some error checking. It needs to check that all of the values necessary to send a basic message are present If they are not, the system should respond in a friendly manner that something went wrong. The underlying swift errors are ugly, and so no one should ever see them.

author

Tyler Smart tyleresmart@gmail.com

example

This will send a basic message, using the setHTMLBody method to set the text

$emailItem = new expMail();

$emailItem->setHTMLBody('

My Text

'); $emailItem->setTextBody('My Text ');

$emailItem->addTo('myemail@mysite.com'); $emailItem->addFrom('from@sender.com'); $emailItem->subject('Hello World!');

if($emailItem->send() < 1) //the number of recipients { eDebug "There was an error sending your message." }

Return values
int —

number of recipients to which the email was successfully sent.

setHTMLBody()

setHTMLBody() - This function sets the main version of the message to HTML.

public setHTMLBody(string $html) : mixed
Parameters
$html : string

This is the HTML that you want set as the body

Tags
author

Tyler Smart tyleresmart@gmail.com

example

This will set the message body to the HTML that is passed in. This is the standard way to set the email message body.

$emailItem = new expMail();

$emailItem->setHTMLBody('

My Text

'); //This sets the body to be an HTML version

$emailItem->addTo('myemail@mysite.com'); $emailItem->addFrom('from@sender.com'); $emailItem->subject('Hello World!');

$emailItem->send();

Return values
mixed —

setTextBody()

setTextBody() - This function sets the main version of the message to plain text. No HTML

public setTextBody(string $text) : mixed
Parameters
$text : string

This is the text version of the email you are sending

Tags
author

Tyler Smart tyleresmart@gmail.com

example

This will set the message body to plain text. Usually people do this because the recipient cannot read HTML email.

$emailItem = new expMail();

$emailItem->setTextBody('My Text '); //This adds a Text version in case they cannot read HTML

$emailItem->addTo('myemail@mysite.com'); $emailItem->addFrom('from@sender.com'); $emailItem->subject('Hello World!');

$emailItem->send();

Return values
mixed —

test()

test() - Does the mail system seem to be working correctly? This is useless for the Native mail system

public test() : mixed
Tags
todo

Update this section to use more error checking

Return values
mixed —

Search results