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
    • IRC
    • Slack
    • Paid Support
CakePHP

C CakePHP 3.10 Red Velvet API

  • Project:
    • CakePHP
      • CakePHP
      • Authentication
      • Authorization
      • Chronos
      • Elastic Search
      • Queue
  • Version:
    • 3.10
      • 5.2
      • 5.1
      • 5.0
      • 4.6
      • 4.5
      • 4.4
      • 4.3
      • 4.2
      • 4.1
      • 4.0
      • 3.10
      • 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

Namespaces

  • Global
  • Cake
    • Auth
    • Cache
    • Collection
    • Command
    • Console
    • Controller
    • Core
    • Database
    • Datasource
    • Error
    • Event
    • Filesystem
    • Form
    • Http
    • I18n
    • Log
    • Mailer
      • Exception
      • Transport
    • Network
    • ORM
    • Routing
    • Shell
    • TestSuite
    • Utility
    • Validation
    • View

Class Email

CakePHP Email class.

This class is used for sending Internet Message Format based on the standard outlined in https://www.rfc-editor.org/rfc/rfc2822.txt

Configuration

Configuration for Email is managed by Email::config() and Email::configTransport(). Email::config() can be used to add or read a configuration profile for Email instances. Once made configuration profiles can be used to re-use across various email messages your application sends.

Namespace: Cake\Mailer

Constants

  • string
    EMAIL_PATTERN ¶
    '/^((?:[\\p{L}0-9.!#$%&\'*+\\/=?^_`{|}~-]+)*@[\\p{L}0-9-._]+)$/ui'

    Holds the regex pattern for email validation

  • int
    LINE_LENGTH_MUST ¶
    998

    Line length - no must more - RFC 2822 - 2.1.1

  • int
    LINE_LENGTH_SHOULD ¶
    78

    Line length - no should more - RFC 2822 - 2.1.1

  • string
    MESSAGE_HTML ¶
    'html'

    Type of message - HTML

  • string
    MESSAGE_TEXT ¶
    'text'

    Type of message - TEXT

Property Summary

  • $_appCharset protected
    string|null

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

    If set, boundary to use for multipart mime messages

  • $_cc protected
    array

    Carbon Copy

  • $_charset8bit protected
    array

    8Bit character sets

  • $_config protected static
    array

    Configuration sets.

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

  • $_dsnClassMap protected static deprecated
    string[]

    An array mapping url schemes to fully qualified Transport class names. Unused.

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

  • $_htmlMessage protected
    string

    Html message

  • $_message protected
    array

    Final message to send

  • $_messageId protected
    bool|string

    Message ID

  • $_priority protected
    int|null

    Contains the optional priority of the email.

  • $_profile protected
    array

    A copy of the configuration profile for this instance. This copy can be modified with Email::profile().

  • $_readReceipt protected
    array

    The read receipt email

  • $_registry public @property
    Cake\Core\ObjectRegistry
  • $_replyTo protected
    array

    List of email(s) that 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

  • $_textMessage protected
    string

    Text message

  • $_to protected
    array

    Recipient of the email

  • $_transferEncodingAvailable protected
    array

    Available encoding to be set for transfer.

  • $_transport protected
    Cake\Mailer\AbstractTransport|null

    The transport instance to use for sending mail.

  • $_validViewOptions public @property
    array
  • $_viewBuilder protected
    Cake\View\ViewBuilder

    The view builder instance being used.

  • $charset public
    string

    Charset the email body is sent in

  • $headerCharset public
    string|null

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

  • $transferEncoding protected
    string|null

    The email transfer encoding used. If null, the $charset property is used for determined the transfer encoding.

  • $viewClass public deprecated
    string|null

    The name of default View class.

  • $viewVars public
    array

    Variables for the view.

