class Mailer

Class to prepare an email and send it through a sending strategy.

Currently, the following strategies are available (sub-namespace MailSenders) :

  • PHP Mail function
  • SMTP protocol
  • eml files stored in a folder
  • array of strings (useful for debugging)

Properties

protected MailSender $mailsender
static protected Cache $cacheAttachments
static protected Cache $cacheEmbeddings
static protected Mailer $defaultMailer

Methods

static Mailer
getDefault()

Get the default mailer (using PHP Mail function strategy)

static Cache
getAttachmentsCache()

Get cache for attachments

static Cache
getEmbeddingsCache()

Get cache for embeddings

static MailMultipart
addTextHtml(string $plain, string $html)

Create a email with a text/plain part and a text/html part

static MailMultipart
addTextHtmlFromHtml(string $html, string $htmltemplate = "%content%")

Create a email with a text/html part ; the text/plain part is built from the text/html part

static MailMultipart
addTextHtmlFromText(string $plain, string $htmltemplate = "%content%")

Create a email with a text/plain part ; the text/html part is built from the text/plain part

static MailMultipart
addAlternativeObject(MailContent $alt1, MailContent $alt2)

Create a multipart/alternative part

createText($text)

Create a text/plain part

createHtml($html)

Create a text/html part

static MailEmbedding
createEmbedding(string $embed, string $embedtype, string $cid)

Create an embedding object

static MailAttachment
createAttachment(string $file, string $filename, string $filetype)

Create an attachment object

static MailMultipart
addAttachments(MailContent $mail, string[][] $files)

Adds several attachments to an email

static MailMultipart
addAttachment(MailContent $mail, string $file, string $filename, string $filetype)

Add an attachment to an email

static MailMultipart
addAttachmentObject(MailContent $mail, MailAttachment $obj)

Add an attachment object to an email

static MailMultipart
addAttachmentObjects(MailContent $mail, MailAttachment[] $objs)

Add several attachment objects to an email

static MailMultipart
addEmbedding(MailContent $mail, string $embed, string $embedtype, string $cid)

Add an embedding to an email

static MailMultipart
addEmbeddingObject(MailContent $mail, MailEmbedding $obj)

Add an embedding object to an email

static MailMultipart
addEmbeddings(MailContent $mail, $embeds)

Adds several embeddings to an email

static MailMultipart
addEmbeddingObjects(MailContent $mail, MailEmbedding[] $objs)

Add several embedding objects to an email

static string[]
headersToArray(string $headers)

Transform a headers string to an associative array

static string
arrayToHeaders(string[] $headers)

Transform a array of headers to a string

static string
getHeader(string $headers, string $hkey)

Get a specific header value

static string
removeHeader(string $headers, string $hkey)

Remove a header

static string
addHeader($headers, $h)

Add a header to a headers string

static string
addHeaders(string $headers, string[] $hs)

Add several headers to existing headers string

static string
encodeSubject(string $sub)

Encode a subject to UTF8 + BASE64

static MailContent
patch(MailContent $mail, callable $fun, mixed $data)

Patch the email after it has been constructed.

static string
htmlMinify(string $html)

Minfy html code

static string
html2plain(string $html)

Convert an html string to plain text, removing tags

static string
plain2html(string $plain)

Convert a plain text string to html, ** replaced by B tags, == by red tags

static MailContent
render(MailContent $mail)

Add required technical headers (such as MIME version)

__construct(string $mailsender_name, string[]|NULL $params = NULL)

Constructor

bool
setMailSender(string $mailsender_name, string[]|NULL $params = NULL)

Set the email sending strategy

destruct()

Close email sending strategy (e.g. closing SMTP connections)

getMailSender()

Get current email sending strategy, or create a default one

bool|string
expressSendmail(string $content, string $from, string $to, string $subject, string[] $attachments = array(), bool $destruct = false)

Simple method call to send an email with content (either plain text or html) and optionnal attachments

bool|string
sendmail(MailContent $mail, string $from, string $to, string $subject, bool $destruct = false)

Send an email built with static building method of Mailer

bool|string
sendmail_raw(string $to, string $subject, string $mail, string $headers, bool $destruct = false)

Send raw mail

Details

at line 70
static Mailer getDefault()

Get the default mailer (using PHP Mail function strategy)

To create a Mailer instance with another strategy, create the instance through it's constructor, not getDefault()

Return Value

Mailer Returns a default instance, using PHP mail function strategy

at line 84
static Cache getAttachmentsCache()

Get cache for attachments

Return Value

Cache Cache for attachments

at line 98
static Cache getEmbeddingsCache()

