API Documentation
\
Charcoal
Email
Script
ServiceProvider

\Charcoal\EmailEmail

Default implementation of the `EmailInterface`.

Summary

Methods
Properties
Constants
__construct()
setData()
setCampaign()
campaign()
setTo()
addTo()
to()
setCc()
addCc()
cc()
setBcc()
addBcc()
bcc()
setFrom()
from()
setReplyTo()
replyTo()
setSubject()
subject()
setMsgHtml()
msgHtml()
setMsgTxt()
msgTxt()
setAttachments()
addAttachment()
attachments()
setLog()
log()
setTrack()
track()
send()
setSmtpOptions()
queue()
setTemplateData()
templateData()
viewController()
createConfig()
No public properties found
No constants found
emailToArray()
emailFromArray()
setTemplateFactory()
templateFactory()
setQueueItemFactory()
queueItemFactory()
setLogFactory()
logFactory()
generateCampaign()
generateMsgHtml()
stripHtml()
logSend()
logQueue()
getter()
setter()
No protected properties found
N/A
camelize()
$campaign
$to
$cc
$bcc
$from
$replyTo
$subject
$msgHtml
$msgTxt
$attachments
$log
$track
$templateData
$phpMailer
$templateFactory
$queueItemFactory
$logFactory
N/A

Properties

$campaign

$campaign : string

The campaign ID.

Type

string

$to

$to : array

The recipient email address(es).

Type

array

$cc

$cc : array

The CC recipient email address(es).

Type

array

$bcc

$bcc : array

The BCC recipient email address(es).

Type

array

$from

$from : string

The sender's email address.

Type

string

$replyTo

$replyTo : string

The email address to reply to the message.

Type

string

$subject

$subject : string

The email subject.

Type

string

$msgHtml

$msgHtml : string

The HTML message body.

Type

string

$msgTxt

$msgTxt : string

The plain-text message body.

Type

string

$attachments

$attachments : array

Type

array

$log

$log : boolean

Whether the email should be logged.

Type

boolean

$track

$track : boolean

Whether the email should be tracked.

Type

boolean

$templateData

$templateData : array

The data to pass onto the view controller.

Type

array

$phpMailer

$phpMailer : \PHPMailer\PHPMailer\PHPMailer

Type

\PHPMailer\PHPMailer\PHPMailer — PHP Mailer instance.

$templateFactory

$templateFactory : \Charcoal\Factory\FactoryInterface

Type

\Charcoal\Factory\FactoryInterface

$queueItemFactory

$queueItemFactory : \Charcoal\Factory\FactoryInterface

Type

\Charcoal\Factory\FactoryInterface

$logFactory

$logFactory : \Charcoal\Factory\FactoryInterface

Type

\Charcoal\Factory\FactoryInterface

Methods

__construct()

__construct(array  $data)

Construct a new Email object.

Parameters

array $data

Dependencies and settings.

setData()

setData(array  $data) : \Charcoal\Email\Email

Set the email's data.

Parameters

array $data

The data to set.

Returns

\Charcoal\Email\Email —

Chainable

setCampaign()

setCampaign(string  $campaign) : \Charcoal\Email\EmailInterface

Set the campaign ID.

Parameters

string $campaign

The campaign identifier.

Throws

\InvalidArgumentException

If the campaign is invalid.

Returns

\Charcoal\Email\EmailInterface —

Chainable

campaign()

campaign() : string

Get the campaign identifier.

If it has not been explicitely set, it will be auto-generated (with uniqid).

Returns

string

setTo()

setTo(string|array  $email) : \Charcoal\Email\EmailInterface

Set the recipient email address(es).

Parameters

string|array $email

The recipient email address(es).

Throws

\InvalidArgumentException

If the email address is invalid.

Returns

\Charcoal\Email\EmailInterface —

Chainable

addTo()

addTo(mixed  $email) : \Charcoal\Email\EmailInterface

Add a recipient email address.

Parameters

mixed $email

The recipient email address to add.

Throws

\InvalidArgumentException

If the email address is invalid.

Returns

\Charcoal\Email\EmailInterface —

Chainable

to()

to() : array<mixed,string>

Get the recipient's email address.

Returns

array<mixed,string>

setCc()

setCc(string|array  $email) : \Charcoal\Email\EmailInterface

Set the carbon copy (CC) recipient email address(es).

Parameters

string|array $email

The CC recipient email address(es).

Throws

\InvalidArgumentException