Method Summary

  • __clone() public

    Clone ViewBuilder instance when email object is cloned.

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

  • _checkViewVars() protected

    Iterates through hash to clean up and normalize.

  • _createBoundary() protected

    Create unique boundary identifier

  • _decode() protected

    Decode the specified string

  • _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 transferEncoding or set charset.

  • _getContentTypeCharset() protected

    Return charset value for Content-Type.

  • _getTypes() protected

    Gets the text body types that are in this email message

  • _logDelivery() protected

    Log the email message delivery.

  • _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 deprecated

    Add attachments to the email message

  • bcc() public deprecated

    Bcc

  • cc() public deprecated

    Cc

  • charset() public deprecated

    Charset setter/getter

  • config() public static deprecated

    This method can be used to define configuration adapters for an application or read existing configuration.

  • configTransport() public static deprecated

    Add or read transport configuration.

  • configured() public static

    Returns an array containing the named configurations

  • configuredTransport() public static deprecated

    Returns an array containing the named transport configurations

  • createFromArray() public

    Configures an email instance object from serialized config.

  • createView() public

    Constructs the view class instance based on the current configuration.

  • deliver() public static

    Static method to fast create an instance of \Cake\Mailer\Email

  • domain() public deprecated

    Domain as top level (the part after @)

  • drop() public static

    Drops a constructed adapter.

  • dropTransport() public static deprecated

    Delete transport configuration.

  • dsnClassMap() public static deprecated

    Returns or updates the DSN class map for this class.

  • emailFormat() public deprecated

    Email format

  • emailPattern() public deprecated

    EmailPattern setter/getter

  • flatten() protected

    Converts given value to string

  • from() public deprecated

    From

  • getAttachments() public

    Gets attachments to the email message.

  • getBcc() public

    Gets "bcc" address.

  • getCc() public

    Gets "cc" address.

  • getCharset() public

    Charset getter.

  • getConfig() public static

    Reads existing configuration.

  • getConfigOrFail() public static

    Reads existing configuration for a specific key.

  • getConfigTransport() public static deprecated

    Gets current transport configuration.

  • getDomain() public

    Gets domain.

  • getDsnClassMap() public static

    Returns the DSN class map for this class.

  • getEmailFormat() public

    Gets email format.

  • getEmailPattern() public

    EmailPattern setter/getter

  • getFrom() public

    Gets "from" address.

  • getHeaderCharset() public

    HeaderCharset getter.

  • getHeaders() public

    Get list of headers

  • getHelpers() public deprecated

    Gets helpers to be used when rendering.

  • getLayout() public deprecated

    Gets layout.

  • getMessageId() public

    Gets message ID.

  • getOriginalSubject() public

    Get original subject without encoding

  • getPriority() public

    Gets priority.

  • getProfile() public

    Gets the configuration profile to use for this instance.

  • getReadReceipt() public

    Gets Read Receipt (Disposition-Notification-To header).

  • getReplyTo() public

    Gets "Reply-To" address.

  • getReturnPath() public

    Gets return path.

  • getSender() public

    Gets the "sender" address. See rfc link below for full explanation.

  • getSubject() public

    Gets subject.

  • getTemplate() public deprecated

    Gets template.

  • getTheme() public deprecated

    Gets theme to use when rendering.

  • getTo() public

    Gets "to" address

  • getTransferEncoding() public

    TransferEncoding getter.

  • getTransport() public

    Gets the transport.

  • getViewRenderer() public

    Gets view class for render.

  • getViewVars() public

    Gets variables to be set on render.

  • headerCharset() public deprecated

    HeaderCharset setter/getter

  • helpers() public deprecated

    Helpers to be used in render

  • jsonSerialize() public

    Serializes the email object to a value that can be natively serialized and re-used to clone this email instance.

  • message() public

    Get generated message (used by transport classes)

  • messageId() public deprecated

    Message-ID

  • parseDsn() public static

    Parses a DSN into a valid connection configuration

  • profile() public deprecated

    Get/Set the configuration profile to use for this instance.

  • readReceipt() public deprecated

    Read Receipt (Disposition-Notification-To header)

  • replyTo() public deprecated

    Reply-To

  • reset() public

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

  • returnPath() public deprecated

    Return Path

  • send() public

    Send an email using the specified content, template and layout

  • sender() public deprecated

    Sender

  • serialize() public

    Serializes the Email object.

  • set() public

    Saves a variable or an associative array of variables for use inside a template.

  • setAttachments() public

    Add attachments to the email message

  • setBcc() public

    Sets "bcc" address.

  • setCc() public

    Sets "cc" address.

  • setCharset() public

    Charset setter.

  • setConfig() public static

    This method can be used to define configuration adapters for an application.

  • setConfigTransport() public static deprecated

    Sets transport configuration.

  • setDomain() public

    Sets domain.

  • setDsnClassMap() public static

    Updates the DSN class map for this class.

  • setEmailFormat() public

    Sets email format.

  • setEmailPattern() public

    EmailPattern setter/getter

  • setFrom() public

    Sets "from" address.

  • setHeaderCharset() public

    HeaderCharset setter.

  • setHeaders() public

    Sets headers for the message

  • setHelpers() public deprecated

    Sets helpers to be used when rendering.

  • setLayout() public deprecated

    Sets layout.

  • setMessageId() public

    Sets message ID.

  • setPriority() public

    Sets priority.

  • setProfile() public

    Sets the configuration profile to use for this instance.

  • setReadReceipt() public

    Sets Read Receipt (Disposition-Notification-To header).

  • setReplyTo() public

    Sets "Reply-To" address.

  • setReturnPath() public

    Return Path

  • setSender() public

    Sets the "sender" address. See rfc link below for full explanation.

  • setSubject() public

    Sets subject.

  • setTemplate() public deprecated

    Sets template.

  • setTheme() public deprecated

    Sets theme to use when rendering.

  • setTo() public

    Sets "to" address.

  • setTransferEncoding() public

    TransferEncoding setter.

  • setTransport() public

    Sets the transport.

  • setViewRenderer() public

    Sets view class for render.

  • setViewVars() public

    Sets variables to be set on render.

  • subject() public deprecated

    Get/Set Subject.

  • template() public deprecated

    Template and layout

  • theme() public deprecated

    Theme to use when rendering

  • to() public deprecated

    To

  • transport() public deprecated

    Get/set the transport.

  • unserialize() public

    Unserializes the Email object.

  • viewBuilder() public

    Get the view builder being used.

  • viewOptions() public deprecated

    Get/Set valid view options in the object's _validViewOptions property. The property is created as an empty array if it is not set. If called without any parameters it will return the current list of valid view options. See createView().

  • viewRender() public deprecated

    View class for render

  • viewVars() public deprecated

    Variables to be set on render

Method Detail

__clone() ¶ public

__clone(): void

Clone ViewBuilder instance when email object is cloned.

Returns
void

__construct() ¶ public

__construct(array|string|null $config = null)

Constructor

Parameters
array|string|null $config optional

Array of configs, or string to load configs from app.php

_addEmail() ¶ protected

