Class Email

CakePHP Email class.

This class is used for sending Internet Message Format based on the standard outlined in https://www.rfc-editor.org/rfc/rfc2822.txt

Configuration

Configuration for Email is managed by Email::config() and Email::configTransport(). Email::config() can be used to add or read a configuration profile for Email instances. Once made configuration profiles can be used to re-use across various email messages your application sends.

Namespace: Cake\Mailer

Constants summary

string

EMAIL_PATTERN

'/^((?:[\\p{L}0-9.!#$%&\'*+\\/=?^_`{|}~-]+)*@[\\p{L}0-9-._]+)$/ui'
int

LINE_LENGTH_MUST

998
int

LINE_LENGTH_SHOULD

78
string

MESSAGE_HTML

'html'
string

MESSAGE_TEXT

'text'

Properties summary

$_appCharset protected

string|null

The application wide charset, used to encode headers and body
$_attachments protected

array

List of files that should be attached to the email.
$_bcc protected

array

Blind Carbon Copy
$_boundary protected

string|null

If set, boundary to use for multipart mime messages
$_cc protected

array

Carbon Copy
$_charset8bit protected

array

8Bit character sets
$_config protected static

array

Configuration sets.
$_contentTypeCharset protected

array

Define Content-Type charset name
$_domain protected

string

Domain for messageId generation.
$_dsnClassMap protected static

string[]

An array mapping url schemes to fully qualified Transport class names.
$_emailFormat protected

string

What format should the email be sent in
$_emailFormatAvailable protected

array

Available formats to be sent.
$_emailPattern protected

string

Regex for email validation
$_from protected

array

The mail which the email is sent from
$_headers protected

array

Associative array of a user defined headers Keys will be prefixed 'X-' as per RFC2822 Section 4.7.5
$_htmlMessage protected

string

Html message
$_message protected

array

Final message to send
$_messageId protected

bool|string

Message ID
$_priority protected

int|null

Contains the optional priority of the email.
$_profile protected

array

A copy of the configuration profile for this instance. This copy can be modified with Email::profile().
$_readReceipt protected

array

The read receipt email
$_replyTo protected

array

The email the recipient will reply to
$_returnPath protected

array
The mail that will be used in case of any errors like
- Remote mailserver down
- Remote user has exceeded his quota
- Unknown user
$_sender protected

array

The sender email
$_subject protected

string

The subject of the email
$_textMessage protected

string

Text message
$_to protected

array

Recipient of the email
$_transferEncodingAvailable protected

array

Available encoding to be set for transfer.
$_transport protected

\Cake\Mailer\AbstractTransport|null

The transport instance to use for sending mail.
$_validViewOptions public

array
$_viewBuilder protected

\Cake\View\ViewBuilder

The view builder instance being used.
$charset public

string

Charset the email body is sent in
$headerCharset public

string|null

Charset the email header is sent in If null, the $charset property will be used as default
$transferEncoding protected

string|null

The email transfer encoding used.
$viewClass public

string|null

The name of default View class.
$viewVars public

array

Variables for the view.

Method Summary

__clone() public

Clone ViewBuilder instance when email object is cloned.
__construct() public

Constructor
_addEmail() protected

Add email
_applyConfig() protected

Apply the config to an instance
_attachFiles() protected

Attach non-embedded files by adding file contents inside boundaries.
_attachInlineFiles() protected

Attach inline/embedded files to the message.
_checkViewVars() protected

Iterates through hash to clean up and normalize.
_createBoundary() protected

Create unique boundary identifier
_decode() protected

Decode the specified string
_encode() protected

Encode the specified string using the current charset
_encodeString() protected

Translates a string for one charset to another if the App.encoding value differs and the mb_convert_encoding function exists
_formatAddress() protected

Format addresses
_getContentTransferEncoding() protected

Return the Content-Transfer Encoding value based on the set transferEncoding or set charset.
_getContentTypeCharset() protected

Return charset value for Content-Type.
_getTypes() protected

Gets the text body types that are in this email message
_logDelivery() protected

Log the email message delivery.
_readFile() protected

Read the file contents and return a base64 version of the file contents.
_render() protected

Render the body of the email.
_renderTemplates() protected

Build and set all the view properties needed to render the templated emails.
_setEmail() protected

Set email
_setEmailSingle() protected

Set only 1 email
_validateEmail() protected

Validate email address
_wrap() protected

Wrap the message to follow the RFC 2822 - 2.1.1
addAttachments() public

Add attachments
addBcc() public

Add Bcc
addCc() public

Add Cc
addHeaders() public

Add header for the message
addTo() public

Add To
attachments() public

Add attachments to the email message
bcc() public

Bcc
cc() public

Cc
charset() public

Charset setter/getter
config() public static

This method can be used to define configuration adapters for an application or read existing configuration.
configTransport() public static

Add or read transport configuration.
configured() public static

Returns an array containing the named configurations
configuredTransport() public static

Returns an array containing the named transport configurations
createFromArray() public

Configures an email instance object from serialized config.
createView() public

