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

Package: Cake\Network\Email
Copyright: Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
License: MIT License
Location: Cake/Network/Email/CakeEmail.php

Constants summary

string

EMAIL_CLIENT ¶

'CakePHP Email'
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

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

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

array

Carbon Copy
$_charset8bit protected

array

8Bit character sets
$_config protected

string|array

Configuration to transport
$_configClass protected

string

The class name used for email configuration.
$_contentTypeCharset protected

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
$_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
$_helpers protected

array

Helpers to be used in the render
$_htmlMessage protected

string

Html message
$_layout protected

string

Layout for the View
$_message protected

array

Final message to send
$_messageId protected

boolean|string

Message ID
$_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
$_template protected

string

Template for the view
$_textMessage protected

string

Text message
$_theme protected

array

Theme for the View
$_to protected

array

Recipient of the email
$_transportClass protected

AbstractTransport

Instance of transport class
$_transportName protected

string

What method should the email be sent
$_viewRender protected

string

View for render
$_viewVars protected

array

Vars to sent to render
$charset public

string

Charset the email body is sent in
$headerCharset public

string

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

$this

Throws

SocketException

_applyConfig() protected ¶

_applyConfig( array $config )

Apply the config to an instance

Parameters

array $config: Configuration options.

Throws

ConfigureException

When configuration file cannot be found, or is missing the named config.

_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

array
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

array
An array of lines to add to the message

_createBoundary() protected ¶

_createBoundary( )

Create unique boundary identifier

_encode() protected ¶

_encode( string $text )

Encode the specified string using the current charset

Parameters

string $text: String to encode

Returns

string
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

string

_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

array

_getContentTransferEncoding() protected ¶

_getContentTransferEncoding( )

Return the Content-Transfer Encoding value based on the 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'

_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

string
File contents in base64 encoding

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

_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

$this

Throws

SocketException

_validateEmail() protected ¶

_validateEmail( string $email )

Validate email address

Parameters

string $email: Email

Throws

SocketException
If email address does not validate

_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

array
Wrapped message

addAttachments() public ¶

addAttachments( string|array $attachments )

Add attachments

Parameters

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

Returns

$this

Throws

SocketException

See

CakeEmail::attachments()

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

$this

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

$this

addHeaders() public ¶

addHeaders( array $headers )

Add header for the message

Parameters

array $headers: Headers to set.

Returns

$this

Throws

SocketException

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

$this

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

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

Throws

SocketException

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

array|CakeEmail

cc() public ¶

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

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

array|CakeEmail

charset() public ¶

charset( string $charset = null )

Charset setter/getter

Parameters

string $charset optional null: Character set.

Returns

string
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' => '[email protected]'));

Parameters

string|array $config optional null: String with configuration name (from email.php), array with config or null to return current config

Returns

string|array|CakeEmail
$this

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

CakeEmail
Instance of CakeEmail

Throws

SocketException

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

string|CakeEmail
$this

emailFormat() public ¶

emailFormat( string $format = null )

Email format

Parameters

string $format optional null: Formatting string.

Returns

string|CakeEmail
$this

Throws

SocketException

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

string|CakeEmail
$this

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

array|CakeEmail

Throws

SocketException

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

array

headerCharset() public ¶

headerCharset( string $charset = null )

HeaderCharset setter/getter

Parameters

string $charset optional null: Character set.

Returns

string
this->charset

helpers() public ¶

helpers( array $helpers = null )

Helpers to be used in render

Parameters

array $helpers optional null: Helpers list.

Returns

array|CakeEmail
$this

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|array
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

boolean|string|CakeEmail
$this

Throws

SocketException

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

array|CakeEmail

Throws

SocketException

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

array|CakeEmail

Throws

SocketException

reset() public ¶

reset( )

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

Returns

$this

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

array|CakeEmail

Throws

SocketException

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

array

Throws

SocketException

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

array|CakeEmail

Throws

SocketException

setHeaders() public ¶

setHeaders( array $headers )

Sets headers for the message

Parameters

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

Returns

$this

Throws

SocketException

subject() public ¶

subject( string $subject = null )

Get/Set Subject.

Parameters

string $subject optional null: Subject string.

Returns

string|CakeEmail
$this

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

array|CakeEmail
$this

theme() public ¶

theme( string $theme = null )

Theme to use when rendering

Parameters

string $theme optional null: Theme name.

Returns

string|CakeEmail
$this

to() public ¶

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

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

array|CakeEmail