_addEmail(string $varName, string|array $email, string $name): $this

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
InvalidArgumentException

_applyConfig() ¶ protected

_applyConfig(string|array $config): void

Apply the config to an instance

Parameters
string|array $config

Configuration options.

Returns
void
Throws
InvalidArgumentException
When using a configuration that doesn't exist.

_attachFiles() ¶ protected

_attachFiles(string|null $boundary = null): array

Attach non-embedded files by adding file contents inside boundaries.

Parameters
string|null $boundary optional

Boundary to use. If null, will default to $this->_boundary

Returns
array

_attachInlineFiles() ¶ protected

_attachInlineFiles(string|null $boundary = null): array

Attach inline/embedded files to the message.

Parameters
string|null $boundary optional

Boundary to use. If null, will default to $this->_boundary

Returns
array

_checkViewVars() ¶ protected

_checkViewVars(mixed $item, string $key): void

Iterates through hash to clean up and normalize.

Parameters
mixed $item

Reference to the view var value.

string $key

View var key.

Returns
void

_createBoundary() ¶ protected

_createBoundary(): void

Create unique boundary identifier

Returns
void

_decode() ¶ protected

_decode(string $text): string

Decode the specified string

Parameters
string $text

String to decode

Returns
string

_encode() ¶ protected

_encode(string $text): string

Encode the specified string using the current charset

Parameters
string $text

String to encode

Returns
string

_encodeString() ¶ protected

_encodeString(string $text, string $charset): string

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

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

Return the Content-Transfer Encoding value based on the set transferEncoding or set charset.

Returns
string

_getContentTypeCharset() ¶ protected

_getContentTypeCharset(): string

Return charset value for Content-Type.

Checks fallback/compatibility types which include workarounds for legacy japanese character sets.

Returns
string

_getTypes() ¶ protected

_getTypes(): array

Gets the text body types that are in this email message

Returns
array

_logDelivery() ¶ protected

_logDelivery(array $contents): void

Log the email message delivery.

Parameters
array $contents

The content with 'headers' and 'message' keys.

Returns
void

_readFile() ¶ protected

_readFile(string $path): string

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

_render() ¶ protected

_render(array $content): array

Render the body of the email.

Parameters
array $content

Content to render

Returns
array

_renderTemplates() ¶ protected

_renderTemplates(string $content): array

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

_setEmail() ¶ protected

_setEmail(string $varName, string|array $email, string $name): $this

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
Throws
InvalidArgumentException

_setEmailSingle() ¶ protected

_setEmailSingle(string $varName, string|array $email, string $name, string $throwMessage): $this

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
InvalidArgumentException

_validateEmail() ¶ protected

_validateEmail(string $email, string $context): void

Validate email address

Parameters
string $email

Email address to validate

string $context

Which property was set

Returns
void
Throws
InvalidArgumentException
If email address does not validate

_wrap() ¶ protected

_wrap(string $message, int $wrapLength = Email::LINE_LENGTH_MUST): array

Wrap the message to follow the RFC 2822 - 2.1.1

Parameters
string $message

Message to wrap

int $wrapLength optional

The line length

Returns
array

addAttachments() ¶ public

addAttachments(string|array $attachments): $this

Add attachments

Parameters
string|array $attachments

String with the filename or array with filenames

Returns
$this
Throws
InvalidArgumentException
See Also
\Cake\Mailer\Email::attachments()

addBcc() ¶ public

addBcc(string|array $email, string|null $name = null): $this

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|null $name optional

Name

Returns
$this

addCc() ¶ public

addCc(string|array $email, string|null $name = null): $this

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|null $name optional

Name

Returns
$this

addHeaders() ¶ public

addHeaders(array $headers): $this

Add header for the message

Parameters
array $headers

Headers to set.

Returns
$this

addTo() ¶ public

addTo(string|array $email, string|null $name = null): $this

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|null $name optional

Name

Returns
$this

attachments() ¶ public

attachments(string|array|null $attachments = null): array|$this

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->setAttachments('path/to/file');

Attach a file with a different filename:

$email->setAttachments(['custom_name.txt' => 'path/to/file.txt']);

Attach a file and specify additional properties:

$email->setAttachments(['custom_name.png' => [
     'file' => 'path/to/file',
     'mimetype' => 'image/png',
     'contentId' => 'abc123',
     'contentDisposition' => false
   ]
]);

Attach a file from string and specify additional properties:

$email->setAttachments(['custom_name.png' => [
     'data' => file_get_contents('path/to/file'),
     'mimetype' => 'image/png'
   ]
]);

The contentId key allows you to specify an inline attachment. In your email text, you can use <img src="cid:abc123" /> to display the image inline.

The contentDisposition key allows you to disable the Content-Disposition header, this can improve attachment compatibility with outlook email clients.

Parameters
string|array|null $attachments optional

String with the filename or array with filenames

Returns
array|$this
Throws
InvalidArgumentException

bcc() ¶ public

bcc(string|array|null $email = null, string|null $name = null): array|$this

Bcc

Parameters
string|array|null $email optional

Null to get, String with email, Array with email as key, name as value or email as value (without name)

string|null $name optional

Name

Returns
array|$this

cc() ¶ public

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

Cc

Parameters
string|array|null $email optional

Null to get, String with email, Array with email as key, name as value or email as value (without name)

string|null $name optional

Name

Returns
array|$this

charset() ¶ public

charset(string|null $charset = null): string