Constructs the view class instance based on the current configuration.
deliver() public static

Static method to fast create an instance of \Cake\Mailer\Email
domain() public

Domain as top level (the part after @)
drop() public static

Drops a constructed adapter.
dropTransport() public static

Delete transport configuration.
dsnClassMap() public static

Returns or updates the DSN class map for this class.
emailFormat() public

Email format
emailPattern() public

EmailPattern setter/getter
flatten() protected

Converts given value to string
from() public

From
getAttachments() public

Gets attachments to the email message.
getBcc() public

Gets "bcc" address.
getCc() public

Gets "cc" address.
getCharset() public

Charset getter.
getConfig() public static

Reads existing configuration.
getConfigOrFail() public static

Reads existing configuration for a specific key.
getConfigTransport() public static

Gets current transport configuration.
getDomain() public

Gets domain.
getDsnClassMap() public static

Returns the DSN class map for this class.
getEmailFormat() public

Gets email format.
getEmailPattern() public

EmailPattern setter/getter
getFrom() public

Gets "from" address.
getHeaderCharset() public

HeaderCharset getter.
getHeaders() public

Get list of headers
getHelpers() public

Gets helpers to be used when rendering.
getLayout() public

Gets layout.
getMessageId() public

Gets message ID.
getOriginalSubject() public

Get original subject without encoding
getPriority() public

Gets priority.
getProfile() public

Gets the configuration profile to use for this instance.
getReadReceipt() public

Gets Read Receipt (Disposition-Notification-To header).
getReplyTo() public

Gets "Reply-To" address.
getReturnPath() public

Gets return path.
getSender() public

Gets the "sender" address. See rfc link below for full explanation.
getSubject() public

Gets subject.
getTemplate() public

Gets template.
getTheme() public

Gets theme to use when rendering.
getTo() public

Gets "to" address
getTransferEncoding() public

TransferEncoding getter.
getTransport() public

Gets the transport.
getViewRenderer() public

Gets view class for render.
getViewVars() public

Gets variables to be set on render.
headerCharset() public

HeaderCharset setter/getter
helpers() public

Helpers to be used in render
jsonSerialize() public

Serializes the email object to a value that can be natively serialized and re-used to clone this email instance.
message() public

Get generated message (used by transport classes)
messageId() public

Message-ID
parseDsn() public static

Parses a DSN into a valid connection configuration
profile() public

Get/Set the configuration profile to use for this instance.
readReceipt() public

Read Receipt (Disposition-Notification-To header)
replyTo() public

Reply-To
reset() public

Reset all the internal variables to be able to send out a new email.
returnPath() public

Return Path
send() public

Send an email using the specified content, template and layout
sender() public

Sender
serialize() public

Serializes the Email object.
set() public

Saves a variable or an associative array of variables for use inside a template.
setAttachments() public

Add attachments to the email message
setBcc() public

Sets "bcc" address.
setCc() public

Sets "cc" address.
setCharset() public

Charset setter.
setConfig() public static

This method can be used to define configuration adapters for an application.
setConfigTransport() public static

Sets transport configuration.
setDomain() public

Sets domain.
setDsnClassMap() public static

Updates the DSN class map for this class.
setEmailFormat() public

Sets email format.
setEmailPattern() public

EmailPattern setter/getter
setFrom() public

Sets "from" address.
setHeaderCharset() public

HeaderCharset setter.
setHeaders() public

Sets headers for the message
setHelpers() public

Sets helpers to be used when rendering.
setLayout() public

Sets layout.
setMessageId() public

Sets message ID.
setPriority() public

Sets priority.
setProfile() public

Sets the configuration profile to use for this instance.
setReadReceipt() public

Sets Read Receipt (Disposition-Notification-To header).
setReplyTo() public

Sets "Reply-To" address.
setReturnPath() public

Return Path
setSender() public

Sets the "sender" address. See rfc link below for full explanation.
setSubject() public

Sets subject.
setTemplate() public

Sets template.
setTheme() public

Sets theme to use when rendering.
setTo() public

Sets "to" address.
setTransferEncoding() public

TransferEncoding setter.
setTransport() public

Sets the transport.
setViewRenderer() public

Sets view class for render.
setViewVars() public

Sets variables to be set on render.
subject() public

Get/Set Subject.
template() public

Template and layout
theme() public

Theme to use when rendering
to() public

To
transport() public

Get/set the transport.
unserialize() public

Unserializes the Email object.
viewBuilder() public

Get the view builder being used.
viewOptions() public

Get/Set valid view options in the object's _validViewOptions property. The property is created as an empty array if it is not set. If called without any parameters it will return the current list of valid view options. See createView().
viewRender() public

View class for render
viewVars() public

Variables to be set on render

Method Detail

__clone() public

__clone()

Clone ViewBuilder instance when email object is cloned.

__construct() public

__construct(mixed $config)

Constructor

Parameters

array|string|null $config optional: Array of configs, or string to load configs from app.php

_addEmail() protected

_addEmail(mixed $varName, mixed $email, mixed $name)