Get cache for embeddings

Return Value

Cache Cache for embeddings

at line 114
static MailMultipart addTextHtml(string $plain, string $html)

Create a email with a text/plain part and a text/html part

Parameters

string $plain Plain text part
string $html HTML text part

Return Value

MailMultipart Returns a multipart/alternative part

at line 127
static MailMultipart addTextHtmlFromHtml(string $html, string $htmltemplate = "%content%")

Create a email with a text/html part ; the text/plain part is built from the text/html part

Parameters

string $html HTML text part
string $htmltemplate Template for html part ; use %content% in the template to set the placeholder for content

Return Value

MailMultipart Returns a multipart/alternative part

at line 141
static MailMultipart addTextHtmlFromText(string $plain, string $htmltemplate = "%content%")

Create a email with a text/plain part ; the text/html part is built from the text/plain part

Parameters

string $plain Plain text part
string $htmltemplate Template for html part ; use %content% in the template to set the placeholder for content

Return Value

MailMultipart Returns a multipart/alternative part

at line 159
static MailMultipart addAlternativeObject(MailContent $alt1, MailContent $alt2)

Create a multipart/alternative part

The text/plain and text/html part are in fact "childs" of a multipart/alternative part

Parameters

MailContent $alt1 Part 1
MailContent $alt2 Part 2

Return Value

MailMultipart Returns a multipart/alternative part

at line 170
static MailTextPlainContent createText($text)

Create a text/plain part

Parameters

$text

Return Value

MailTextPlainContent The plain text part

at line 181
static MailTextHtmlContent createHtml($html)

Create a text/html part

Parameters

$html

Return Value

MailTextHtmlContent The HTML part

at line 195
static MailEmbedding createEmbedding(string $embed, string $embedtype, string $cid)

Create an embedding object

Parameters

string $embed File path to the file to embed
string $embedtype Mime type of the embedding
string $cid Content-ID for embedding

Return Value

MailEmbedding Returns a embedding part

at line 209
static MailAttachment createAttachment(string $file, string $filename, string $filetype)

Create an attachment object

Parameters

string $file File path to the file to attach
string $filename File name used in the email (will appear in the email client of the recipient)
string $filetype Mime type of the attachment

Return Value

MailAttachment Returns a embedding part

at line 222
static MailMultipart addAttachments(MailContent $mail, string[][] $files)

Adds several attachments to an email

Parameters

MailContent $mail Email object
string[][] $files Array of array about files to attach ; provide file, filename and filetype values for each file

Return Value

MailMultipart Returns a multipart

at line 241
static MailMultipart addAttachment(MailContent $mail, string $file, string $filename, string $filetype)

Add an attachment to an email

Parameters

MailContent $mail Email object
string $file Filepath to file to attach
string $filename Filename to display to the user
string $filetype Mime type of the attachment

Return Value

MailMultipart Returns a multipart

at line 254
static MailMultipart addAttachmentObject(MailContent $mail, MailAttachment $obj)

Add an attachment object to an email

Parameters

MailContent $mail Email object
MailAttachment $obj Attachment object

Return Value

MailMultipart Returns a multipart

at line 267
static MailMultipart addAttachmentObjects(MailContent $mail, MailAttachment[] $objs)

Add several attachment objects to an email

Parameters

MailContent $mail Email object
MailAttachment[] $objs Attachment objects

Return Value

MailMultipart Returns a multipart

at line 282
static MailMultipart addEmbedding(MailContent $mail, string $embed, string $embedtype, string $cid)

Add an embedding to an email

Parameters

MailContent $mail Email object
string $embed Filepath to file to embed
string $embedtype Mime type of the embedding
string $cid Embedding CID

Return Value

MailMultipart Returns a multipart

at line 295
static MailMultipart addEmbeddingObject(MailContent $mail, MailEmbedding $obj)

Add an embedding object to an email

Parameters

MailContent $mail Email object
MailEmbedding $obj Embedding object

Return Value

MailMultipart Returns a multipart

at line 308
static MailMultipart addEmbeddings(MailContent $mail, $embeds)

Adds several embeddings to an email

Parameters

MailContent $mail
$embeds

Return Value

MailMultipart Returns a multipart

at line 325
static MailMultipart addEmbeddingObjects(MailContent $mail, MailEmbedding[] $objs)

Add several embedding objects to an email

Parameters

MailContent $mail Email object
MailEmbedding[] $objs Embedding objects

Return Value

MailMultipart Returns a multipart

at line 337
static string[] headersToArray(string $headers)

Transform a headers string to an associative array

