Class CakeEmail
CakePHP email class.
This class is used for handling Internet Message Format based based on the standard outlined in http://www.rfc-editor.org/rfc/rfc2822.txt
Copyright: Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
License: MIT License
Location: Cake/Network/Email/CakeEmail.php
Constants summary
Properties summary
-
$_appCharset
protectedstring
The application wide charset, used to encode headers and body -
$_attachments
protectedarray
List of files that should be attached to the email. -
$_bcc
protectedarray
Blind Carbon Copy -
$_boundary
protectedstring
If set, boundary to use for multipart mime messages -
$_cc
protectedarray
Carbon Copy -
$_charset8bit
protectedarray
8Bit character sets -
$_config
protectedstring|array
Configuration to transport -
$_configClass
protectedstring
The class name used for email configuration. -
$_configInstance
protectedEmailConfig
An instance of the EmailConfig class can be set here -
$_contentTypeCharset
protectedarray
Define Content-Type charset name -
$_domain
protectedstring
Domain for messageId generation. Needs to be manually set for CLI mailing as env('HTTP_HOST') is empty
-
$_emailFormat
protectedstring
What format should the email be sent in -
$_emailFormatAvailable
protectedarray
Available formats to be sent. -
$_emailPattern
protectedstring
Regex for email validation -
$_from
protectedarray
The mail which the email is sent from -
$_headers
protectedarray
Associative array of a user defined headers Keys will be prefixed 'X-' as per RFC2822 Section 4.7.5
-
$_helpers
protectedarray
Helpers to be used in the render -
$_htmlMessage
protectedstring
Html message -
$_layout
protectedstring
Layout for the View -
$_message
protectedarray
Final message to send -
$_messageId
protectedboolean|string
Message ID -
$_readReceipt
protectedarray
The read receipt email -
$_replyTo
protectedarray
The email the recipient will reply to -
$_returnPath
protectedarray
The mail that will be used in case of any errors like - Remote mailserver down - Remote user has exceeded his quota - Unknown user
-
$_sender
protectedarray
The sender email -
$_subject
protectedstring
The subject of the email -
$_template
protectedstring
Template for the view -
$_textMessage
protectedstring
Text message -
$_theme
protectedarray
Theme for the View -
$_to
protectedarray
Recipient of the email -
$_transportClass
protectedInstance of transport class -
$_transportName
protectedstring
What method should the email be sent -
$_viewRender
protectedstring
View for render -
$_viewVars
protectedarray
Vars to sent to render -
$charset
publicstring
Charset the email body is sent in -
$headerCharset
publicstring
Charset the email header is sent in If null, the $charset property will be used as default
Method Summary
-
__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. -
_createBoundary() protected
Create unique boundary identifier -
_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 charset -
_getContentTypeCharset() protected
Return charset value for Content-Type. -
_getTypes() protected
Gets the text body types that are in this email message -
_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. If there is no template set, the $content will be returned in a hash of the text content types for the email.
-
_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
Configuration to use when send email -
deliver() public static
Static method to fast create an instance of CakeEmail -
domain() public
Domain as top level (the part after @) -
emailFormat() public
Email format -
emailPattern() public
EmailPattern setter/getter -
from() public
From -
getHeaders() public
Get list of headers -
headerCharset() public
HeaderCharset setter/getter -
helpers() public
Helpers to be used in render -
message() public
Get generated message (used by transport classes) -
messageId() public
Message-ID -
readReceipt() public
Read Receipt (Disposition-Notification-To header) -
replyTo() public
Reply-To -
reset() public
Reset all CakeEmail 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 -
setHeaders() public
Sets headers for the message -
subject() public
Get/Set Subject. -
template() public
Template and layout -
theme() public
Theme to use when rendering -
to() public
To -
transport() public
Transport name -
transportClass() public
Return the transport class -
viewRender() public
View class for render -
viewVars() public
Variables to be set on render
Method Detail
__construct() public ¶
__construct( array|string $config = null )
Constructor
Parameters
- array|string $config optional null
- Array of configs, or string to load configs from email.php
_addEmail() 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
Throws
_applyConfig() protected ¶
_applyConfig( array $config )
Apply the config to an instance
Parameters
- array $config
- Configuration options.
Throws
_attachFiles() protected ¶
_attachFiles( string $boundary = null )
Attach non-embedded files by adding file contents inside boundaries.
Parameters
- string $boundary optional null
- Boundary to use. If null, will default to $this->_boundary
Returns
An array of lines to add to the message
_attachInlineFiles() protected ¶
_attachInlineFiles( string $boundary = null )
Attach inline/embedded files to the message.
Parameters
- string $boundary optional null
- Boundary to use. If null, will default to $this->_boundary
Returns
An array of lines to add to the message
_encode() protected ¶
_encode( string $text )
Encode the specified string using the current charset
Parameters
- string $text
- String to encode
Returns
Encoded string
_encodeString() 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
_formatAddress() 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
_getContentTransferEncoding() protected ¶
_getContentTransferEncoding( )
Return the Content-Transfer Encoding value based on the set charset
Returns
_getContentTypeCharset() protected ¶
_getContentTypeCharset( )
Return charset value for Content-Type.
Checks fallback/compatibility types which include workarounds for legacy japanese character sets.
Returns
_getTypes() protected ¶
_getTypes( )
Gets the text body types that are in this email message
Returns
Array of types. Valid types are 'text' and 'html'
_readFile() 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
File contents in base64 encoding
_render() protected ¶
_render( array $content )
Render the body of the email.
Parameters
- array $content
- Content to render
Returns
Email body ready to be sent
_renderTemplates() 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
The rendered content with html and text keys.
_setEmail() 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
_setEmailSingle() 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
Throws
_validateEmail() protected ¶
_validateEmail( string $email )
Validate email address
Parameters
- string $email
Throws
_wrap() protected ¶
_wrap( string $message , integer $wrapLength = CakeEmail::LINE_LENGTH_MUST )
Wrap the message to follow the RFC 2822 - 2.1.1
Parameters
- string $message
- Message to wrap
- integer $wrapLength optional CakeEmail::LINE_LENGTH_MUST
- The line length
Returns
Wrapped message
addAttachments() public ¶
addAttachments( string|array $attachments )
Add attachments
Parameters
- string|array $attachments
- String with the filename or array with filenames
Returns
Throws
See
addBcc() public ¶
addBcc( string|array $email , string $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 $name optional null
- Name
Returns
addCc() public ¶
addCc( string|array $email , string $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 $name optional null
- Name
Returns
addHeaders() public ¶
addHeaders( array $headers )
Add header for the message
Parameters
- array $headers
- Headers to set.
Returns
Throws
addTo() public ¶
addTo( string|array $email , string $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 $name optional null
- Name
Returns
attachments() public ¶
attachments( string|array $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(array('custom_name.txt' => 'path/to/file.txt'));
Attach a file and specify additional properties:
$email->attachments(array('custom_name.png' => array( 'file' => 'path/to/file', 'mimetype' => 'image/png', 'contentId' => 'abc123', 'contentDisposition' => false ));
Attach a file from string and specify additional properties:
$email->attachments(array('custom_name.png' => array( '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 optional null
- String with the filename or array with filenames
Returns
Throws
bcc() public ¶
bcc( string|array $email = null , string $name = null )
Bcc
Parameters
- string|array $email optional null
Null to get, String with email, Array with email as key, name as value or email as value (without name)
- string $name optional null
- Name
Returns
CakeEmail
cc() public ¶
cc( string|array $email = null , string $name = null )
Cc
Parameters
- string|array $email optional null
Null to get, String with email, Array with email as key, name as value or email as value (without name)
- string $name optional null
- Name
Returns
CakeEmail
charset() public ¶
charset( string $charset = null )
Charset setter/getter
Parameters
- string $charset optional null
- Character set.
Returns
this->charset
config() public ¶
config( string|array $config = null )
Configuration to use when send email
Usage
Load configuration from app/Config/email.php
:
$email->config('default');
Merge an array of configuration into the instance:
$email->config(array('to' => 'bill@example.com'));
Parameters
- string|array $config optional null
- String with configuration name (from email.php), array with config or null to return current config
Returns
CakeEmail
deliver() public static ¶
deliver( string|array $to = null , string $subject = null , string|array $message = null , string|array $transportConfig = 'fast' , boolean $send = true )
Static method to fast create an instance of CakeEmail
Parameters
- string|array $to optional null
- Address to send (see CakeEmail::to()). If null, will try to use 'to' from transport config
- string $subject optional null
- String of subject or null to use 'subject' from transport config
- string|array $message optional null
- String with message or array with variables to be used in render
- string|array $transportConfig optional 'fast'
- String to use config from EmailConfig or array with configs
- boolean $send optional true
- Send the email or just return the instance pre-configured
Returns
Throws
domain() public ¶
domain( string $domain = null )
Domain as top level (the part after @)
Parameters
- string $domain optional null
- Manually set the domain for CLI mailing
Returns
CakeEmail
emailFormat() public ¶
emailFormat( string $format = null )
Email format
Parameters
- string $format optional null
- Formatting string.
Returns
CakeEmail
Throws
emailPattern() public ¶
emailPattern( string|boolean|null $regex = false )
EmailPattern setter/getter
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
CakeEmail
from() public ¶
from( string|array $email = null , string $name = null )
From
Parameters
- string|array $email optional null
Null to get, String with email, Array with email as key, name as value or email as value (without name)
- string $name optional null
- Name
Returns
CakeEmail
Throws
getHeaders() public ¶
getHeaders( array $include = array() )
Get list of headers
Includes:
from
replyTo
readReceipt
returnPath
to
cc
bcc
subject
Parameters
- array $include optional array()
- List of headers.
Returns
headerCharset() public ¶
headerCharset( string $charset = null )
HeaderCharset setter/getter
Parameters
- string $charset optional null
- Character set.
Returns
this->charset
helpers() public ¶
helpers( array $helpers = null )
Helpers to be used in render
Parameters
- array $helpers optional null
- Helpers list.
Returns
CakeEmail
message() public ¶
message( string $type = null )
Get generated message (used by transport classes)
Parameters
- string $type optional null
- Use MESSAGE_* constants or null to return the full message as array
Returns
String if have type, array if type is null
messageId() public ¶
messageId( boolean|string $message = null )
Message-ID
Parameters
- boolean|string $message optional null
- True to generate a new Message-ID, False to ignore (not send in email), String to set as Message-ID
Returns
CakeEmail
Throws
readReceipt() public ¶
readReceipt( string|array $email = null , string $name = null )
Read Receipt (Disposition-Notification-To header)
Parameters
- string|array $email optional null
Null to get, String with email, Array with email as key, name as value or email as value (without name)
- string $name optional null
- Name
Returns
CakeEmail
Throws
replyTo() public ¶
replyTo( string|array $email = null , string $name = null )
Reply-To
Parameters
- string|array $email optional null
Null to get, String with email, Array with email as key, name as value or email as value (without name)
- string $name optional null
- Name
Returns
CakeEmail
Throws
returnPath() public ¶
returnPath( string|array $email = null , string $name = null )
Return Path
Parameters
- string|array $email optional null
Null to get, String with email, Array with email as key, name as value or email as value (without name)
- string $name optional null
- Name
Returns
CakeEmail
Throws
send() public ¶
send( string|array $content = null )
Send an email using the specified content, template and layout
Parameters
- string|array $content optional null
- String with message or array with messages
Returns
Throws
sender() public ¶
sender( string|array $email = null , string $name = null )
Sender
Parameters
- string|array $email optional null
Null to get, String with email, Array with email as key, name as value or email as value (without name)
- string $name optional null
- Name
Returns
CakeEmail
Throws
setHeaders() public ¶
setHeaders( array $headers )
Sets headers for the message
Parameters
- array $headers
- Associative array containing headers to be set.
Returns
Throws
template() public ¶
template( boolean|string $template = false , boolean|string $layout = false )
Template and layout
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
CakeEmail
theme() public ¶
theme( string $theme = null )
Theme to use when rendering
Parameters
- string $theme optional null
- Theme name.
Returns
CakeEmail
to() public ¶
to( string|array $email = null , string $name = null )
To
Parameters
- string|array $email optional null
Null to get, String with email, Array with email as key, name as value or email as value (without name)
- string $name optional null
- Name
Returns
CakeEmail
viewRender() public ¶
viewRender( string $viewClass = null )
View class for render
Parameters
- string $viewClass optional null
- View class name.
Returns
CakeEmail
viewVars() public ¶
viewVars( array $viewVars = null )
Variables to be set on render
Parameters
- array $viewVars optional null
- Variables to set for view.
Returns
CakeEmail
Properties detail
$_attachments ¶
List of files that should be attached to the email.
Only absolute paths
array()
$_bcc ¶
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
array()
$_cc ¶
Carbon Copy
List of email's that should receive a copy of the email. The Recipient WILL be able to see this list
array()
$_contentTypeCharset ¶
Define Content-Type charset name
array( 'ISO-2022-JP-MS' => 'ISO-2022-JP' )
$_domain ¶
Domain for messageId generation. Needs to be manually set for CLI mailing as env('HTTP_HOST') is empty
null
$_emailFormatAvailable ¶
Available formats to be sent.
array('text', 'html', 'both')
$_emailPattern ¶
Regex for email validation
If null, filter_var() will be used. Use the emailPattern() method to set a custom pattern.'
self::EMAIL_PATTERN
$_headers ¶
Associative array of a user defined headers Keys will be prefixed 'X-' as per RFC2822 Section 4.7.5
array()
$_returnPath ¶
The mail that will be used in case of any errors like - Remote mailserver down - Remote user has exceeded his quota - Unknown user
array()
$headerCharset ¶
Charset the email header is sent in If null, the $charset property will be used as default
null