Add email

Parameters

string $varName: Property name
string|array $email: String with email, Array with email as key, name as value or email as value (without name)
string $name: Name

Returns

$this

Throws

InvalidArgumentException

_applyConfig() protected

_applyConfig(mixed $config)

Apply the config to an instance

Parameters

string|array $config: Configuration options.

Throws

InvalidArgumentException
When using a configuration that doesn't exist.

_attachFiles() protected

_attachFiles(mixed $boundary)

Attach non-embedded files by adding file contents inside boundaries.

Parameters

string|null $boundary optional: Boundary to use. If null, will default to $this->_boundary

Returns

array

An array of lines to add to the message

_attachInlineFiles() protected

_attachInlineFiles(mixed $boundary)

Attach inline/embedded files to the message.

Parameters

string|null $boundary optional: Boundary to use. If null, will default to $this->_boundary

Returns

array

An array of lines to add to the message

_checkViewVars() protected

_checkViewVars(mixed $item, mixed $key)

Iterates through hash to clean up and normalize.

Parameters

mixed $item: Reference to the view var value.
string $key: View var key.

_createBoundary() protected

_createBoundary()

Create unique boundary identifier

_decode() protected

_decode(mixed $text)

Decode the specified string

Parameters

string $text: String to decode

Returns

string

Decoded string

_encode() protected

_encode(mixed $text)

Encode the specified string using the current charset

Parameters

string $text: String to encode

Returns

string

Encoded string

_encodeString() protected

_encodeString(mixed $text, mixed $charset)

Translates a string for one charset to another if the App.encoding value differs and the mb_convert_encoding function exists

Parameters

string $text: The text to be converted
string $charset: the target encoding

Returns

string

_formatAddress() protected

_formatAddress(mixed $address)

Format addresses

If the address contains non alphanumeric/whitespace characters, it will be quoted as characters like : and , are known to cause issues in address header fields.

Parameters

array $address: Addresses to format.

Returns

array

_getContentTransferEncoding() protected

_getContentTransferEncoding()

Return the Content-Transfer Encoding value based on the set transferEncoding or set charset.

Returns

string

_getContentTypeCharset() protected

_getContentTypeCharset()

Return charset value for Content-Type.

Checks fallback/compatibility types which include workarounds for legacy japanese character sets.

Returns

string

_getTypes() protected

_getTypes()

Gets the text body types that are in this email message

Returns

array

Array of types. Valid types are 'text' and 'html'

_logDelivery() protected

_logDelivery(mixed $contents)

Log the email message delivery.

Parameters

array $contents: The content with 'headers' and 'message' keys.

_readFile() protected

_readFile(mixed $path)

Read the file contents and return a base64 version of the file contents.

Parameters

string $path: The absolute path to the file to read.

Returns

string

File contents in base64 encoding

_render() protected

_render(mixed $content)

Render the body of the email.

Parameters

array $content: Content to render

Returns

array

Email body ready to be sent

_renderTemplates() protected

_renderTemplates(mixed $content)

Build and set all the view properties needed to render the templated emails.

If there is no template set, the $content will be returned in a hash of the text content types for the email.

Parameters

string $content: The content passed in from send() in most cases.

Returns

array

The rendered content with html and text keys.

_setEmail() protected

_setEmail(mixed $varName, mixed $email, mixed $name)

Set email

Parameters

string $varName: Property name
string|array $email: String with email, Array with email as key, name as value or email as value (without name)
string $name: Name

Returns

$this

Throws

InvalidArgumentException

_setEmailSingle() protected

_setEmailSingle(mixed $varName, mixed $email, mixed $name, mixed $throwMessage)

Set only 1 email

Parameters

string $varName: Property name
string|array $email: String with email, Array with email as key, name as value or email as value (without name)
string $name: Name
string $throwMessage: Exception message

Returns

$this

Throws

InvalidArgumentException

_validateEmail() protected

_validateEmail(mixed $email, mixed $context)

Validate email address

Parameters

string $email: Email address to validate
string $context: Which property was set

Throws

InvalidArgumentException
If email address does not validate

_wrap() protected

_wrap(mixed $message, mixed $wrapLength)

Wrap the message to follow the RFC 2822 - 2.1.1

Parameters

string $message: Message to wrap
int $wrapLength optional: The line length

Returns

array

Wrapped message

addAttachments() public

addAttachments(mixed $attachments)

Add attachments

Parameters

string|array $attachments: String with the filename or array with filenames

Returns

$this

Throws

InvalidArgumentException

addBcc() public

addBcc(mixed $email, mixed $name)

Add Bcc

Parameters

string|array $email: Null to get, String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

$this

addCc() public

addCc(mixed $email, mixed $name)

Add Cc

Parameters

string|array $email: Null to get, String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

$this

addHeaders() public

addHeaders(array $headers)

Add header for the message

Parameters

array $headers: Headers to set.

Returns

$this

addTo() public

addTo(mixed $email, mixed $name)

Add To

Parameters