If the email address is invalid.

Returns

\Charcoal\Email\EmailInterface —

Chainable

addCc()

addCc(mixed  $email) : \Charcoal\Email\EmailInterface

Add a CC recipient email address.

Parameters

mixed $email

The CC recipient email address to add.

Throws

\InvalidArgumentException

If the email address is invalid.

Returns

\Charcoal\Email\EmailInterface —

Chainable

cc()

cc() : array<mixed,string>

Get the CC recipient's email address.

Returns

array<mixed,string>

setBcc()

setBcc(string|array  $email) : \Charcoal\Email\EmailInterface

Set the blind carbon copy (BCC) recipient email address(es).

Parameters

string|array $email

The BCC recipient email address(es).

Throws

\InvalidArgumentException

If the email address is invalid.

Returns

\Charcoal\Email\EmailInterface —

Chainable

addBcc()

addBcc(mixed  $email) : \Charcoal\Email\EmailInterface

Add a BCC recipient email address.

Parameters

mixed $email

The BCC recipient email address to add.

Throws

\InvalidArgumentException

If the email address is invalid.

Returns

\Charcoal\Email\EmailInterface —

Chainable

bcc()

bcc() : array<mixed,string>

Get the BCC recipient's email address.

Returns

array<mixed,string>

setFrom()

setFrom(string|array  $email) : \Charcoal\Email\EmailInterface

Set the sender's email address.

Parameters

string|array $email

An email address.

Throws

\InvalidArgumentException

If the email is not a string or an array.

Returns

\Charcoal\Email\EmailInterface —

Chainable

from()

from() : string

Get the sender's email address.

Returns

string

setReplyTo()

setReplyTo(mixed  $email) : \Charcoal\Email\EmailInterface

Set email address to reply to the message.

Parameters

mixed $email

The sender's "Reply-To" email address.

Throws

\InvalidArgumentException

If the email is not a string or an array.

Returns

\Charcoal\Email\EmailInterface —

Chainable

replyTo()

replyTo() : string

Get email address to reply to the message.

Returns

string

setSubject()

setSubject(string  $subject) : \Charcoal\Email\EmailInterface

Set the email subject.

Parameters

string $subject

The email subject.

Throws

\InvalidArgumentException

If the subject is not a string.

Returns

\Charcoal\Email\EmailInterface —

Chainable

subject()

subject() : string

Get the email subject.

Returns

string —

The emails' subject.

setMsgHtml()

setMsgHtml(string  $body) : \Charcoal\Email\EmailInterface

Set the email's HTML message body.

Parameters

string $body

The HTML message body.

Throws

\InvalidArgumentException

If the message is not a string.

Returns

\Charcoal\Email\EmailInterface —

Chainable

msgHtml()

msgHtml() : string

Get the email's HTML message body.

If the message is not explitely set, it will be auto-generated from a template view.

Returns

string

setMsgTxt()

setMsgTxt(string  $body) : \Charcoal\Email\EmailInterface

Set the email's plain-text message body.

Parameters

string $body

The message's text body.

Throws

\InvalidArgumentException

If the parameter is invalid.

Returns

\Charcoal\Email\EmailInterface —

Chainable

msgTxt()

msgTxt() : string

Get the email's plain-text message body.

If the plain-text message is not explitely set, it will be auto-generated from the HTML message.

Returns

string

setAttachments()

setAttachments(array  $attachments) : \Charcoal\Email\EmailInterface

Set the email's attachments.

Parameters

array $attachments

The file attachments.

Returns

\Charcoal\Email\EmailInterface —

Chainable

addAttachment()

addAttachment(mixed  $attachment) : \Charcoal\Email\EmailInterface

Add an attachment to the email.

Parameters

mixed $attachment

A single file attachment.

Returns

\Charcoal\Email\EmailInterface —

Chainable

attachments()

attachments() : array

Get the email's attachments.

Returns

array

setLog()

setLog(boolean  $log) : \Charcoal\Email\EmailInterface

Enable or disable logging for this particular email.

Parameters

boolean $log

The log flag.

Returns

\Charcoal\Email\EmailInterface —

Chainable

log()

log() : boolean

Determine if logging is enabled for this particular email.

Returns

boolean

setTrack()

setTrack(boolean  $track) : \Charcoal\Email\EmailInterface

Enable or disable tracking for this particular email.

Parameters

boolean $track

The track flag.

Returns

\Charcoal\Email\EmailInterface —