transport() public ¶

transport( string $name = null )

Transport name

Parameters

string $name optional null: Transport name.

Returns

string|CakeEmail
$this

transportClass() public ¶

transportClass( )

Return the transport class

Returns

AbstractTransport

Throws

SocketException

viewRender() public ¶

viewRender( string $viewClass = null )

View class for render

Parameters

string $viewClass optional null: View class name.

Returns

string|CakeEmail
$this

viewVars() public ¶

viewVars( array $viewVars = null )

Variables to be set on render

Parameters

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

Returns

array|CakeEmail
$this

Properties detail

`$_appCharset` ¶

protected string

The application wide charset, used to encode headers and body

null

`$_attachments` ¶

protected array

List of files that should be attached to the email.

Only absolute paths

array()

`$_bcc` ¶

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

array()

`$_boundary` ¶

protected string

If set, boundary to use for multipart mime messages

null

`$_cc` ¶

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

array()

`$_charset8bit` ¶

protected array

8Bit character sets

array('UTF-8', 'SHIFT_JIS')

`$_config` ¶

protected string|array

Configuration to transport

array()

`$_configClass` ¶

protected string

The class name used for email configuration.

'EmailConfig'

`$_contentTypeCharset` ¶

protected array

Define Content-Type charset name

array(
    'ISO-2022-JP-MS' => 'ISO-2022-JP'
)

`$_domain` ¶

protected string

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

null

`$_emailFormat` ¶

protected string

What format should the email be sent in

'text'

`$_emailFormatAvailable` ¶

protected array

Available formats to be sent.

array('text', 'html', 'both')

`$_emailPattern` ¶

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

`$_from` ¶

protected array

The mail which the email is sent from

array()

`$_headers` ¶

protected array

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

array()

`$_helpers` ¶

protected array

Helpers to be used in the render

array('Html')

`$_htmlMessage` ¶

protected string

Html message

''

`$_layout` ¶

protected string

Layout for the View

'default'

`$_message` ¶

protected array

Final message to send

array()

`$_messageId` ¶

protected boolean|string

Message ID

true

`$_readReceipt` ¶

protected array

The read receipt email

array()

`$_replyTo` ¶

protected array

The email the recipient will reply to

array()

`$_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

array()

`$_sender` ¶

protected array

The sender email

array()

`$_subject` ¶

protected string

The subject of the email

''

`$_template` ¶

protected string

Template for the view

''

`$_textMessage` ¶

protected string

Text message

''

`$_theme` ¶

protected array

Theme for the View

null

`$_to` ¶

protected array

Recipient of the email

array()

`$_transportClass` ¶

protected AbstractTransport

Instance of transport class

null

`$_transportName` ¶

protected string

What method should the email be sent

'Mail'

`$_viewRender` ¶

protected string

View for render

'View'

`$_viewVars` ¶

protected array

Vars to sent to render

array()

`$charset` ¶

public string

Charset the email body is sent in

'utf-8'

`$headerCharset` ¶

public string

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

null

Packages

Classes

Class CakeEmail

Constants summary

Properties summary

Method Summary

__construct() public

_addEmail() protected

_applyConfig() protected

_attachFiles() protected

_attachInlineFiles() protected

_createBoundary() protected

_encode() protected

_encodeString() protected

_formatAddress() protected

_getContentTransferEncoding() protected

_getContentTypeCharset() protected

_getTypes() protected

_readFile() protected

_render() protected

_renderTemplates() protected

_setEmail() protected

_setEmailSingle() protected

_validateEmail() protected

_wrap() protected

addAttachments() public

addBcc() public

addCc() public

addHeaders() public

addTo() public

attachments() public

bcc() public

cc() public

charset() public

config() public

deliver() public static

domain() public

emailFormat() public

emailPattern() public

from() public

getHeaders() public

headerCharset() public

helpers() public

message() public

messageId() public

readReceipt() public

replyTo() public

reset() public

returnPath() public

send() public

sender() public

setHeaders() public

subject() public

template() public

theme() public

to() public

transport() public

transportClass() public

viewRender() public

viewVars() public

Method Detail

__construct() public ¶

Parameters

_addEmail() protected ¶

Parameters

Returns

Throws

_applyConfig() protected ¶

Parameters

Throws

_attachFiles() protected ¶

Parameters

Returns

_attachInlineFiles() protected ¶

Parameters

Returns

_createBoundary() protected ¶

_encode() protected ¶

Parameters

Returns