string|array $email: Null to get, String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

$this

attachments() public

attachments(mixed $attachments)

Add attachments to the email message

Attachments can be defined in a few forms depending on how much control you need:

Attach a single file:

$email->setAttachments('path/to/file');

Attach a file with a different filename:

$email->setAttachments(['custom_name.txt' => 'path/to/file.txt']);

Attach a file and specify additional properties:

$email->setAttachments(['custom_name.png' => [
     'file' => 'path/to/file',
     'mimetype' => 'image/png',
     'contentId' => 'abc123',
     'contentDisposition' => false
   ]
]);

Attach a file from string and specify additional properties:

$email->setAttachments(['custom_name.png' => [
     'data' => file_get_contents('path/to/file'),
     'mimetype' => 'image/png'
   ]
]);

The contentId key allows you to specify an inline attachment. In your email text, you can use <img src="cid:abc123" /> to display the image inline.

The contentDisposition key allows you to disable the Content-Disposition header, this can improve attachment compatibility with outlook email clients.

Parameters

string|array|null $attachments optional: String with the filename or array with filenames

Returns

array|$this

Either the array of attachments when getting or $this when setting.

Throws

InvalidArgumentException

bcc() public

bcc(mixed $email, mixed $name)

Bcc

Parameters

string|array|null $email optional: Null to get, String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

array|$this

cc() public

cc(mixed $email, mixed $name)

Parameters

string|array|null $email optional: Null to get, String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

array|$this

charset() public

charset(mixed $charset)

Charset setter/getter

Parameters

string|null $charset optional: Character set.

Returns

string

Charset

config() public static

config(mixed $key, mixed $config)

This method can be used to define configuration adapters for an application or read existing configuration.

To change an adapter's configuration at runtime, first drop the adapter and then reconfigure it.

Adapters will not be constructed until the first operation is done.

Usage

Assuming that the class' name is Cache the following scenarios are supported:

Reading config data back:

Cache::config('default');

Setting a cache engine up.

Cache::config('default', $settings);

Injecting a constructed adapter in:

Cache::config('default', $instance);

Configure multiple adapters at once:

Cache::config($arrayOfConfig);

Parameters

string|array $key: The name of the configuration, or an array of multiple configs.
array|null $config optional: An array of name => configuration data for adapter.

Returns

array|null

Null when adding configuration or an array of configuration data when reading.

Throws

BadMethodCallException
When trying to modify an existing config.

configTransport() public static

configTransport(mixed $key, mixed $config)

Add or read transport configuration.

Use this method to define transports to use in delivery profiles. Once defined you cannot edit the configurations, and must use Email::dropTransport() to flush the configuration first.

When using an array of configuration data a new transport will be constructed for each message sent. When using a Closure, the closure will be evaluated for each message.

The className is used to define the class to use for a transport. It can either be a short name, or a fully qualified classname

Parameters

string|array $key: The configuration name to read/write. Or an array of multiple transports to set.
array|\Cake\Mailer\AbstractTransport|null $config optional: Either an array of configuration data, or a transport instance.

Returns

array|null

Either null when setting or an array of data when reading.

Throws

BadMethodCallException
When modifying an existing configuration.

configured() public static

configured()

Returns an array containing the named configurations

Returns

string[]

Array of configurations.

configuredTransport() public static

configuredTransport()

Returns an array containing the named transport configurations

Returns

array

Array of configurations.

createFromArray() public

createFromArray(mixed $config)

Configures an email instance object from serialized config.

Parameters

array $config: Email configuration array.

Returns

$this

Configured email instance.

createView() public

createView(mixed $viewClass)

Constructs the view class instance based on the current configuration.

Parameters

string|null $viewClass optional: Optional namespaced class name of the View class to instantiate.

Returns

\Cake\View\View

Throws

Cake\View\Exception\MissingViewException
If view class was not found.

deliver() public static

deliver(mixed $to, mixed $subject, mixed $message, mixed $config, mixed $send)

Static method to fast create an instance of \Cake\Mailer\Email

Parameters

string|array|null $to optional: Address to send (see Cake\Mailer\Email::to()). If null, will try to use 'to' from transport config
string|null $subject optional: String of subject or null to use 'subject' from transport config
string|array|null $message optional: String with message or array with variables to be used in render
string|array $config optional: String to use Email delivery profile from app.php or array with configs
bool $send optional: Send the email or just return the instance pre-configured

Returns

static

Instance of Cake\Mailer\Email

Throws

InvalidArgumentException

domain() public

domain(mixed $domain)

Domain as top level (the part after @)

Parameters

string|null $domain optional: Manually set the domain for CLI mailing

Returns

string|$this

drop() public static

drop(mixed $config)

Drops a constructed adapter.

If you wish to modify an existing configuration, you should drop it, change configuration and then re-add it.

If the implementing objects supports a $_registry object the named configuration will also be unloaded from the registry.

Parameters

string $config: An existing configuration you wish to remove.

Returns

bool

Success of the removal, returns false when the config does not exist.

dropTransport() public static

