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

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.
  • $_configInstance protected
    EmailConfig
    An instance of the EmailConfig class can be set here
  • $_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

Method Detail

__construct()source 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()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

CakeEmail

Throws

SocketException

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

_createBoundary( )

Create unique boundary identifier

_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 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'

_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

CakeEmail

_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

CakeEmail

Throws

SocketException

_validateEmail()source protected 

_validateEmail( string $email )

Validate email address

Parameters

string $email
Email

Throws

SocketException
If email address does not validate

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

addAttachments( string|array $attachments )

Add attachments

Parameters

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

Returns

CakeEmail

Throws

SocketException

See

CakeEmail::attachments()

addBcc()source 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

CakeEmail

addCc()source 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

CakeEmail

addHeaders()source public 

addHeaders( array $headers )

Add header for the message

Parameters

array $headers
Headers to set.

Returns

CakeEmail

Throws

SocketException

addTo()source 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

CakeEmail

attachments()source 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
Either the array of attachments when getting or $this when setting.

Throws

SocketException

bcc()source 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()source 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

array|CakeEmail

charset()source public 

charset( string $charset null )

Charset setter/getter

Parameters

string $charset optional null
Character set.

Returns

string
this->charset

config()source 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

deliver()source 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()source 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

emailFormat()source public 

emailFormat( string $format null )

Email format

Parameters

string $format optional null
Formatting string.

Returns

string|CakeEmail

Throws

SocketException

emailPattern()source 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

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

headerCharset( string $charset null )

HeaderCharset setter/getter

Parameters

string $charset optional null
Character set.

Returns

string
this->charset

helpers()source public 

helpers( array $helpers null )

Helpers to be used in render

Parameters

array $helpers optional null
Helpers list.

Returns

array|CakeEmail

message()source 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()source 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

Throws

SocketException

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

reset( )

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

Returns

CakeEmail

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

setHeaders( array $headers )

Sets headers for the message

Parameters

array $headers
Associative array containing headers to be set.

Returns

CakeEmail

Throws

SocketException

subject()source public 

subject( string $subject null )

Get/Set Subject.

Parameters

string $subject optional null
Subject string.

Returns

string|CakeEmail

template()source 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

theme()source public 

theme( string $theme null )

Theme to use when rendering

Parameters

string $theme optional null
Theme name.

Returns

string|CakeEmail

to()source 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

array|CakeEmail

transport()source public 

transport( string $name null )

Transport name

Parameters

string $name optional null
Transport name.

Returns

string|CakeEmail

transportClass()source public 

transportClass( )

Return the transport class

Returns

AbstractTransport

Throws

SocketException

viewRender()source public 

viewRender( string $viewClass null )

View class for render

Parameters

string $viewClass optional null
View class name.

Returns

string|CakeEmail

viewVars()source public 

viewVars( array $viewVars null )

Variables to be set on render

Parameters

array $viewVars optional null
Variables to set for view.

Returns

array|CakeEmail

Properties detail

$_appCharsetsource

protected string

The application wide charset, used to encode headers and body

null

$_attachmentssource

protected array

List of files that should be attached to the email.

Only absolute paths

array()

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

array()

$_boundarysource

protected string

If set, boundary to use for multipart mime messages

null

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

array()

$_charset8bitsource

protected array

8Bit character sets

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

$_configsource

protected string|array

Configuration to transport

array()

$_configClasssource

protected string

The class name used for email configuration.

'EmailConfig'

$_configInstancesource

protected EmailConfig

An instance of the EmailConfig class can be set here

$_contentTypeCharsetsource

protected array

Define Content-Type charset name

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

null

$_emailFormatsource

protected string

What format should the email be sent in

'text'

$_emailFormatAvailablesource

protected array

Available formats to be sent.

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

array()

$_headerssource

protected array

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

array()

$_helperssource

protected array

Helpers to be used in the render

array('Html')

$_htmlMessagesource

protected string

Html message

''

$_layoutsource

protected string

Layout for the View

'default'

$_messagesource

protected array

Final message to send

array()

$_messageIdsource

protected boolean|string

Message ID

true

$_readReceiptsource

protected array

The read receipt email

array()

$_replyTosource

protected array

The email the recipient will reply to

array()

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

array()

$_sendersource

protected array

The sender email

array()

$_subjectsource

protected string

The subject of the email

''

$_templatesource

protected string

Template for the view

''

$_textMessagesource

protected string

Text message

''

$_themesource

protected array

Theme for the View

null

$_tosource

protected array

Recipient of the email

array()

$_transportClasssource

protected AbstractTransport

Instance of transport class

null

$_transportNamesource

protected string

What method should the email be sent

'Mail'

$_viewRendersource

protected string

View for render

'View'

$_viewVarssource

protected array

Vars to sent to render

array()

$charsetsource

public string

Charset the email body is sent in

'utf-8'

$headerCharsetsource

public string

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

null

© 2005–2016 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.
http://api.cakephp.org/2.8/class-CakeEmail.html