Chainable

track()

track() : boolean

Determine if tracking is enabled for this particular email.

Returns

boolean

send()

send() : boolean

Send the email to all recipients

Returns

boolean —

Success / Failure.

setSmtpOptions()

setSmtpOptions(\PHPMailer\PHPMailer\PHPMailer  $mail) : void

Set the SMTP's options for PHPMailer.

Parameters

\PHPMailer\PHPMailer\PHPMailer $mail

The PHPMailer to setup.

queue()

queue(mixed  $ts = null) : boolean

Enqueue the email for each recipient.

Parameters

mixed $ts

A date/time to initiate the queue processing.

Returns

boolean —

Success / Failure.

setTemplateData()

setTemplateData(array  $data) : \Charcoal\Email\Email

Set the template data for the view.

Parameters

array $data

The template data.

Returns

\Charcoal\Email\Email —

Chainable

templateData()

templateData() : array

Get the template data for the view.

Returns

array

viewController()

viewController() : \Charcoal\Email\TemplateInterface|array

Get the custom view controller for rendering the email's HTML message.

Unlike typical ViewableInterface objects, the view controller is not the email itself but an external "email" template.

Returns

\Charcoal\Email\TemplateInterface|array

createConfig()

createConfig() : \Charcoal\Email\EmailConfig

Temporary hack to fulfills the Configurable Interface.

Returns

\Charcoal\Email\EmailConfig

emailToArray()

emailToArray(mixed  $var) : string

Convert an email address (RFC822) into a proper array notation.

Parameters

mixed $var

An email array (containing an "email" key and optionally a "name" key).

Throws

\InvalidArgumentException

If the email is invalid.

Returns

string

emailFromArray()

emailFromArray(array  $arr) : string

Convert an email address array to a RFC-822 string notation.

Parameters

array $arr

An email array (containing an "email" key and optionally a "name" key).

Throws

\InvalidArgumentException

If the email array is invalid.

Returns

string

setTemplateFactory()

setTemplateFactory(\Charcoal\Factory\FactoryInterface  $factory) : \Charcoal\Email\Email

Parameters

\Charcoal\Factory\FactoryInterface $factory

The factory to use to create email template objects.

Returns

\Charcoal\Email\Email —

Chainable

templateFactory()

templateFactory() : \Charcoal\Factory\FactoryInterface

Returns

\Charcoal\Factory\FactoryInterface

setQueueItemFactory()

setQueueItemFactory(\Charcoal\Factory\FactoryInterface  $factory) : \Charcoal\Email\Email

Parameters

\Charcoal\Factory\FactoryInterface $factory

The factory to use to create email queue item objects.

Returns

\Charcoal\Email\Email —

Chainable

queueItemFactory()

queueItemFactory() : \Charcoal\Factory\FactoryInterface

Returns

\Charcoal\Factory\FactoryInterface

setLogFactory()

setLogFactory(\Charcoal\Factory\FactoryInterface  $factory) : \Charcoal\Email\Email

Parameters

\Charcoal\Factory\FactoryInterface $factory

The factory to use to create log objects.

Returns

\Charcoal\Email\Email —

Chainable

logFactory()

logFactory() : \Charcoal\Factory\FactoryInterface

Returns

\Charcoal\Factory\FactoryInterface

generateCampaign()

generateCampaign() : string

Generates a unique identifier ideal for a campaign ID.

Returns

string

generateMsgHtml()

generateMsgHtml() : string

Get the email's HTML message from the template, if applicable.

Returns

string

stripHtml()

stripHtml(string  $html) : string

Convert an HTML string to plain-text.

Parameters

string $html

The HTML string to convert.

Returns

string —

The resulting plain-text string.

logSend()

logSend(boolean  $result, mixed  $mailer) : void

Log the send event for each recipient.

Parameters

boolean $result

Success or failure.
mixed $mailer

The raw mailer.

logQueue()

logQueue() : void

Log the queue event.

getter()

getter(string  $key) : string

Allow an object to define how the key getter are called.

Parameters

string $key

The key to get the getter from.

Returns

string —

The getter method name, for a given key.

setter()

setter(string  $key) : string

Allow an object to define how the key setter are called.

Parameters

string $key

The key to get the setter from.

Returns

string —

The setter method name, for a given key.

camelize()

camelize(string  $str) : string

Transform a snake_case string to camelCase.

Parameters

string $str

The snake_case string to camelize.

Returns

string —

The camelCase string.