Charset setter/getter

Parameters
string|null $charset optional

Character set.

Returns
string

config() ¶ public static

config(string|array $key, array|null $config = null): array|null

This method can be used to define configuration adapters for an application or read existing configuration.

To change an adapter's configuration at runtime, first drop the adapter and then reconfigure it.

Adapters will not be constructed until the first operation is done.

Usage

Assuming that the class' name is Cache the following scenarios are supported:

Reading config data back:

Cache::config('default');

Setting a cache engine up.

Cache::config('default', $settings);

Injecting a constructed adapter in:

Cache::config('default', $instance);

Configure multiple adapters at once:

Cache::config($arrayOfConfig);
Parameters
string|array $key

The name of the configuration, or an array of multiple configs.

array|null $config optional

An array of name => configuration data for adapter.

Returns
array|null
Throws
BadMethodCallException
When trying to modify an existing config.

configTransport() ¶ public static

configTransport(string|array $key, array|Cake\Mailer\AbstractTransport|null $config = null): array|null

Add or read transport configuration.

Use this method to define transports to use in delivery profiles. Once defined you cannot edit the configurations, and must use Email::dropTransport() to flush the configuration first.

When using an array of configuration data a new transport will be constructed for each message sent. When using a Closure, the closure will be evaluated for each message.

The className is used to define the class to use for a transport. It can either be a short name, or a fully qualified classname

Parameters
string|array $key

The configuration name to read/write. Or an array of multiple transports to set.

array|Cake\Mailer\AbstractTransport|null $config optional

Either an array of configuration data, or a transport instance.

Returns
array|null
Throws
BadMethodCallException
When modifying an existing configuration.

configured() ¶ public static

configured(): string[]

Returns an array containing the named configurations

Returns
string[]

configuredTransport() ¶ public static

configuredTransport(): array

Returns an array containing the named transport configurations

Returns
array

createFromArray() ¶ public

createFromArray(array $config): $this

Configures an email instance object from serialized config.

Parameters
array $config

Email configuration array.

Returns
$this

createView() ¶ public

createView(string|null $viewClass = null): Cake\View\View

Constructs the view class instance based on the current configuration.

Parameters
string|null $viewClass optional

Optional namespaced class name of the View class to instantiate.

Returns
Cake\View\View
Throws
Cake\View\Exception\MissingViewException
If view class was not found.

deliver() ¶ public static

deliver(string|array|null $to = null, string|null $subject = null, string|array|null $message = null, string|array $config = 'default', bool $send = true): static

Static method to fast create an instance of \Cake\Mailer\Email

Parameters
string|array|null $to optional

Address to send (see Cake\Mailer\Email::to()). If null, will try to use 'to' from transport config

string|null $subject optional

String of subject or null to use 'subject' from transport config

string|array|null $message optional

String with message or array with variables to be used in render

string|array $config optional

String to use Email delivery profile from app.php or array with configs

bool $send optional

Send the email or just return the instance pre-configured

Returns
static
Throws
InvalidArgumentException

domain() ¶ public

domain(string|null $domain = null): string|$this

Domain as top level (the part after @)

Parameters
string|null $domain optional

Manually set the domain for CLI mailing

Returns
string|$this

drop() ¶ public static

drop(string $config): bool

Drops a constructed adapter.

If you wish to modify an existing configuration, you should drop it, change configuration and then re-add it.

If the implementing objects supports a $_registry object the named configuration will also be unloaded from the registry.

Parameters
string $config

An existing configuration you wish to remove.

Returns
bool

dropTransport() ¶ public static

dropTransport(string $key): void

Delete transport configuration.

Parameters
string $key

The transport name to remove.

Returns
void

dsnClassMap() ¶ public static

dsnClassMap(string[]|null $map = null): string[]

Returns or updates the DSN class map for this class.

Parameters
string[]|null $map optional

Additions/edits to the class map to apply.

Returns
string[]

emailFormat() ¶ public

emailFormat(string|null $format = null): string|$this

Email format

Parameters
string|null $format optional

Formatting string.

Returns
string|$this
Throws
InvalidArgumentException

emailPattern() ¶ public

emailPattern(string|false|null $regex = false): string|$this

EmailPattern setter/getter

Parameters
string|false|null $regex optional

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

flatten() ¶ protected

flatten(string|array $value): string

Converts given value to string

Parameters
string|array $value

The value to convert

Returns
string

from() ¶ public

from(string|array|null $email = null, string|null $name = null): array|$this

From

Parameters
string|array|null $email optional

Null to get, String with email, Array with email as key, name as value or email as value (without name)

string|null $name optional

Name

Returns
array|$this
Throws
InvalidArgumentException

getAttachments() ¶ public

getAttachments(): array

Gets attachments to the email message.

Returns
array

getBcc() ¶ public

getBcc(): array

Gets "bcc" address.

Returns
array

getCc() ¶ public

getCc(): array

Gets "cc" address.

Returns
array

getCharset() ¶ public

getCharset(): string

Charset getter.

Returns
string

getConfig() ¶ public static

getConfig(string $key): mixed|null

Reads existing configuration.

Parameters
string $key

The name of the configuration.

Returns
mixed|null

getConfigOrFail() ¶ public static

getConfigOrFail(string|null $key): mixed

Reads existing configuration for a specific key.

The config value for this key must exist, it can never be null.

Parameters
string|null $key

The name of the configuration.

Returns
mixed
Throws
InvalidArgumentException
If value does not exist.

