W3cubDocs

/CakePHP 3.8

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.

Cake\Mailer\Email implements JsonSerializable, Serializable uses Cake\Core\StaticConfigTrait , Cake\View\ViewVarsTrait
Namespace: Cake\Mailer
Location: Mailer/Email.php

Constants summary

  • string

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

    LINE_LENGTH_MUST
    998
  • integer

    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
  • array
    Define Content-Type charset name
  • $_domain protected
    string

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

  • $_dsnClassMap protected static
    array

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

  • $_emailFormat protected
    string
    What format should the email be sent in
  • 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
    boolean|string
    Message ID
  • $_priority protected
    integer|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
  • array
    Available encoding to be set for transfer.
  • $_transport protected
    The transport instance to use for sending mail.
  • $charset public
    string
    Charset the email body is sent in
  • 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. If null, the $charset property is used for determined the transfer encoding.

Inherited Magic Properties

Inherited Properties

Method Summary

Method Detail

__clone()source public

__clone( )

Clone ViewBuilder instance when email object is cloned.

__construct()source public

__construct( array|string|null $config = null )

Constructor

Parameters

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

_addEmail()source protected

_addEmail( string $varName , string|array $email , string $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()source protected

_applyConfig( string|array $config )

Apply the config to an instance

Parameters

string|array $config
Configuration options.

Throws

InvalidArgumentException
When using a configuration that doesn't exist.

_attachFiles()source protected

_attachFiles( string|null $boundary = null )

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

Parameters

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

Returns

array
An array of lines to add to the message

_attachInlineFiles()source protected

_attachInlineFiles( string|null $boundary = null )

Attach inline/embedded files to the message.

Parameters

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

Returns

array
An array of lines to add to the message

_checkViewVars()source protected

_checkViewVars( mixed $item , string $key )

Iterates through hash to clean up and normalize.

Parameters

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

_createBoundary()source protected

_createBoundary( )

Create unique boundary identifier

_decode()source protected

_decode( string $text )

Decode the specified string

Parameters

string $text
String to decode

Returns

string
Decoded string

_encode()source protected

_encode( string $text )

Encode the specified string using the current charset

Parameters

string $text
String to encode

Returns

string
Encoded string

_encodeString()source protected

_encodeString( string $text , string $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()source protected

_formatAddress( array $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()source protected

_getContentTransferEncoding( )

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

Returns

string

_getContentTypeCharset()source protected

_getContentTypeCharset( )

Return charset value for Content-Type.

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

Returns

string

_getTypes()source 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()source protected

_logDelivery( array $contents )

Log the email message delivery.

Parameters

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

_readFile()source protected

_readFile( string $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()source protected

_render( array $content )

Render the body of the email.

Parameters

array $content
Content to render

Returns

array
Email body ready to be sent

_renderTemplates()source protected

_renderTemplates( string $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()source protected

_setEmail( string $varName , string|array $email , string $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()source protected

_setEmailSingle( string $varName , string|array $email , string $name , string $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()source protected

_validateEmail( string $email , string $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()source protected

_wrap( string $message , integer $wrapLength = Email::LINE_LENGTH_MUST )

Wrap the message to follow the RFC 2822 - 2.1.1

Parameters

string $message
Message to wrap
integer $wrapLength optional Email::LINE_LENGTH_MUST
The line length

Returns

array
Wrapped message

addAttachments()source public

addAttachments( string|array $attachments )

Add attachments

Parameters

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

Returns


$this

Throws

InvalidArgumentException

See

\Cake\Mailer\Email::attachments()

addBcc()source public

addBcc( string|array $email , string|null $name = null )

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 null
Name

Returns


$this

addCc()source public

addCc( string|array $email , string|null $name = null )

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 null
Name

Returns


$this

addHeaders()source public

addHeaders( array $headers )

Add header for the message

Parameters

array $headers
Headers to set.

Returns


$this

addTo()source public

addTo( string|array $email , string|null $name = null )

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 null
Name

Returns


$this

attachments()source public deprecated

attachments( string|array|null $attachments = null )

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.

Deprecated

3.4.0 Use setAttachments()/getAttachments() instead.

Parameters

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

Returns

array|Cake\Mailer\Email
$this Either the array of attachments when getting or $this when setting.

Throws

InvalidArgumentException

bcc()source public deprecated

bcc( string|array|null $email = null , string|null $name = null )

Bcc

Deprecated

3.4.0 Use setBcc()/getBcc() instead.

Parameters

string|array|null $email optional null

Null to get, String with email, Array with email as key, name as value or email as value (without name)

string|null $name optional null
Name

Returns

array|Cake\Mailer\Email
$this

cc()source public deprecated

cc( string|array|null $email = null , string|null $name = null )

Cc

Deprecated

3.4.0 Use setCc()/getCc() instead.

Parameters

string|array|null $email optional null

Null to get, String with email, Array with email as key, name as value or email as value (without name)

string|null $name optional null
Name

Returns

array|Cake\Mailer\Email
$this

charset()source public deprecated

charset( string|null $charset = null )

Charset setter/getter

Deprecated

3.4.0 Use setCharset()/getCharset() instead.

Parameters

string|null $charset optional null
Character set.

Returns

string
Charset

configTransport()source public static deprecated

configTransport( string|array $key , array|Cake\Mailer\AbstractTransport|null $config = null )

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

Deprecated

3.4.0 Use TransportFactory::setConfig()/getConfig() instead.

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 null

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.

configuredTransport()source public static deprecated

configuredTransport( )

Returns an array containing the named transport configurations

Deprecated

3.7.0 Use TransportFactory::configured() instead.

Returns

array
Array of configurations.

createFromArray()source public

createFromArray( array $config )

Configures an email instance object from serialized config.

Parameters

array $config
Email configuration array.

Returns


$this Configured email instance.

deliver()source public static

deliver( string|array|null $to = null , string|null $subject = null , string|array|null $message = null , string|array $config = 'default' , boolean $send = true )

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

Parameters

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

Returns

Cake\Mailer\Email
Instance of Cake\Mailer\Email

Throws

InvalidArgumentException

domain()source public deprecated

domain( string|null $domain = null )

Domain as top level (the part after @)

Deprecated

3.4.0 Use setDomain()/getDomain() instead.

Parameters

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

Returns

string|Cake\Mailer\Email
$this

dropTransport()source public static deprecated

dropTransport( string $key )

Delete transport configuration.

Deprecated

3.7.0 Use TransportFactory::drop() instead.

Parameters

string $key
The transport name to remove.

emailFormat()source public deprecated

emailFormat( string|null $format = null )

Email format

Deprecated

3.4.0 Use setEmailFormat()/getEmailFormat() instead.

Parameters

string|null $format optional null
Formatting string.

Returns

string|Cake\Mailer\Email
$this

Throws

InvalidArgumentException

emailPattern()source public deprecated

emailPattern( string|boolean|null $regex = false )

EmailPattern setter/getter

Deprecated

3.4.0 Use setEmailPattern()/getEmailPattern() instead.

Parameters

string|boolean|null $regex optional false

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|Cake\Mailer\Email
$this

flatten()source protected

flatten( string|array $value )

Converts given value to string

Parameters

string|array $value
The value to convert

Returns

string

from()source public deprecated

from( string|array|null $email = null , string|null $name = null )

From

Deprecated

3.4.0 Use setFrom()/getFrom() instead.

Parameters

string|array|null $email optional null

Null to get, String with email, Array with email as key, name as value or email as value (without name)

string|null $name optional null
Name

Returns

array|Cake\Mailer\Email
$this

Throws

InvalidArgumentException

getAttachments()source public

getAttachments( )

Gets attachments to the email message.

Returns

array
Array of attachments.

getBcc()source public

getBcc( )

Gets "bcc" address.

Returns

array

getCc()source public

getCc( )

Gets "cc" address.

Returns

array

getCharset()source public

getCharset( )

Charset getter.

Returns

string
Charset

getConfigTransport()source public static deprecated

getConfigTransport( string $key )

Gets current transport configuration.

Deprecated

3.7.0 Use TransportFactory::getConfig() instead.

Parameters

string $key
The configuration name to read.

Returns

array|null
Transport config.

getDomain()source public

getDomain( )

Gets domain.

Returns

string

getEmailFormat()source public

getEmailFormat( )

Gets email format.

Returns

string

getEmailPattern()source public

getEmailPattern( )

EmailPattern setter/getter

Returns

string

getFrom()source public

getFrom( )

Gets "from" address.

Returns

array

getHeaderCharset()source public

getHeaderCharset( )

HeaderCharset getter.

Returns

string
Charset

getHeaders()source 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()source public deprecated

getHelpers( )

Gets helpers to be used when rendering.

Deprecated

3.7.0 Use $email->viewBuilder()->getHelpers() instead.

Returns

array

getLayout()source public deprecated

getLayout( )

Gets layout.

Deprecated

3.7.0 Use $email->viewBuilder()->getLayout() instead.

Returns

string

getMessageId()source public

getMessageId( )

Gets message ID.

Returns

boolean|string

getOriginalSubject()source public

getOriginalSubject( )

Get original subject without encoding

Returns

string
Original subject

getPriority()source public

getPriority( )

Gets priority.

Returns

integer

getProfile()source public

getProfile( )

Gets the configuration profile to use for this instance.

Returns

string|array

getReadReceipt()source public

getReadReceipt( )

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

Returns

array

getReplyTo()source public

getReplyTo( )

Gets "Reply-To" address.

Returns

array

getReturnPath()source public

getReturnPath( )

Gets return path.

Returns

array

getSender()source public

getSender( )

Gets "sender" address.

Returns

array

getSubject()source public

getSubject( )

Gets subject.

Returns

string

getTemplate()source public

getTemplate( )

Gets template.

Returns

string

getTheme()source public deprecated

getTheme( )

Gets theme to use when rendering.

Deprecated

3.7.0 Use $email->viewBuilder()->getTheme() instead.

Returns

string

getTo()source public

getTo( )

Gets "to" address

Returns

array

getTransferEncoding()source public

getTransferEncoding( )

TransferEncoding getter.

Returns

string|null
Encoding

getTransport()source public

getTransport( )

Gets the transport.

Returns

Cake\Mailer\AbstractTransport

getViewRenderer()source public

getViewRenderer( )

Gets view class for render.

Returns

string

getViewVars()source public

getViewVars( )

Gets variables to be set on render.

Returns

array

headerCharset()source public deprecated

headerCharset( string|null $charset = null )

HeaderCharset setter/getter

Deprecated

3.4.0 Use setHeaderCharset()/getHeaderCharset() instead.

Parameters

string|null $charset optional null
Character set.

Returns

string
Charset

helpers()source public deprecated

helpers( array|null $helpers = null )

Helpers to be used in render

Deprecated

3.4.0 Use setHelpers()/getHelpers() instead.

Parameters

array|null $helpers optional null
Helpers list.

Returns

array|Cake\Mailer\Email
$this

jsonSerialize()source 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.

Implementation of

JsonSerializable::jsonSerialize()

message()source public

message( string|null $type = null )

Get generated message (used by transport classes)

Parameters

string|null $type optional null
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()source public deprecated

messageId( boolean|string|null $message = null )

Message-ID

Deprecated

3.4.0 Use setMessageId()/getMessageId() instead.

Parameters

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

Returns

boolean|string|Cake\Mailer\Email
$this

Throws

InvalidArgumentException

profile()source public deprecated

profile( null|string|array $config = null )

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

Deprecated

3.4.0 Use setProfile()/getProfile() instead.

Parameters

null|string|array $config optional null

String with configuration name, or an array with config or null to return current config.

Returns

string|array|Cake\Mailer\Email
$this

readReceipt()source public deprecated

readReceipt( string|array|null $email = null , string|null $name = null )

Read Receipt (Disposition-Notification-To header)

Deprecated

3.4.0 Use setReadReceipt()/getReadReceipt() instead.

Parameters

string|array|null $email optional null

Null to get, String with email, Array with email as key, name as value or email as value (without name)

string|null $name optional null
Name

Returns

array|Cake\Mailer\Email
$this

Throws

InvalidArgumentException

replyTo()source public deprecated

replyTo( string|array|null $email = null , string|null $name = null )

Reply-To

Deprecated

3.4.0 Use setReplyTo()/getReplyTo() instead.

Parameters

string|array|null $email optional null

Null to get, String with email, Array with email as key, name as value or email as value (without name)

string|null $name optional null
Name

Returns

array|Cake\Mailer\Email
$this

Throws

InvalidArgumentException

reset()source public

reset( )

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

Returns


$this

returnPath()source public deprecated

returnPath( string|array|null $email = null , string|null $name = null )

Return Path

Deprecated

3.4.0 Use setReturnPath()/getReturnPath() instead.

Parameters

string|array|null $email optional null

Null to get, String with email, Array with email as key, name as value or email as value (without name)

string|null $name optional null
Name

Returns

array|Cake\Mailer\Email
$this

Throws

InvalidArgumentException

send()source public

send( string|array|null $content = null )

Send an email using the specified content, template and layout

Parameters

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

Returns

array

Throws

BadMethodCallException

sender()source public deprecated

sender( string|array|null $email = null , string|null $name = null )

Sender

Deprecated

3.4.0 Use setSender()/getSender() instead.

Parameters

string|array|null $email optional null

Null to get, String with email, Array with email as key, name as value or email as value (without name)

string|null $name optional null
Name

Returns

array|Cake\Mailer\Email
$this

Throws

InvalidArgumentException

serialize()source public

serialize( )

Serializes the Email object.

Returns

string

Implementation of

Serializable::serialize()

setAttachments()source public

setAttachments( string|array $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()source public

setBcc( string|array $email , string|null $name = null )

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 null
Name

Returns


$this

setCc()source public

setCc( string|array $email , string|null $name = null )

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 null
Name

Returns


$this

setCharset()source public

setCharset( string|null $charset )

Charset setter.

Parameters

string|null $charset
Character set.

Returns


$this

setConfigTransport()source public static deprecated

setConfigTransport( string|array $key , array|Cake\Mailer\AbstractTransport|null $config = null )

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

Deprecated

3.7.0 Use TransportFactory::setConfig() instead.

Parameters

string|array $key

The configuration name to write. Or an array of multiple transports to set.

array|Cake\Mailer\AbstractTransport|null $config optional null

Either an array of configuration data, or a transport instance. Null when using key as array.

setDomain()source public

setDomain( string $domain )

Sets domain.

Domain as top level (the part after @).

Parameters

string $domain
Manually set the domain for CLI mailing.

Returns


$this

setEmailFormat()source public

setEmailFormat( string $format )

Sets email format.

Parameters

string $format
Formatting string.

Returns


$this

Throws

InvalidArgumentException

setEmailPattern()source public

setEmailPattern( string|null $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()source public

setFrom( string|array $email , string|null $name = null )

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 null
Name

Returns


$this

Throws

InvalidArgumentException

setHeaderCharset()source public

setHeaderCharset( string|null $charset )

HeaderCharset setter.

Parameters

string|null $charset
Character set.

Returns


$this

setHeaders()source public

setHeaders( array $headers )

Sets headers for the message

Parameters

array $headers
Associative array containing headers to be set.

Returns


$this

setHelpers()source public deprecated

setHelpers( array $helpers )

Sets helpers to be used when rendering.

Deprecated

3.7.0 Use $email->viewBuilder()->setHelpers() instead.

Parameters

array $helpers
Helpers list.

Returns


$this

setLayout()source public deprecated

setLayout( string|null $layout )

Sets layout.

Deprecated

3.7.0 Use $email->viewBuilder()->setLayout() instead.

Parameters

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

Returns


$this

setMessageId()source public

setMessageId( boolean|string $message )

Sets message ID.

Parameters

boolean|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()source public

setPriority( integer|null $priority )

Sets priority.

Parameters

integer|null $priority
1 (highest) to 5 (lowest)

Returns


$this

setProfile()source public

setProfile( string|array $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()source public

setReadReceipt( string|array $email , string|null $name = null )

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 null
Name

Returns


$this

Throws

InvalidArgumentException

setReplyTo()source public

setReplyTo( string|array $email , string|null $name = null )

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 null
Name

Returns


$this

Throws

InvalidArgumentException

setReturnPath()source public

setReturnPath( string|array $email , string|null $name = null )

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 null
Name

Returns


$this

Throws

InvalidArgumentException

setSender()source public

setSender( string|array $email , string|null $name = null )

Sets "sender" 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 null
Name

Returns


$this

Throws

InvalidArgumentException

setSubject()source public

setSubject( string $subject )

Sets subject.

Parameters

string $subject
Subject string.

Returns


$this

setTemplate()source public

setTemplate( string|null $template )

Sets template.

Parameters

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

Returns


$this

setTheme()source public deprecated

setTheme( string $theme )

Sets theme to use when rendering.

Deprecated

3.7.0 Use $email->viewBuilder()->setTheme() instead.

Parameters

string $theme
Theme name.

Returns


$this

setTo()source public

setTo( string|array $email , string|null $name = null )

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 null
Name

Returns


$this

setTransferEncoding()source public

setTransferEncoding( string|null $encoding )

TransferEncoding setter.

Parameters

string|null $encoding
Encoding set.

Returns


$this

setTransport()source public

setTransport( string|Cake\Mailer\AbstractTransport $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()source public

setViewRenderer( string $viewClass )

Sets view class for render.

Parameters

string $viewClass
View class name.

Returns


$this

setViewVars()source public

setViewVars( array $viewVars )

Sets variables to be set on render.

Parameters

array $viewVars
Variables to set for view.

Returns


$this

subject()source public deprecated

subject( string|null $subject = null )

Get/Set Subject.

Deprecated

3.4.0 Use setSubject()/getSubject() instead.

Parameters

string|null $subject optional null
Subject string.

Returns

string|Cake\Mailer\Email
$this

template()source public deprecated

template( boolean|string $template = false , boolean|string $layout = false )

Template and layout

Deprecated

3.4.0 Use setTemplate()/getTemplate() and setLayout()/getLayout() instead.

Parameters

boolean|string $template optional false
Template name or null to not use
boolean|string $layout optional false
Layout name or null to not use

Returns

array|Cake\Mailer\Email
$this

theme()source public deprecated

theme( string|null $theme = null )

Theme to use when rendering

Deprecated

3.4.0 Use setTheme()/getTheme() instead.

Parameters

string|null $theme optional null
Theme name.

Returns

string|Cake\Mailer\Email
$this

to()source public deprecated

to( string|array|null $email = null , string|null $name = null )

To

Deprecated

3.4.0 Use setTo()/getTo() instead.

Parameters

string|array|null $email optional null

Null to get, String with email, Array with email as key, name as value or email as value (without name)

string|null $name optional null
Name

Returns

array|Cake\Mailer\Email
$this

transport()source public deprecated

transport( string|Cake\Mailer\AbstractTransport|null $name = null )

Get/set the transport.

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

Deprecated

3.4.0 Use setTransport()/getTransport() instead.

Parameters

string|Cake\Mailer\AbstractTransport|null $name optional null

Either the name of a configured transport, or a transport instance.

Returns

Cake\Mailer\AbstractTransport|Cake\Mailer\Email
$this

Throws

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

unserialize()source public

unserialize( string $data )

Unserializes the Email object.

Parameters

string $data
Serialized string.

Returns

Cake\Mailer\Email
Configured email instance.

Implementation of

Serializable::unserialize()

viewRender()source public deprecated

viewRender( string|null $viewClass = null )

View class for render

Deprecated

3.4.0 Use setViewRenderer()/getViewRenderer() instead.

Parameters

string|null $viewClass optional null
View class name.

Returns

string|Cake\Mailer\Email
$this

viewVars()source public deprecated

viewVars( array|null $viewVars = null )

Variables to be set on render

Deprecated

3.4.0 Use setViewVars()/getViewVars() instead.

Parameters

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

Returns

array|Cake\Mailer\Email
$this

Methods used from Cake\Core\StaticConfigTrait

config()source public static deprecated

config( string|array $key , array|null $config = null )

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);

Deprecated

3.4.0 Use setConfig()/getConfig() instead.

Parameters

string|array $key
The name of the configuration, or an array of multiple configs.
array|null $config optional null
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.

configured()source public static

configured( )

Returns an array containing the named configurations

Returns

string[]
Array of configurations.

drop()source public static

drop( string $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

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

dsnClassMap()source public static deprecated

dsnClassMap( array $map = null )

Returns or updates the DSN class map for this class.

Deprecated

3.4.0 Use setDsnClassMap()/getDsnClassMap() instead.

Parameters

array $map optional null
Additions/edits to the class map to apply.

Returns

array

getConfig()source public static

getConfig( string $key )

Reads existing configuration.

Parameters

string $key
The name of the configuration.

Returns

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

getDsnClassMap()source public static

getDsnClassMap( )

Returns the DSN class map for this class.

Returns

array

parseDsn()source public static

parseDsn( string $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:[email protected]/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:[email protected]: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

setConfig()source public static

setConfig( string|array $key , array $config = null )

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 $config optional null
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.

setDsnClassMap()source public static

setDsnClassMap( array $map )

Updates the DSN class map for this class.

Parameters

array $map
Additions/edits to the class map to apply.

Methods used from Cake\View\ViewVarsTrait

createView()source public

createView( string|null $viewClass = null )

Constructs the view class instance based on the current configuration.

Parameters

string|null $viewClass optional null
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.

set()source public

set( string|array $name , mixed $value = null )

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 null

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

viewBuilder()source public

viewBuilder( )

Get the view builder being used.

Returns

Cake\View\ViewBuilder

viewOptions()source public deprecated

viewOptions( string|array|null $options = null , boolean $merge = true )

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().

Deprecated

3.7.0 Use ViewBuilder::setOptions() or any one of it's setter methods instead.

Parameters

string|array|null $options optional null
string or array of string to be appended to _validViewOptions.
boolean $merge optional true

Whether to merge with or override existing valid View options. Defaults to true.

Returns

array
The updated view options as an array.

Properties detail

$_appCharsetsource

protected string|null

The application wide charset, used to encode headers and body

$_attachmentssource

protected array

List of files that should be attached to the email.

Only absolute paths

[]

$_bccsource

protected array

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

[]

$_boundarysource

protected string|null

If set, boundary to use for multipart mime messages

$_ccsource

protected array

Carbon Copy

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

[]

$_charset8bitsource

protected array

8Bit character sets

['UTF-8', 'SHIFT_JIS']

$_contentTypeCharsetsource

protected array

Define Content-Type charset name

[
    'ISO-2022-JP-MS' => 'ISO-2022-JP'
]

$_domainsource

protected string

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

$_dsnClassMapsource

protected static array

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

Deprecated

3.7.0 This property is unused and will be removed in 4.0.0.
[]

$_emailFormatsource

protected string

What format should the email be sent in

'text'

$_emailFormatAvailablesource

protected array

Available formats to be sent.

['text', 'html', 'both']

$_emailPatternsource

protected string

Regex for email validation

If null, filter_var() will be used. Use the emailPattern() method to set a custom pattern.'

self::EMAIL_PATTERN

$_fromsource

protected array

The mail which the email is sent from

[]

$_headerssource

protected array

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

[]

$_htmlMessagesource

protected string

Html message

''

$_messagesource

protected array

Final message to send

[]

$_messageIdsource

protected boolean|string

Message ID

true

$_prioritysource

protected integer|null

Contains the optional priority of the email.

$_profilesource

protected array

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

[]

$_readReceiptsource

protected array

The read receipt email

[]

$_replyTosource

protected array

The email the recipient will reply to

[]

$_returnPathsource

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

[]

$_sendersource

protected array

The sender email

[]

$_subjectsource

protected string

The subject of the email

''

$_textMessagesource

protected string

Text message

''

$_tosource

protected array

Recipient of the email

[]

$_transferEncodingAvailablesource

protected array

Available encoding to be set for transfer.

[
    '7bit',
    '8bit',
    'base64',
    'binary',
    'quoted-printable'
]

$_transportsource

protected Cake\Mailer\AbstractTransport|null

The transport instance to use for sending mail.

$charsetsource

public string

Charset the email body is sent in

'utf-8'

$headerCharsetsource

public string|null

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

$transferEncodingsource

protected string|null

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

© 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.8/class-Cake.Mailer.Email.html