dropTransport(mixed $key)

Delete transport configuration.

Parameters

string $key: The transport name to remove.

dsnClassMap() public static

dsnClassMap(array $map)

Returns or updates the DSN class map for this class.

Parameters

string[]|null $map optional: Additions/edits to the class map to apply.

Returns

string[]

emailFormat() public

emailFormat(mixed $format)

Email format

Parameters

string|null $format optional: Formatting string.

Returns

string|$this

Throws

InvalidArgumentException

emailPattern() public

emailPattern(mixed $regex)

EmailPattern setter/getter

Parameters

string|false|null $regex optional: The pattern to use for email address validation, null to unset the pattern and make use of filter_var() instead, false or nothing to return the current value

Returns

string|$this

flatten() protected

flatten(mixed $value)

Converts given value to string

Parameters

string|array $value: The value to convert

Returns

string

from() public

from(mixed $email, mixed $name)

From

Parameters

string|array|null $email optional: Null to get, String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

array|$this

Throws

InvalidArgumentException

getAttachments() public

getAttachments()

Gets attachments to the email message.

Returns

array

Array of attachments.

getBcc() public

getBcc()

Gets "bcc" address.

Returns

array

getCc() public

getCc()

Gets "cc" address.

Returns

array

getCharset() public

getCharset()

Charset getter.

Returns

string

Charset

getConfig() public static

getConfig(mixed $key)

Reads existing configuration.

Parameters

string $key: The name of the configuration.

Returns

mixed|null

Configuration data at the named key or null if the key does not exist.

getConfigOrFail() public static

getConfigOrFail(mixed $key)

Reads existing configuration for a specific key.

The config value for this key must exist, it can never be null.

Parameters

string|null $key: The name of the configuration.

Returns

mixed

Configuration data at the named key.

Throws

InvalidArgumentException
If value does not exist.

getConfigTransport() public static

getConfigTransport(mixed $key)

Gets current transport configuration.

Parameters

string $key: The configuration name to read.

Returns

array|null

Transport config.

getDomain() public

getDomain()

Gets domain.

Returns

string

getDsnClassMap() public static

getDsnClassMap()

Returns the DSN class map for this class.

Returns

string[]

getEmailFormat() public

getEmailFormat()

Gets email format.

Returns

string

getEmailPattern() public

getEmailPattern()

EmailPattern setter/getter

Returns

string

getFrom() public

getFrom()

Gets "from" address.

Returns

array

getHeaderCharset() public

getHeaderCharset()

HeaderCharset getter.

Returns

string

Charset

getHeaders() public

getHeaders(array $include)

Get list of headers

Includes:

from
replyTo
readReceipt
returnPath
to
cc
bcc
subject

Parameters

array $include optional: List of headers.

Returns

array

getHelpers() public

getHelpers()

Gets helpers to be used when rendering.

Returns

array

getLayout() public

getLayout()

Gets layout.

Returns

string

getMessageId() public

getMessageId()

Gets message ID.

Returns

bool|string

getOriginalSubject() public

getOriginalSubject()

Get original subject without encoding

Returns

string

Original subject

getPriority() public

getPriority()

Gets priority.

Returns

int

getProfile() public

getProfile()

Gets the configuration profile to use for this instance.

Returns

string|array

getReadReceipt() public

getReadReceipt()

Gets Read Receipt (Disposition-Notification-To header).

Returns

array

getReplyTo() public

getReplyTo()

Gets "Reply-To" address.

Returns

array

getReturnPath() public

getReturnPath()

Gets return path.

Returns

array

getSender() public

getSender()

Gets the "sender" address. See rfc link below for full explanation.

getTransferEncoding()

TransferEncoding getter.

Returns

string|null

Encoding

getTransport() public

getTransport()

Gets the transport.

Returns

\Cake\Mailer\AbstractTransport

getViewRenderer() public

getViewRenderer()

Gets view class for render.

Returns

string

getViewVars() public

getViewVars()

Gets variables to be set on render.

Returns

array

headerCharset() public

headerCharset(mixed $charset)

HeaderCharset setter/getter

Parameters

string|null $charset optional: Character set.

Returns

string

Charset

helpers() public

helpers(mixed $helpers)

Helpers to be used in render

Parameters

array|null $helpers optional: Helpers list.

Returns

array|$this

jsonSerialize() public

jsonSerialize()

Serializes the email object to a value that can be natively serialized and re-used to clone this email instance.

It has certain limitations for viewVars that are good to know:

ORM\Query executed and stored as resultset
SimpleXMLElements stored as associative array
Exceptions stored as strings
Resources, \Closure and \PDO are not supported.

Returns

array

Serializable array of configuration properties.

Throws

Exception
When a view var object can not be properly serialized.

message() public

message(mixed $type)

Get generated message (used by transport classes)

Parameters

string|null $type optional: Use MESSAGE_* constants or null to return the full message as array

Returns

string|array

String if type is given, array if type is null

messageId() public

messageId(mixed $message)

Message-ID

Parameters

