CakePHP Email class.
This class is used for sending Internet Message Format based on the standard outlined in http://www.rfc-editor.org/rfc/rfc2822.txt
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.
string
'/^((?:[\p{L}0-9.!#$%&\'*+\/=?^_`{|}~-]+)*@[\p{L}0-9-.]+)$/ui' integer
998 integer
78 string
'html' string
'text' $_appCharset protected string|null$_attachments protected array$_bcc protected array$_boundary protected string|null$_cc protected array$_charset8bit protected array$_contentTypeCharset protected array$_domain protected stringDomain for messageId generation. Needs to be manually set for CLI mailing as env('HTTP_HOST') is empty
array$_emailFormat protected string$_emailFormatAvailable protected array$_emailPattern protected string$_from protected array$_headers protected arrayAssociative array of a user defined headers Keys will be prefixed 'X-' as per RFC2822 Section 4.7.5
$_htmlMessage protected string$_message protected array$_messageId protected boolean|string$_priority protected integer|null$_profile protected arrayA copy of the configuration profile for this instance. This copy can be modified with Email::profile().
$_readReceipt protected array$_replyTo protected array$_returnPath protected arrayThe 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$_subject protected string$_textMessage protected string$_to protected array$_transport protected array$charset public string$headerCharset public string|nullCharset the email header is sent in If null, the $charset property will be used as default
Translates a string for one charset to another if the App.encoding value differs and the mb_convert_encoding function exists
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.
Serializes the email object to a value that can be natively serialized and re-used to clone this email instance.
__construct( array|string|null $config null )
Constructor
$config optional null _addEmail( string $varName , string|array $email , string $name )
Add email
$varName $email String with email, Array with email as key, name as value or email as value (without name)
$name _applyConfig( string|array $config )
Apply the config to an instance
$config _attachFiles( string|null $boundary null )
Attach non-embedded files by adding file contents inside boundaries.
$boundary optional null _attachInlineFiles( string|null $boundary null )
Attach inline/embedded files to the message.
$boundary optional null _checkViewVars( mixed $item , string $key )
Iterates through hash to clean up and normalize.
$item $key _constructTransport( string $name )
Build a transport instance from configuration data.
$name Cake\Mailer\AbstractTransport_decode( string $text )
Decode the specified string
$text _encode( string $text )
Encode the specified string using the current charset
$text _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
$text $charset _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.
$address _getContentTransferEncoding( )
Return the Content-Transfer Encoding value based on the set charset
_getContentTypeCharset( )
Return charset value for Content-Type.
Checks fallback/compatibility types which include workarounds for legacy japanese character sets.
_getTypes( )
Gets the text body types that are in this email message
_logDelivery( array $contents )
Log the email message delivery.
$contents _readFile( string $path )
Read the file contents and return a base64 version of the file contents.
$path _render( array $content )
Render the body of the email.
$content _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.
$content _setEmail( string $varName , string|array $email , string $name )
Set email
$varName $email String with email, Array with email as key, name as value or email as value (without name)
$name _setEmailSingle( string $varName , string|array $email , string $name , string $throwMessage )
Set only 1 email
$varName $email String with email, Array with email as key, name as value or email as value (without name)
$name $throwMessage _validateEmail( string $email )
Validate email address
$email _wrap( string $message , integer $wrapLength Email::LINE_LENGTH_MUST )
Wrap the message to follow the RFC 2822 - 2.1.1
$message $wrapLength optional Email::LINE_LENGTH_MUST addAttachments( string|array $attachments )
Add attachments
$attachments addBcc( string|array $email , string|null $name null )
Add Bcc
$email Null to get, String with email, Array with email as key, name as value or email as value (without name)
$name optional null addCc( string|array $email , string|null $name null )
Add Cc
$email Null to get, String with email, Array with email as key, name as value or email as value (without name)
$name optional null addHeaders( array $headers )
Add header for the message
$headers addTo( string|array $email , string|null $name null )
Add To
$email Null to get, String with email, Array with email as key, name as value or email as value (without name)
$name optional null 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->attachments('path/to/file'); Attach a file with a different filename:
$email->attachments(['custom_name.txt' => 'path/to/file.txt']);
Attach a file and specify additional properties:
$email->attachments(['custom_name.png' => [
'file' => 'path/to/file',
'mimetype' => 'image/png',
'contentId' => 'abc123',
'contentDisposition' => false
]
]); Attach a file from string and specify additional properties:
$email->attachments(['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.
$attachments optional null Cake\Mailer\Emailbcc( string|array|null $email null , string|null $name null )
Bcc
$email optional null Null to get, String with email, Array with email as key, name as value or email as value (without name)
$name optional null Cake\Mailer\Emailcc( string|array|null $email null , string|null $name null )
Cc
$email optional null Null to get, String with email, Array with email as key, name as value or email as value (without name)
$name optional null Cake\Mailer\Emailcharset( string|null $charset null )
Charset setter/getter
$charset optional null 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
$key The configuration name to read/write. Or an array of multiple transports to set.
Cake\Mailer\AbstractTransport|null $config optional null Either an array of configuration data, or a transport instance.
configuredTransport( )
Returns an array containing the named transport configurations
createFromArray( array $config )
Configures an email instance object from serialized config.
$config deliver( string|array|null $to null , string|null $subject null , string|array|null $message null , string|array $transportConfig 'default' , boolean $send true )
Static method to fast create an instance of \Cake\Mailer\Email
$to optional null $subject optional null $message optional null $transportConfig optional 'default' $send optional true Cake\Mailer\Emaildomain( string|null $domain null )
Domain as top level (the part after @)
$domain optional null Cake\Mailer\EmaildropTransport( string $key )
Delete transport configuration.
$key emailFormat( string|null $format null )
Email format
$format optional null Cake\Mailer\EmailemailPattern( string|boolean|null $regex false )
EmailPattern setter/getter
$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
Cake\Mailer\Emailfrom( string|array|null $email null , string|null $name null )
From
$email optional null Null to get, String with email, Array with email as key, name as value or email as value (without name)
$name optional null Cake\Mailer\EmailgetAttachments( )
Gets attachments to the email message.
getConfigTransport( string $key )
Gets current transport configuration.
$key getHeaders( array $include [] )
Get list of headers
fromreplyToreadReceiptreturnPathtoccbccsubject$include optional [] getOriginalSubject( )
Get original subject without encoding
getProfile( )
Gets the configuration profile to use for this instance.
getReadReceipt( )
Gets Read Receipt (Disposition-Notification-To header).
getTransport( )
Gets the transport.
Cake\Mailer\AbstractTransportheaderCharset( string|null $charset null )
HeaderCharset setter/getter
$charset optional null helpers( array|null $helpers null )
Helpers to be used in render
$helpers optional null Cake\Mailer\EmailjsonSerialize( )
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:
JsonSerializable::jsonSerialize() message( string|null $type null )
Get generated message (used by transport classes)
$type optional null messageId( boolean|string|null $message null )
Message-ID
$message optional null Cake\Mailer\Emailprofile( null|string|array $config null )
Get/Set the configuration profile to use for this instance.
$config optional null String with configuration name, or an array with config or null to return current config.
Cake\Mailer\EmailreadReceipt( string|array|null $email null , string|null $name null )
Read Receipt (Disposition-Notification-To header)
$email optional null Null to get, String with email, Array with email as key, name as value or email as value (without name)
$name optional null Cake\Mailer\EmailreplyTo( string|array|null $email null , string|null $name null )
Reply-To
$email optional null Null to get, String with email, Array with email as key, name as value or email as value (without name)
$name optional null Cake\Mailer\Emailreset( )
Reset all the internal variables to be able to send out a new email.
returnPath( string|array|null $email null , string|null $name null )
Return Path
$email optional null Null to get, String with email, Array with email as key, name as value or email as value (without name)
$name optional null Cake\Mailer\Emailsend( string|array|null $content null )
Send an email using the specified content, template and layout
$content optional null sender( string|array|null $email null , string|null $name null )
Sender
$email optional null Null to get, String with email, Array with email as key, name as value or email as value (without name)
$name optional null Cake\Mailer\Emailserialize( )
Serializes the Email object.
Serializable::serialize() 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->attachments('path/to/file'); Attach a file with a different filename:
$email->attachments(['custom_name.txt' => 'path/to/file.txt']);
Attach a file and specify additional properties:
$email->attachments(['custom_name.png' => [
'file' => 'path/to/file',
'mimetype' => 'image/png',
'contentId' => 'abc123',
'contentDisposition' => false
]
]); Attach a file from string and specify additional properties:
$email->attachments(['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.
$attachments setBcc( string|array $email , string|null $name null )
Sets "bcc" address.
$email String with email, Array with email as key, name as value or email as value (without name)
$name optional null setCc( string|array $email null , string|null $name null )
Sets "cc" address.
$email optional null String with email, Array with email as key, name as value or email as value (without name)
$name optional null setCharset( string|null $charset )
Charset setter.
$charset 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
$key The configuration name to write. Or an array of multiple transports to set.
Cake\Mailer\AbstractTransport|null $config optional null Either an array of configuration data, or a transport instance. Null when using key as array.
setDomain( string $domain )
Sets domain.
Domain as top level (the part after @).
$domain setEmailFormat( string $format )
Sets email format.
$format setEmailPattern( string|null $regex )
EmailPattern setter/getter
$regex The pattern to use for email address validation, null to unset the pattern and make use of filter_var() instead.
setFrom( string|array $email , string|null $name null )
Sets "from" address.
$email Null to get, String with email, Array with email as key, name as value or email as value (without name)
$name optional null setHeaderCharset( string|null $charset )
HeaderCharset setter.
$charset setHeaders( array $headers )
Sets headers for the message
$headers setHelpers( array $helpers )
Sets helpers to be used when rendering.
$helpers setLayout( string|null $layout )
Sets layout.
$layout setMessageId( boolean|string $message )
Sets message ID.
$message setPriority( integer|null $priority )
Sets priority.
$priority setProfile( string|array $config )
Sets the configuration profile to use for this instance.
$config String with configuration name, or an array with config.
setReadReceipt( string|array $email , string|null $name null )
Sets Read Receipt (Disposition-Notification-To header).
$email String with email, Array with email as key, name as value or email as value (without name)
$name optional null setReplyTo( string|array $email , string|null $name null )
Sets "Reply-To" address.
$email String with email, Array with email as key, name as value or email as value (without name)
$name optional null setReturnPath( string|array $email , string|null $name null )
Return Path
$email String with email, Array with email as key, name as value or email as value (without name)
$name optional null setSender( string|array $email , string|null $name null )
Sets "sender" address.
$email String with email, Array with email as key, name as value or email as value (without name)
$name optional null setSubject( string $subject )
Sets subject.
$subject setTemplate( string|null $template )
Sets template.
$template setTheme( string $theme )
Sets theme to use when rendering.
$theme setTo( string|array $email , string|null $name null )
Sets "to" address.
$email String with email, Array with email as key, name as value or email as value (without name)
$name optional null 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.
Cake\Mailer\AbstractTransport $name Either the name of a configured transport, or a transport instance.
setViewRenderer( string $viewClass )
Sets view class for render.
$viewClass setViewVars( array $viewVars )
Sets variables to be set on render.
$viewVars subject( string|null $subject null )
Get/Set Subject.
$subject optional null Cake\Mailer\Emailtemplate( boolean|string $template false , boolean|string $layout false )
Template and layout
$template optional false $layout optional false Cake\Mailer\Emailtheme( string|null $theme null )
Theme to use when rendering
$theme optional null Cake\Mailer\Emailto( string|array|null $email null , string|null $name null )
To
$email optional null Null to get, String with email, Array with email as key, name as value or email as value (without name)
$name optional null Cake\Mailer\Emailtransport( 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.
Cake\Mailer\AbstractTransport|null $name optional null Either the name of a configured transport, or a transport instance.
Cake\Mailer\AbstractTransport|Cake\Mailer\Emailunserialize( string $data )
Unserializes the Email object.
$data Cake\Mailer\EmailSerializable::unserialize() viewRender( string|null $viewClass null )
View class for render
$viewClass optional null Cake\Mailer\EmailviewVars( array|null $viewVars null )
Variables to be set on render
$viewVars optional null Cake\Mailer\Emailconfig( 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.
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);
$key $config optional null configured( )
Returns an array containing the named configurations
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.
$config dsnClassMap( array $map null )
Returns or updates the DSN class map for this class.
$map optional null getConfig( string $key )
Reads existing configuration.
$key getDsnClassMap( )
Returns the DSN class map for this class.
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: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.
$dsn 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.
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);
$key $config optional null setDsnClassMap( array $map )
Updates the DSN class map for this class.
$map createView( string|null $viewClass null )
Constructs the view class instance based on the current configuration.
$viewClass optional null Cake\View\ViewCake\View\Exception\MissingViewExceptionset( string|array $name , mixed $value null )
Saves a variable or an associative array of variables for use inside a template.
$name $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.
viewBuilder( )
Get the view builder being used.
Cake\View\ViewBuilderviewOptions( 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().
$options optional null $merge optional true Whether to merge with or override existing valid View options. Defaults to true.
protected string|null
The application wide charset, used to encode headers and body
null
protected array
List of files that should be attached to the email.
Only absolute paths
[]
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
[]
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
[]
protected array
Define Content-Type charset name
[
'ISO-2022-JP-MS' => 'ISO-2022-JP'
] protected string
Domain for messageId generation. Needs to be manually set for CLI mailing as env('HTTP_HOST') is empty
null
protected static array
An array mapping url schemes to fully qualified Transport class names
[
'debug' => 'Cake\Mailer\Transport\DebugTransport',
'mail' => 'Cake\Mailer\Transport\MailTransport',
'smtp' => 'Cake\Mailer\Transport\SmtpTransport',
] 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
protected array
Associative array of a user defined headers Keys will be prefixed 'X-' as per RFC2822 Section 4.7.5
[]
protected array
A copy of the configuration profile for this instance. This copy can be modified with Email::profile().
[]
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
[]
protected Cake\Mailer\AbstractTransport|null
The transport instance to use for sending mail.
null
public string|null
Charset the email header is sent in If null, the $charset property will be used as default
null
© 2005–2017 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.4/class-Cake.Mailer.Email.html