Parameters

string $headers String of headers

Return Value

string[] Return an array of headers

at line 373
static string arrayToHeaders(string[] $headers)

Transform a array of headers to a string

Parameters

string[] $headers Array of headers

Return Value

string Return a string of headers

at line 393
static string getHeader(string $headers, string $hkey)

Get a specific header value

Parameters

string $headers Headers string
string $hkey Header name

Return Value

string Returns the value of header $hkey

at line 407
static string removeHeader(string $headers, string $hkey)

Remove a header

Parameters

string $headers Headers string
string $hkey Header name

Return Value

string New headers string

at line 436
static string addHeader($headers, $h)

Add a header to a headers string

Parameters

$headers
$h

Return Value

string New headers string

at line 472
static string addHeaders(string $headers, string[] $hs)

Add several headers to existing headers string

Parameters

string $headers Headers string
string[] $hs Array of headers string name: value

Return Value

string New headers string

at line 489
static string encodeSubject(string $sub)

Encode a subject to UTF8 + BASE64

Parameters

string $sub Subject to encode

Return Value

string Subject encoded with UTF8 charset and BASE64 transfer-encoding

at line 510
static MailContent patch(MailContent $mail, callable $fun, mixed $data)

Patch the email after it has been constructed.

May be used to add tracking data to links after building process. Callback $fun should have the following signature :

  • $code : will contain the email part
  • $ctype : will be set with the email part content-type
  • $data : $data parameter of patch method ; useful to transmit work data to callback

Parameters

MailContent $mail Email to process
callable $fun Callback (see method summary for it's parameters)
mixed $data Data to pass to the callback

Return Value

MailContent Returns the $mail parameters, with it's content updated

at line 545
static string htmlMinify(string $html)

Minfy html code

Parameters

string $html HTML text to minify

Return Value

string Returns a string with no newlines, tabs and removes duplicate spaces

at line 562
static string html2plain(string $html)

Convert an html string to plain text, removing tags

Parameters

string $html HTML string

Return Value

string Returns plain text

at line 635
static string plain2html(string $plain)

Convert a plain text string to html, ** replaced by B tags, == by red tags

Parameters

string $plain Plain text to convert to HTML formatting

Return Value

string HTML formatted text

at line 670
static MailContent render(MailContent $mail)

Add required technical headers (such as MIME version)

Parameters

MailContent $mail Mail object to process

Return Value

MailContent Returns mail object modified

at line 689
__construct(string $mailsender_name, string[]|NULL $params = NULL)

Constructor

Parameters

string $mailsender_name Email sending strategy name
string[]|NULL $params Array of parameters for the strategy

at line 702
bool setMailSender(string $mailsender_name, string[]|NULL $params = NULL)

Set the email sending strategy

Parameters

string $mailsender_name Email sending strategy name
string[]|NULL $params Array of parameters for the strategy

Return Value

bool Returns TRUE if mail sending strategy is ready after its creation, or not

at line 713
destruct()

Close email sending strategy (e.g. closing SMTP connections)

at line 724
MailSender getMailSender()

Get current email sending strategy, or create a default one

Return Value

MailSender Returns the mail sender strategy currently defined ; if none, MailSenders\PHPMail_MailSender is used

at line 744
bool|string expressSendmail(string $content, string $from, string $to, string $subject, string[] $attachments = array(), bool $destruct = false)

Simple method call to send an email with content (either plain text or html) and optionnal attachments

Parameters

string $content String with content (HTML or plain text)
string $from Email sender
string $to Email recipient
string $subject Email subject
string[] $attachments Array of filepaths
bool $destruct Set this parameter to TRUE to have the strategy destroyed after sending the email

Return Value

bool|string Returns FALSE if mail was sent, an error message if someting went wrong

at line 786
bool|string sendmail(MailContent $mail, string $from, string $to, string $subject, bool $destruct = false)

Send an email built with static building method of Mailer

Parameters

MailContent $mail Mail object to send
string $from Email sender
string $to Email recipient
string $subject Email subject
bool $destruct Set this parameter to TRUE to have the strategy destroyed after sending the email

Return Value

bool|string Returns FALSE if mail was sent, an error message if someting went wrong

at line 806
bool|string sendmail_raw(string $to, string $subject, string $mail, string $headers, bool $destruct = false)

Send raw mail

Parameters

string $to Email recipient
string $subject Email subject
string $mail Email body as text
string $headers Headers string
bool $destruct Set this parameter to TRUE to have the strategy destroyed after sending the email

Return Value

bool|string Returns FALSE if mail was sent, an error message if someting went wrong