bool|string|null $message optional: True to generate a new Message-ID, False to ignore (not send in email), String to set as Message-ID

Returns

bool|string|$this

Throws

InvalidArgumentException

parseDsn() public static

parseDsn(mixed $dsn)

Parses a DSN into a valid connection configuration

This method allows setting a DSN using formatting similar to that used by PEAR::DB. The following is an example of its usage:

$dsn = 'mysql://user:pass@localhost/database?';
$config = ConnectionManager::parseDsn($dsn);

$dsn = 'Cake\Log\Engine\FileLog://?types=notice,info,debug&file=debug&path=LOGS';
$config = Log::parseDsn($dsn);

$dsn = 'smtp://user:secret@localhost:25?timeout=30&client=null&tls=null';
$config = Email::parseDsn($dsn);

$dsn = 'file:///?className=\My\Cache\Engine\FileEngine';
$config = Cache::parseDsn($dsn);

$dsn = 'File://?prefix=myapp_cake_core_&serialize=true&duration=+2 minutes&path=/tmp/persistent/';
$config = Cache::parseDsn($dsn);

For all classes, the value of scheme is set as the value of both the className unless they have been otherwise specified.

Note that querystring arguments are also parsed and set as values in the returned configuration.

Parameters

string $dsn: The DSN string to convert to a configuration array

Returns

array

The configuration array to be stored after parsing the DSN

Throws

InvalidArgumentException
If not passed a string, or passed an invalid string

profile() public

profile(mixed $config)

Get/Set the configuration profile to use for this instance.

Parameters

array|string|null $config optional: String with configuration name, or an array with config or null to return current config.

Returns

string|array|$this

readReceipt() public

readReceipt(mixed $email, mixed $name)

Read Receipt (Disposition-Notification-To header)

Parameters

string|array|null $email optional: Null to get, String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

array|$this

Throws

InvalidArgumentException

replyTo() public

replyTo(mixed $email, mixed $name)

Reply-To

Parameters

string|array|null $email optional: Null to get, String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

array|$this

Throws

InvalidArgumentException

reset() public

reset()

Reset all the internal variables to be able to send out a new email.

Returns

$this

returnPath() public

returnPath(mixed $email, mixed $name)

Return Path

Parameters

string|array|null $email optional: Null to get, String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

array|$this

Throws

InvalidArgumentException

send() public

send(mixed $content)

Send an email using the specified content, template and layout

Parameters

string|array|null $content optional: String with message or array with messages

Returns

array

Throws

BadMethodCallException

sender() public

sender(mixed $email, mixed $name)

Sender

Parameters

string|array|null $email optional: Null to get, String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

array|$this

Throws

InvalidArgumentException

serialize() public

serialize()

Serializes the Email object.

Returns

string

set() public

set(mixed $name, mixed $value)

Saves a variable or an associative array of variables for use inside a template.

Parameters

string|array $name: A string or an array of data.
mixed $value optional: Value in case $name is a string (which then works as the key). Unused if $name is an associative array, otherwise serves as the values to $name's keys.

Returns

$this

setAttachments() public

setAttachments(mixed $attachments)

Add attachments to the email message

Attachments can be defined in a few forms depending on how much control you need:

Attach a single file:

$email->setAttachments('path/to/file');

Attach a file with a different filename:

$email->setAttachments(['custom_name.txt' => 'path/to/file.txt']);

Attach a file and specify additional properties:

$email->setAttachments(['custom_name.png' => [
     'file' => 'path/to/file',
     'mimetype' => 'image/png',
     'contentId' => 'abc123',
     'contentDisposition' => false
   ]
]);

Attach a file from string and specify additional properties:

$email->setAttachments(['custom_name.png' => [
     'data' => file_get_contents('path/to/file'),
     'mimetype' => 'image/png'
   ]
]);

The contentId key allows you to specify an inline attachment. In your email text, you can use <img src="cid:abc123" /> to display the image inline.

The contentDisposition key allows you to disable the Content-Disposition header, this can improve attachment compatibility with outlook email clients.

Parameters

string|array $attachments: String with the filename or array with filenames

Returns

$this

Throws

InvalidArgumentException

setBcc() public

setBcc(mixed $email, mixed $name)

Sets "bcc" address.

Parameters

string|array $email: String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

$this

setCc() public

setCc(mixed $email, mixed $name)

Sets "cc" address.

Parameters

string|array $email: String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

$this

setCharset() public

setCharset(mixed $charset)

Charset setter.

Parameters

string|null $charset: Character set.

Returns

$this

setConfig() public static

setConfig(mixed $key, mixed $config)

This method can be used to define configuration adapters for an application.

To change an adapter's configuration at runtime, first drop the adapter and then reconfigure it.

Adapters will not be constructed until the first operation is done.

Usage

Assuming that the class' name is Cache the following scenarios are supported:

Setting a cache engine up.

Cache::setConfig('default', $settings);

Injecting a constructed adapter in:

Cache::setConfig('default', $instance);

Configure multiple adapters at once:

Cache::setConfig($arrayOfConfig);

Parameters

string|array $key: The name of the configuration, or an array of multiple configs.
array|object|null $config optional: An array of name => configuration data for adapter.

Throws

BadMethodCallException
When trying to modify an existing config.
LogicException
When trying to store an invalid structured config array.

setConfigTransport() public static

setConfigTransport(mixed $key, mixed $config)

Sets transport configuration.

Use this method to define transports to use in delivery profiles. Once defined you cannot edit the configurations, and must use Email::dropTransport() to flush the configuration first.

When using an array of configuration data a new transport will be constructed for each message sent. When using a Closure, the closure will be evaluated for each message.

The className is used to define the class to use for a transport. It can either be a short name, or a fully qualified class name

Parameters

string|array $key: The configuration name to write. Or an array of multiple transports to set.
array|\Cake\Mailer\AbstractTransport|null $config optional: Either an array of configuration data, or a transport instance. Null when using key as array.

setDomain() public

setDomain(mixed $domain)

Sets domain.

Domain as top level (the part after @).

Parameters

string $domain: Manually set the domain for CLI mailing.

Returns

$this

setDsnClassMap() public static

setDsnClassMap(array $map)

Updates the DSN class map for this class.

Parameters

string[] $map: Additions/edits to the class map to apply.

setEmailFormat() public

setEmailFormat(mixed $format)

Sets email format.

Parameters

string $format: Formatting string.

Returns

$this

Throws

InvalidArgumentException

setEmailPattern() public

setEmailPattern(mixed $regex)

EmailPattern setter/getter

Parameters

string|null $regex: The pattern to use for email address validation, null to unset the pattern and make use of filter_var() instead.

Returns

$this

setFrom() public

setFrom(mixed $email, mixed $name)

Sets "from" address.

Parameters

string|array $email: Null to get, String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

$this

Throws

InvalidArgumentException

setHeaderCharset() public

setHeaderCharset(mixed $charset)

HeaderCharset setter.

Parameters

string|null $charset: Character set.

Returns

$this

setHeaders() public

setHeaders(array $headers)

Sets headers for the message

Parameters

array $headers: Associative array containing headers to be set.

Returns

$this

setHelpers() public

setHelpers(array $helpers)

Sets helpers to be used when rendering.

Parameters

array $helpers: Helpers list.

Returns

$this

setLayout() public

setLayout(mixed $layout)

Sets layout.

Parameters

string|null $layout: Layout name or null to not use

Returns

$this

setMessageId() public

setMessageId(mixed $message)

Sets message ID.

Parameters

bool|string $message: True to generate a new Message-ID, False to ignore (not send in email), String to set as Message-ID.

Returns

$this

Throws

InvalidArgumentException

setPriority() public

setPriority(mixed $priority)

Sets priority.

Parameters

int|null $priority: 1 (highest) to 5 (lowest)

Returns

$this

setProfile() public

setProfile(mixed $config)

Sets the configuration profile to use for this instance.

Parameters

string|array $config: String with configuration name, or an array with config.

Returns

$this

setReadReceipt() public

setReadReceipt(mixed $email, mixed $name)

Sets Read Receipt (Disposition-Notification-To header).

Parameters

string|array $email: String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

$this

Throws

InvalidArgumentException

setReplyTo() public

setReplyTo(mixed $email, mixed $name)

Sets "Reply-To" address.

Parameters

string|array $email: String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

$this

Throws

InvalidArgumentException

setReturnPath() public

setReturnPath(mixed $email, mixed $name)

Return Path

Parameters

string|array $email: String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

$this

Throws

InvalidArgumentException

setSender() public

setSender(mixed $email, mixed $name)

Sets the "sender" address. See rfc link below for full explanation.

Parameters

string|array $email: String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

$this

Throws

InvalidArgumentException

Links

https://tools.ietf.org/html/rfc2822.html#section-3.6.2

setSubject() public

setSubject(mixed $subject)

Sets subject.

Parameters

string $subject: Subject string.

Returns

$this

setTemplate() public

setTemplate(mixed $template)

Sets template.

Parameters

string|null $template: Template name or null to not use.

Returns

$this

setTheme() public

setTheme(mixed $theme)

Sets theme to use when rendering.

Parameters

string $theme: Theme name.

Returns

$this

setTo() public

setTo(mixed $email, mixed $name)

Sets "to" address.

Parameters

string|array $email: String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

$this

setTransferEncoding() public

setTransferEncoding(mixed $encoding)

TransferEncoding setter.

Parameters

string|null $encoding: Encoding set.

Returns

$this

setTransport() public

setTransport(mixed $name)

Sets the transport.

When setting the transport you can either use the name of a configured transport or supply a constructed transport.

Parameters

string|\Cake\Mailer\AbstractTransport $name: Either the name of a configured transport, or a transport instance.

Returns

$this

Throws

LogicException
When the chosen transport lacks a send method.
InvalidArgumentException
When $name is neither a string nor an object.

setViewRenderer() public

setViewRenderer(mixed $viewClass)