getConfigTransport() ¶ public static

getConfigTransport(string $key): array|null

Gets current transport configuration.

Parameters
string $key

The configuration name to read.

Returns
array|null

getDomain() ¶ public

getDomain(): string

Gets domain.

Returns
string

getDsnClassMap() ¶ public static

getDsnClassMap(): string[]

Returns the DSN class map for this class.

Returns
string[]

getEmailFormat() ¶ public

getEmailFormat(): string

Gets email format.

Returns
string

getEmailPattern() ¶ public

getEmailPattern(): string

EmailPattern setter/getter

Returns
string

getFrom() ¶ public

getFrom(): array

Gets "from" address.

Returns
array

getHeaderCharset() ¶ public

getHeaderCharset(): string

HeaderCharset getter.

Returns
string

getHeaders() ¶ public

getHeaders(array $include = []): array

Get list of headers

Includes:

  • from
  • replyTo
  • readReceipt
  • returnPath
  • to
  • cc
  • bcc
  • subject
Parameters
array $include optional

List of headers.

Returns
array

getHelpers() ¶ public

getHelpers(): array

Gets helpers to be used when rendering.

Returns
array

getLayout() ¶ public

getLayout(): string

Gets layout.

Returns
string

getMessageId() ¶ public

getMessageId(): bool|string

Gets message ID.

Returns
bool|string

getOriginalSubject() ¶ public

getOriginalSubject(): string

Get original subject without encoding

Returns
string

getPriority() ¶ public

getPriority(): int

Gets priority.

Returns
int

getProfile() ¶ public

getProfile(): string|array

Gets the configuration profile to use for this instance.

Returns
string|array

getReadReceipt() ¶ public

getReadReceipt(): array

Gets Read Receipt (Disposition-Notification-To header).

Returns
array

getReplyTo() ¶ public

getReplyTo(): array

Gets "Reply-To" address.

Returns
array

getReturnPath() ¶ public

getReturnPath(): array

Gets return path.

Returns
array

getSender() ¶ public

getSender(): array

Gets the "sender" address. See rfc link below for full explanation.

Returns
array
Links
https://tools.ietf.org/html/rfc2822.html#section-3.6.2

getSubject() ¶ public

getSubject(): string

Gets subject.

Returns
string

getTemplate() ¶ public

getTemplate(): string

Gets template.

Returns
string

getTheme() ¶ public

getTheme(): string

Gets theme to use when rendering.

Returns
string

getTo() ¶ public

getTo(): array

Gets "to" address

Returns
array

getTransferEncoding() ¶ public

getTransferEncoding(): string|null

TransferEncoding getter.

Returns
string|null

getTransport() ¶ public

getTransport(): Cake\Mailer\AbstractTransport

Gets the transport.

Returns
Cake\Mailer\AbstractTransport

getViewRenderer() ¶ public

getViewRenderer(): string

Gets view class for render.

Returns
string

getViewVars() ¶ public

getViewVars(): array

Gets variables to be set on render.

Returns
array

headerCharset() ¶ public

headerCharset(string|null $charset = null): string

HeaderCharset setter/getter

Parameters
string|null $charset optional

Character set.

Returns
string

helpers() ¶ public

helpers(array|null $helpers = null): array|$this

Helpers to be used in render

Parameters
array|null $helpers optional

Helpers list.

Returns
array|$this

jsonSerialize() ¶ public

jsonSerialize(): array

Serializes the email object to a value that can be natively serialized and re-used to clone this email instance.

It has certain limitations for viewVars that are good to know:

  • ORM\Query executed and stored as resultset
    • SimpleXMLElements stored as associative array
    • Exceptions stored as strings
    • Resources, \Closure and \PDO are not supported.
Returns
array
Throws
Exception
When a view var object can not be properly serialized.

message() ¶ public

message(string|null $type = null): string|array

Get generated message (used by transport classes)

Parameters
string|null $type optional

Use MESSAGE_* constants or null to return the full message as array

Returns
string|array

messageId() ¶ public

messageId(bool|string|null $message = null): bool|string|$this

Message-ID

Parameters
bool|string|null $message optional

True to generate a new Message-ID, False to ignore (not send in email), String to set as Message-ID

Returns
bool|string|$this
Throws
InvalidArgumentException

parseDsn() ¶ public static

parseDsn(string $dsn): array

Parses a DSN into a valid connection configuration

This method allows setting a DSN using formatting similar to that used by PEAR::DB. The following is an example of its usage:

$dsn = 'mysql://user:pass@localhost/database?';
$config = ConnectionManager::parseDsn($dsn);

$dsn = 'Cake\Log\Engine\FileLog://?types=notice,info,debug&file=debug&path=LOGS';
$config = Log::parseDsn($dsn);

$dsn = 'smtp://user:secret@localhost:25?timeout=30&client=null&tls=null';
$config = Email::parseDsn($dsn);

$dsn = 'file:///?className=\My\Cache\Engine\FileEngine';
$config = Cache::parseDsn($dsn);

$dsn = 'File://?prefix=myapp_cake_core_&serialize=true&duration=+2 minutes&path=/tmp/persistent/';
$config = Cache::parseDsn($dsn);

For all classes, the value of scheme is set as the value of both the className unless they have been otherwise specified.

Note that querystring arguments are also parsed and set as values in the returned configuration.

Parameters
string $dsn

The DSN string to convert to a configuration array

