CakePHP
  • Documentation
    • Book
    • API
    • Videos
    • Reporting Security Issues
    • Privacy Policy
    • Logos & Trademarks
  • Business Solutions
  • Swag
  • Road Trip
  • Team
  • Community
    • Community
    • Get Involved
    • Issues (GitHub)
    • Bakery
    • Featured Resources
    • Training
    • Meetups
    • My CakePHP
    • CakeFest
    • Newsletter
    • Linkedin
    • YouTube
    • Facebook
    • Twitter
    • Mastodon
    • Help & Support
    • Forum
    • Stack Overflow
    • Slack
    • Paid Support
CakePHP

C CakePHP 2.7 API

  • Overview
  • Tree
  • Deprecated
  • Version:
    • 2.7
      • 4.2
      • 4.1
      • 4.0
      • 3.9
      • 3.8
      • 3.7
      • 3.6
      • 3.5
      • 3.4
      • 3.3
      • 3.2
      • 3.1
      • 3.0
      • 2.10
      • 2.9
      • 2.8
      • 2.7
      • 2.6
      • 2.5
      • 2.4
      • 2.3
      • 2.2
      • 2.1
      • 2.0
      • 1.3
      • 1.2

Packages

  • Cake
    • Cache
      • Engine
    • Configure
    • Console
      • Command
        • Task
    • Controller
      • Component
        • Acl
        • Auth
    • Core
    • Error
    • Event
    • I18n
    • Log
      • Engine
    • Model
      • Behavior
      • Datasource
        • Database
        • Session
      • Validator
    • Network
      • Email
      • Http
    • Routing
      • Filter
      • Route
    • TestSuite
      • Coverage
      • Fixture
      • Reporter
    • Utility
    • View
      • Helper

Classes

  • AbstractTransport
  • CakeEmail
  • DebugTransport
  • MailTransport
  • SmtpTransport

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

  • __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
CakeEmail
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
CakeEmail

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

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
CakeEmail

addHeaders() public ¶

addHeaders( array $headers )

Add header for the message

Parameters
array $headers
Headers to set.
Returns
CakeEmail
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
CakeEmail

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

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

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

emailFormat() public ¶

emailFormat( string $format = null )

Email format

Parameters
string $format optional null
Formatting string.
Returns
string|CakeEmail
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

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

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

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
CakeEmail
Throws
SocketException

subject() public ¶

subject( string $subject = null )

Get/Set Subject.

Parameters
string $subject optional null
Subject string.
Returns
string|CakeEmail

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

theme() public ¶

theme( string $theme = null )

Theme to use when rendering

Parameters
string $theme optional null
Theme name.
Returns
string|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
array|CakeEmail

transport() public ¶

transport( string $name = null )

Transport name

Parameters
string $name optional null
Transport name.
Returns
string|CakeEmail

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

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

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'

$_configInstance ¶

protected EmailConfig

An instance of the EmailConfig class can be set here

$_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
OpenHub
Rackspace
Rackspace
  • Business Solutions
  • Showcase
  • Documentation
  • Book
  • API
  • Videos
  • Reporting Security Issues
  • Privacy Policy
  • Logos & Trademarks
  • Community
  • Get Involved
  • Issues (GitHub)
  • Bakery
  • Featured Resources
  • Training
  • Meetups
  • My CakePHP
  • CakeFest
  • Newsletter
  • Linkedin
  • YouTube
  • Facebook
  • Twitter
  • Mastodon
  • Help & Support
  • Forum
  • Stack Overflow
  • Slack
  • Paid Support

Generated using CakePHP API Docs