Sets view class for render.

Parameters

string $viewClass: View class name.

Returns

$this

setViewVars() public

setViewVars(mixed $viewVars)

Sets variables to be set on render.

Parameters

array $viewVars: Variables to set for view.

Returns

$this

subject() public

subject(mixed $subject)

Get/Set Subject.

Parameters

string|null $subject optional: Subject string.

Returns

string|$this

template() public

template(mixed $template, mixed $layout)

Template and layout

Parameters

bool|string $template optional: Template name or null to not use
bool|string $layout optional: Layout name or null to not use

Returns

array|$this

theme() public

theme(mixed $theme)

Theme to use when rendering

Parameters

string|null $theme optional: Theme name.

Returns

string|$this

to() public

to(mixed $email, mixed $name)

Parameters

string|array|null $email optional: Null to get, String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

array|$this

transport() public

transport(mixed $name)

Get/set the transport.

When setting the transport you can either use the name of a configured transport or supply a constructed transport.

Parameters

string|\Cake\Mailer\AbstractTransport|null $name optional: Either the name of a configured transport, or a transport instance.

Returns

\Cake\Mailer\AbstractTransport|$this

Throws

LogicException
When the chosen transport lacks a send method.
InvalidArgumentException
When $name is neither a string nor an object.

unserialize() public

unserialize(mixed $data)

Unserializes the Email object.

Parameters

string $data: Serialized string.

Returns

static

Configured email instance.

viewBuilder() public

viewBuilder()

Get the view builder being used.

Returns

\Cake\View\ViewBuilder

viewOptions() public

viewOptions(mixed $options, mixed $merge)

Get/Set valid view options in the object's _validViewOptions property. The property is created as an empty array if it is not set. If called without any parameters it will return the current list of valid view options. See createView().

Parameters

string|array|null $options optional: string or array of string to be appended to _validViewOptions.
bool $merge optional: Whether to merge with or override existing valid View options. Defaults to true.

Returns

array

The updated view options as an array.

viewRender() public

viewRender(mixed $viewClass)

View class for render

Parameters

string|null $viewClass optional: View class name.

Returns

string|$this

viewVars() public

viewVars(mixed $viewVars)

Variables to be set on render

Parameters

array|null $viewVars optional: Variables to set for view.

Returns

array|$this

Property Detail

`$_appCharset` protected

The application wide charset, used to encode headers and body

Type

string|null

`$_attachments` protected

List of files that should be attached to the email.

Only absolute paths

Type

array

`$_bcc` protected

Blind Carbon Copy

List of email's that should receive a copy of the email. The Recipient WILL NOT be able to see this list

Type

array

`$_boundary` protected

If set, boundary to use for multipart mime messages

Type

string|null

`$_cc` protected

Carbon Copy

Domain for messageId generation.

Needs to be manually set for CLI mailing as env('HTTP_HOST') is empty

Type

string

`$_dsnClassMap` protected static

An array mapping url schemes to fully qualified Transport class names.

Remote mailserver down
Remote user has exceeded his quota
Unknown user

array

`$_viewBuilder` protected

The view builder instance being used.

Type

\Cake\View\ViewBuilder

`$charset` public

Charset the email body is sent in

Type

string

`$headerCharset` public

Charset the email header is sent in If null, the $charset property will be used as default

Type

string|null

`$transferEncoding` protected

The email transfer encoding used.

If null, the $charset property is used for determined the transfer encoding.

Type

string|null

`$viewClass` public

The name of default View class.

Type

string|null

`$viewVars` public

Variables for the view.

Deprecated: This property will be removed in 4.x. Inside controller context use $this->set() instead, also see $this->viewBuilder()->getVar(). In view context it will be a protected property View::$viewVars.

Type

array

© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/3.9/class-Cake.Mailer.Email.html

Class Email

Configuration

Constants summary

Properties summary

Method Summary

Method Detail

__clone() public

__construct() public

Parameters

_addEmail() protected

Parameters

Returns

Throws

_applyConfig() protected

Parameters

Throws

_attachFiles() protected

Parameters

Returns

_attachInlineFiles() protected

Parameters

Returns

_checkViewVars() protected

Parameters

_createBoundary() protected

_decode() protected

Parameters

Returns

_encode() protected

Parameters

Returns

_encodeString() protected

Parameters

Returns

_formatAddress() protected

Parameters

Returns

_getContentTransferEncoding() protected

Returns

_getContentTypeCharset() protected

Returns

_getTypes() protected

Returns

_logDelivery() protected

Parameters

_readFile() protected

Parameters

Returns

_render() protected

Parameters

Returns

_renderTemplates() protected

Parameters

Returns

_setEmail() protected

Parameters

Returns

Throws

_setEmailSingle() protected

Parameters

Returns

Throws

_validateEmail() protected

Parameters

Throws

_wrap() protected

Parameters

Returns

addAttachments() public

Parameters

Returns

Throws

See Also

addBcc() public

Parameters

Returns

addCc() public

Parameters

Returns

addHeaders() public