Returns
array
Throws
InvalidArgumentException
If not passed a string, or passed an invalid string

profile() ¶ public

profile(array|string|null $config = null): string|array|$this

Get/Set the configuration profile to use for this instance.

Parameters
array|string|null $config optional

String with configuration name, or an array with config or null to return current config.

Returns
string|array|$this

readReceipt() ¶ public

readReceipt(string|array|null $email = null, string|null $name = null): array|$this

Read Receipt (Disposition-Notification-To header)

Parameters
string|array|null $email optional

Null to get, String with email, Array with email as key, name as value or email as value (without name)

string|null $name optional

Name

Returns
array|$this
Throws
InvalidArgumentException

replyTo() ¶ public

replyTo(string|array|null $email = null, string|null $name = null): array|$this

Reply-To

Parameters
string|array|null $email optional

Null to get, String with email, Array with email as key, name as value or email as value (without name)

string|null $name optional

Name

Returns
array|$this
Throws
InvalidArgumentException

reset() ¶ public

reset(): $this

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

Returns
$this

returnPath() ¶ public

returnPath(string|array|null $email = null, string|null $name = null): array|$this

Return Path

Parameters
string|array|null $email optional

Null to get, String with email, Array with email as key, name as value or email as value (without name)

string|null $name optional

Name

Returns
array|$this
Throws
InvalidArgumentException

send() ¶ public

send(string|array|null $content = null): array

Send an email using the specified content, template and layout

Parameters
string|array|null $content optional

String with message or array with messages

Returns
array
Throws
BadMethodCallException

sender() ¶ public

sender(string|array|null $email = null, string|null $name = null): array|$this

Sender

Parameters
string|array|null $email optional

Null to get, String with email, Array with email as key, name as value or email as value (without name)

string|null $name optional

Name

Returns
array|$this
Throws
InvalidArgumentException

serialize() ¶ public

serialize(): string

Serializes the Email object.

Returns
string

set() ¶ public

set(string|array $name, mixed $value = null): $this

Saves a variable or an associative array of variables for use inside a template.

Parameters
string|array $name

A string or an array of data.

mixed $value optional

Value in case $name is a string (which then works as the key). Unused if $name is an associative array, otherwise serves as the values to $name's keys.

Returns
$this

setAttachments() ¶ public

setAttachments(string|array $attachments): $this

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->setAttachments('path/to/file');

Attach a file with a different filename:

$email->setAttachments(['custom_name.txt' => 'path/to/file.txt']);

Attach a file and specify additional properties:

$email->setAttachments(['custom_name.png' => [
     'file' => 'path/to/file',
     'mimetype' => 'image/png',
     'contentId' => 'abc123',
     'contentDisposition' => false
   ]
]);

Attach a file from string and specify additional properties:

$email->setAttachments(['custom_name.png' => [
     'data' => file_get_contents('path/to/file'),
     'mimetype' => 'image/png'
   ]
]);

The contentId key allows you to specify an inline attachment. In your email text, you can use <img src="cid:abc123" /> to display the image inline.

The contentDisposition key allows you to disable the Content-Disposition header, this can improve attachment compatibility with outlook email clients.

Parameters
string|array $attachments

String with the filename or array with filenames

Returns
$this
Throws
InvalidArgumentException

setBcc() ¶ public

setBcc(string|array $email, string|null $name = null): $this

Sets "bcc" address.

Parameters
string|array $email

String with email, Array with email as key, name as value or email as value (without name)

string|null $name optional

Name

Returns
$this

setCc() ¶ public

setCc(string|array $email, string|null $name = null): $this

Sets "cc" address.

Parameters
string|array $email

String with email, Array with email as key, name as value or email as value (without name)

string|null $name optional

Name

Returns
$this

setCharset() ¶ public

setCharset(string|null $charset): $this

Charset setter.

Parameters
string|null $charset

Character set.

Returns
$this

setConfig() ¶ public static

setConfig(string|array $key, array|object|null $config = null): void

This method can be used to define configuration adapters for an application.

To change an adapter's configuration at runtime, first drop the adapter and then reconfigure it.

Adapters will not be constructed until the first operation is done.

Usage

Assuming that the class' name is Cache the following scenarios are supported:

Setting a cache engine up.

Cache::setConfig('default', $settings);

Injecting a constructed adapter in:

Cache::setConfig('default', $instance);

Configure multiple adapters at once:

Cache::setConfig($arrayOfConfig);
Parameters
string|array $key

The name of the configuration, or an array of multiple configs.

array|object|null $config optional

An array of name => configuration data for adapter.

Returns
void
Throws
BadMethodCallException
When trying to modify an existing config.
LogicException
When trying to store an invalid structured config array.

setConfigTransport() ¶ public static

setConfigTransport(string|array $key, array|Cake\Mailer\AbstractTransport|null $config = null): void

Sets transport configuration.

Use this method to define transports to use in delivery profiles. Once defined you cannot edit the configurations, and must use Email::dropTransport() to flush the configuration first.

When using an array of configuration data a new transport will be constructed for each message sent. When using a Closure, the closure will be evaluated for each message.

The className is used to define the class to use for a transport. It can either be a short name, or a fully qualified class name

Parameters
string|array $key

The configuration name to write. Or an array of multiple transports to set.

array|Cake\Mailer\AbstractTransport|null $config optional

Either an array of configuration data, or a transport instance. Null when using key as array.

Returns
void

setDomain() ¶ public

setDomain(string $domain): $this

Sets domain.

Domain as top level (the part after @).

Parameters
string $domain

Manually set the domain for CLI mailing.

Returns
$this

setDsnClassMap() ¶ public static

setDsnClassMap(string[] $map): void

Updates the DSN class map for this class.

Parameters
string[] $map

Additions/edits to the class map to apply.

Returns
void

setEmailFormat() ¶ public

setEmailFormat(string $format): $this

Sets email format.

Parameters
string $format

Formatting string.

Returns
$this
Throws
InvalidArgumentException

setEmailPattern() ¶ public

setEmailPattern(string|null $regex): $this

EmailPattern setter/getter

Parameters
string|null $regex

The pattern to use for email address validation, null to unset the pattern and make use of filter_var() instead.

Returns
$this

setFrom() ¶ public

setFrom(string|array $email, string|null $name = null): $this

Sets "from" address.

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|null $name optional

Name

Returns
$this
Throws
InvalidArgumentException

setHeaderCharset() ¶ public

setHeaderCharset(string|null $charset): $this

HeaderCharset setter.

Parameters
string|null $charset

Character set.

Returns
$this

setHeaders() ¶ public

setHeaders(array $headers): $this

Sets headers for the message

Parameters
array $headers

Associative array containing headers to be set.

Returns
$this

setHelpers() ¶ public

setHelpers(array $helpers): $this

Sets helpers to be used when rendering.

Parameters
array $helpers

Helpers list.

Returns
$this

setLayout() ¶ public

setLayout(string|null $layout): $this

Sets layout.

Parameters
string|null $layout

Layout name or null to not use

Returns
$this

setMessageId() ¶ public

setMessageId(bool|string $message): $this

Sets message ID.

Parameters
bool|string $message

True to generate a new Message-ID, False to ignore (not send in email), String to set as Message-ID.

Returns
$this
Throws
InvalidArgumentException

setPriority() ¶ public

setPriority(int|null $priority): $this

Sets priority.

Parameters
int|null $priority

1 (highest) to 5 (lowest)

Returns
$this

setProfile() ¶ public

setProfile(string|array $config): $this

Sets the configuration profile to use for this instance.

Parameters
string|array $config

String with configuration name, or an array with config.

Returns
$this

setReadReceipt() ¶ public

setReadReceipt(string|array $email, string|null $name = null): $this

Sets Read Receipt (Disposition-Notification-To header).

Parameters
string|array $email

String with email, Array with email as key, name as value or email as value (without name)

string|null $name optional

Name

Returns
$this
Throws
InvalidArgumentException

setReplyTo() ¶ public

setReplyTo(string|array $email, string|null $name = null): $this

Sets "Reply-To" address.

Parameters
string|array $email

String with email, Array with email as key, name as value or email as value (without name)

string|null $name optional

Name

Returns
$this
Throws
InvalidArgumentException

setReturnPath() ¶ public

setReturnPath(string|array $email, string|null $name = null): $this

Return Path

Parameters
string|array $email

String with email, Array with email as key, name as value or email as value (without name)

string|null $name optional

Name

Returns
$this
Throws
InvalidArgumentException

setSender() ¶ public

setSender(string|array $email, string|null $name = null): $this

Sets the "sender" address. See rfc link below for full explanation.

Parameters
string|array $email

String with email, Array with email as key, name as value or email as value (without name)

string|null $name optional

Name

Returns
$this
Throws
InvalidArgumentException
Links
https://tools.ietf.org/html/rfc2822.html#section-3.6.2

setSubject() ¶ public

setSubject(string $subject): $this

Sets subject.

Parameters
string $subject

Subject string.

Returns
$this

setTemplate() ¶ public

setTemplate(string|null $template): $this

Sets template.

Parameters
string|null $template

Template name or null to not use.

Returns
$this

setTheme() ¶ public

setTheme(string $theme): $this

Sets theme to use when rendering.

Parameters
string $theme

Theme name.

Returns
$this

setTo() ¶ public

setTo(string|array $email, string|null $name = null): $this

Sets "to" address.

Parameters
string|array $email

String with email, Array with email as key, name as value or email as value (without name)

string|null $name optional

Name

Returns
$this

setTransferEncoding() ¶ public

setTransferEncoding(string|null $encoding): $this

TransferEncoding setter.

Parameters
string|null $encoding

Encoding set.

Returns
$this

setTransport() ¶ public

setTransport(string|Cake\Mailer\AbstractTransport $name): $this

Sets the transport.

When setting the transport you can either use the name of a configured transport or supply a constructed transport.

Parameters
string|Cake\Mailer\AbstractTransport $name

Either the name of a configured transport, or a transport instance.

Returns
$this
Throws
LogicException
When the chosen transport lacks a send method.
InvalidArgumentException
When $name is neither a string nor an object.

setViewRenderer() ¶ public

setViewRenderer(string $viewClass): $this

Sets view class for render.

Parameters
string $viewClass

View class name.

Returns
$this

setViewVars() ¶ public

setViewVars(array $viewVars): $this

Sets variables to be set on render.

Parameters
array $viewVars

Variables to set for view.

Returns
$this

subject() ¶ public

subject(string|null $subject = null): string|$this

Get/Set Subject.

Parameters
string|null $subject optional

Subject string.

Returns
string|$this

template() ¶ public

template(bool|string $template = false, bool|string $layout = false): array|$this

Template and layout

Parameters
bool|string $template optional

Template name or null to not use

bool|string $layout optional

Layout name or null to not use

Returns
array|$this

theme() ¶ public

theme(string|null $theme = null): string|$this

Theme to use when rendering

Parameters
string|null $theme optional

Theme name.

Returns
string|$this

to() ¶ public

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

To

Parameters
string|array|null $email optional

Null to get, String with email, Array with email as key, name as value or email as value (without name)

string|null $name optional

Name

Returns
array|$this

transport() ¶ public

transport(string|Cake\Mailer\AbstractTransport|null $name = null): Cake\Mailer\AbstractTransport|$this

Get/set the transport.

When setting the transport you can either use the name of a configured transport or supply a constructed transport.

Parameters
string|Cake\Mailer\AbstractTransport|null $name optional

Either the name of a configured transport, or a transport instance.

Returns
Cake\Mailer\AbstractTransport|$this
Throws
LogicException
When the chosen transport lacks a send method.
InvalidArgumentException
When $name is neither a string nor an object.

unserialize() ¶ public

unserialize(string $data): static

Unserializes the Email object.

Parameters
string $data

Serialized string.

Returns
static

viewBuilder() ¶ public

viewBuilder(): Cake\View\ViewBuilder

Get the view builder being used.

Returns
Cake\View\ViewBuilder

viewOptions() ¶ public

viewOptions(string|array|null $options = null, bool $merge = true): array

Get/Set valid view options in the object's _validViewOptions property. The property is created as an empty array if it is not set. If called without any parameters it will return the current list of valid view options. See createView().

Parameters
string|array|null $options optional

string or array of string to be appended to _validViewOptions.

bool $merge optional

Whether to merge with or override existing valid View options. Defaults to true.

Returns
array

viewRender() ¶ public

viewRender(string|null $viewClass = null): string|$this

View class for render

Parameters
string|null $viewClass optional

View class name.

Returns
string|$this

viewVars() ¶ public

viewVars(array|null $viewVars = null): array|$this

Variables to be set on render

Parameters
array|null $viewVars optional

Variables to set for view.

Returns
array|$this

Property Detail

$_appCharset ¶ protected

The application wide charset, used to encode headers and body

Type
string|null

$_attachments ¶ protected

List of files that should be attached to the email.

Only absolute paths

Type
array

$_bcc ¶ protected

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

Type
array

$_boundary ¶ protected

If set, boundary to use for multipart mime messages

Type
string|null

$_cc ¶ protected

Carbon Copy

List of email's that should receive a copy of the email. The Recipient WILL be able to see this list

Type
array

$_charset8bit ¶ protected

8Bit character sets

Type
array

$_config ¶ protected static

Configuration sets.

Type
array

$_contentTypeCharset ¶ protected

Define Content-Type charset name

Type
array

$_domain ¶ protected

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

Type
string

$_dsnClassMap ¶ protected static deprecated

An array mapping url schemes to fully qualified Transport class names. Unused.

Type
string[]

$_emailFormat ¶ protected

What format should the email be sent in

Type
string

$_emailFormatAvailable ¶ protected

Available formats to be sent.

Type
array

$_emailPattern ¶ protected

Regex for email validation

If null, filter_var() will be used. Use the emailPattern() method to set a custom pattern.'

Type
string

$_from ¶ protected

The mail which the email is sent from

Type
array

$_headers ¶ protected

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

Type
array

$_htmlMessage ¶ protected

Html message

Type
string

$_message ¶ protected

Final message to send

Type
array

$_messageId ¶ protected

Message ID

Type
bool|string

$_priority ¶ protected

Contains the optional priority of the email.

Type
int|null

$_profile ¶ protected

A copy of the configuration profile for this instance. This copy can be modified with Email::profile().

Type
array

$_readReceipt ¶ protected

The read receipt email

Type
array

$_registry ¶ public @property

Type
Cake\Core\ObjectRegistry

$_replyTo ¶ protected

List of email(s) that the recipient will reply to.

Type
array

$_returnPath ¶ protected

The mail that will be used in case of any errors like

  • Remote mailserver down
  • Remote user has exceeded his quota
  • Unknown user
Type
array

$_sender ¶ protected

The sender email

Type
array

$_subject ¶ protected

The subject of the email

Type
string

$_textMessage ¶ protected

Text message

Type
string

$_to ¶ protected

Recipient of the email

Type
array

$_transferEncodingAvailable ¶ protected

Available encoding to be set for transfer.

Type
array

$_transport ¶ protected

The transport instance to use for sending mail.

Type
Cake\Mailer\AbstractTransport|null

$_validViewOptions ¶ public @property

Type
array

$_viewBuilder ¶ protected

The view builder instance being used.

Type
Cake\View\ViewBuilder

$charset ¶ public

Charset the email body is sent in

Type
string

$headerCharset ¶ public

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

Type
string|null

$transferEncoding ¶ protected

The email transfer encoding used. If null, the $charset property is used for determined the transfer encoding.

Type
string|null

$viewClass ¶ public deprecated

The name of default View class.

Type
string|null

$viewVars ¶ public

Variables for the view.

Deprecated: This property will be removed in 4.x. Inside controller context use $this->set() instead, also see $this->viewBuilder()->getVar(). In view context it will be a protected property View::$viewVars.

Type
array
OpenHub
Pingping
Linode
  • 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
  • IRC
  • Slack
  • Paid Support

Generated using CakePHP API Docs