Class Mailer

Mailer base class.

Mailer classes let you encapsulate related Email logic into a reusable and testable class.

Defining Messages

Mailers make it easy for you to define methods that handle email formatting logic. For example:

class UserMailer extends Mailer
{
    public function resetPassword($user)
    {
        $this
            ->setSubject('Reset Password')
            ->setTo($user->email)
            ->set(['token' => $user->token]);
    }
}

Is a trivial example but shows how a mailer could be declared.

Sending Messages

After you have defined some messages you will want to send them:

$mailer = new UserMailer();
$mailer->send('resetPassword', $user);

Event Listener

Mailers can also subscribe to application event allowing you to decouple email delivery from your application code. By re-declaring the implementedEvents() method you can define event handlers that can convert events into email. For example, if your application had a user registration event:

public function implementedEvents()
{
    return [
        'Model.afterSave' => 'onRegistration',
    ];
}

public function onRegistration(Event $event, Entity $entity, ArrayObject $options)
{
    if ($entity->isNew()) {
         $this->send('welcome', [$entity]);
    }
}

The onRegistration method converts the application event into a mailer method. Our mailer could either be registered in the application bootstrap, or in the Table class' initialize() hook.

Abstract
Namespace: Cake\Mailer

Property Summary

$_clonedEmail protected

Cake\Mailer\Email

Cloned Email instance for restoring instance after email is sent by mailer action.
$_email protected

Cake\Mailer\Email

Email instance.
$_modelFactories protected

array

A list of overridden model factory functions.
$_modelType protected

string

The model type to use.
$modelClass public

string|false|null

This object's primary model class name. Should be a plural form. CakePHP will not inflect the name.
$name public static

string

Mailer's name.

Method Summary

__call() public

Magic method to forward method class to Email instance.
__construct() public

Constructor.
_setModelClass() protected

Set the modelClass and modelKey properties based on conventions.
addAttachments() public @method
addBcc() public @method
addCc() public @method
addHeaders() public @method
addTo() public @method
attachments() public @method
bcc() public @method
cc() public @method
charset() public @method
domain() public @method
emailFormat() public @method
emailPattern() public @method
from() public @method
getAttachments() public @method
getBcc() public @method
getCc() public @method
getCharset() public @method
getDomain() public @method
getEmailFormat() public @method
getEmailPattern() public @method
getFrom() public @method
getHeaderCharset() public @method
getHeaders() public @method
getHelpers() public @method
getLayout() public @method
getMessageId() public @method
getModelType() public

Get the model type to be used by this class
getName() public

Returns the mailer's name.
getProfile() public @method
getReadReceipt() public @method
getReplyTo() public @method
getReturnPath() public @method
getSender() public @method
getSubject() public @method
getTemplate() public @method
getTheme() public @method
getTo() public @method
getTransport() public @method
getViewRenderer() public @method
getViewVars() public @method
headerCharset() public @method
helpers() public @method
implementedEvents() public

Implemented events.
layout() public deprecated

Sets layout to use.
loadModel() public

Loads and constructs repository objects required by this object
message() public @method
messageId() public @method
modelFactory() public

Override a existing callable to generate repositories of a given type.
modelType() public deprecated

Set or get the model type to be used by this class
profile() public @method
readReceipt() public @method
replyTo() public @method
reset() protected

Reset email instance.
returnPath() public @method
send() public

Sends email.
sender() public @method
set() public

Sets email view vars.
setAttachments() public @method
setBcc() public @method
setCc() public @method
setCharset() public @method
setDomain() public @method
setEmailFormat() public @method
setEmailPattern() public @method
setFrom() public @method
setHeaderCharset() public @method
setHeaders() public @method
setHelpers() public @method
setLayout() public @method
setMessageId() public @method
setModelType() public

Set the model type to be used by this class
setProfile() public @method
setReadReceipt() public @method
setReplyTo() public @method
setReturnPath() public @method
setSender() public @method
setSubject() public @method
setTemplate() public @method
setTheme() public @method
setTo() public @method
setTransport() public @method
setViewRenderer() public @method
setViewVars() public @method
subject() public @method
template() public @method
theme() public @method
to() public @method
transport() public @method
viewBuilder() public

Get Email instance's view builder.
viewRender() public @method
viewVars() public @method

Method Detail

__call() ¶ public

__call(string $method, array $args): $this|mixed

Magic method to forward method class to Email instance.

Parameters

string $method: Method name.
array $args: Method arguments

Returns

$this|mixed

__construct() ¶ public

__construct(Cake\Mailer\Email|null $email = null)

Constructor.

Parameters

Cake\Mailer\Email|null $email optional: Email instance.

_setModelClass() ¶ protected

_setModelClass(string $name): void

Set the modelClass and modelKey properties based on conventions.

If the properties are already set they will not be overwritten

Parameters

string $name: Class name.

Returns

void

addAttachments() ¶ public @method

addAttachments(mixed $attachments): Cake\Mailer\Mailer

Parameters

$attachments

Returns

Cake\Mailer\Mailer

addBcc() ¶ public @method

addBcc(mixed $email, mixed $name = null): Cake\Mailer\Mailer

Parameters

$email
$name optional

Returns

Cake\Mailer\Mailer

addCc() ¶ public @method

addCc(mixed $email, mixed $name = null): Cake\Mailer\Mailer

Parameters

$email
$name optional

Returns

Cake\Mailer\Mailer

addHeaders() ¶ public @method

addHeaders(array $headers): Cake\Mailer\Mailer

Parameters

array $headers

Returns

Cake\Mailer\Mailer

addTo() ¶ public @method

addTo(mixed $email, mixed $name = null): Cake\Mailer\Mailer

Parameters

$email
$name optional

Returns

Cake\Mailer\Mailer

attachments() ¶ public @method

attachments(mixed $attachments = null): Cake\Mailer\Mailer

Parameters

$attachments optional

Returns

Cake\Mailer\Mailer

bcc() ¶ public @method

bcc(mixed $email = null, mixed $name = null): Cake\Mailer\Mailer

Parameters

$email optional
$name optional

Returns

Cake\Mailer\Mailer

cc() ¶ public @method

cc(mixed $email = null, mixed $name = null): Cake\Mailer\Mailer

Parameters

$email optional
$name optional

Returns

Cake\Mailer\Mailer

charset() ¶ public @method

charset(mixed $charset = null): Cake\Mailer\Mailer

Parameters

$charset optional

Returns

Cake\Mailer\Mailer

domain() ¶ public @method

domain(mixed $domain = null): Cake\Mailer\Mailer

Parameters

$domain optional

Returns

Cake\Mailer\Mailer

emailFormat() ¶ public @method

emailFormat(mixed $format = null): Cake\Mailer\Mailer

Parameters

$format optional

Returns

Cake\Mailer\Mailer

emailPattern() ¶ public @method

emailPattern(mixed $regex = null): Cake\Mailer\Mailer

Parameters

$regex optional

Returns

Cake\Mailer\Mailer

from() ¶ public @method

from(mixed $email = null, mixed $name = null): Cake\Mailer\Mailer

Parameters

$email optional
$name optional

Returns

Cake\Mailer\Mailer

getAttachments() ¶ public @method

getAttachments(): array

Returns

array

getBcc() ¶ public @method

getBcc(): array

Returns

array

getCc() ¶ public @method

getCc(): array

Returns

array

getCharset() ¶ public @method

getCharset(): string

Returns

string

getDomain() ¶ public @method

getDomain(): string

Returns

string

getEmailFormat() ¶ public @method

getEmailFormat(): string

Returns

string

getEmailPattern() ¶ public @method

getEmailPattern(): string

Returns

string

getFrom() ¶ public @method

getFrom(): array

Returns

array

getHeaderCharset() ¶ public @method

getHeaderCharset(): string

Returns

string

getHeaders() ¶ public @method

getHeaders(array $include = []): Cake\Mailer\Mailer

Parameters

array $include optional

Returns

Cake\Mailer\Mailer

getHelpers() ¶ public @method

getHelpers(): array

Returns

array

getLayout() ¶ public @method

getLayout(): string

Returns

string

getMessageId() ¶ public @method

getMessageId(): bool|string

Returns

bool|string

getModelType() ¶ public

getModelType(): string

Get the model type to be used by this class

Returns

string

getName() ¶ public

getName(): string

Returns the mailer's name.

Returns

string

getProfile() ¶ public @method

getProfile(): string|array

Returns

string|array

getReadReceipt() ¶ public @method

getReadReceipt(): array

Returns

array

getReplyTo() ¶ public @method

getReplyTo(): array

Returns

array

getReturnPath() ¶ public @method

getReturnPath(): array

Returns

array

getSender() ¶ public @method

getSender(): array

Returns

array

getSubject() ¶ public @method

getSubject(): string

Returns

string

getTemplate() ¶ public @method

getTemplate(): string

Returns

string

getTheme() ¶ public @method

getTheme(): string

Returns

string

getTo() ¶ public @method

getTo(): array

Returns

array

getTransport() ¶ public @method

getTransport(): Cake\Mailer\AbstractTransport

Returns

Cake\Mailer\AbstractTransport

getViewRenderer() ¶ public @method

getViewRenderer(): string

Returns

string

getViewVars() ¶ public @method

getViewVars(): array

Returns

array

headerCharset() ¶ public @method

headerCharset(mixed $charset = null): Cake\Mailer\Mailer

Parameters

$charset optional

Returns

Cake\Mailer\Mailer

helpers() ¶ public @method

helpers(mixed $helpers = null): Cake\Mailer\Mailer

Parameters

$helpers optional

Returns

Cake\Mailer\Mailer

implementedEvents() ¶ public

implementedEvents(): array

Implemented events.

Example:

 public function implementedEvents()
 {
     return [
         'Order.complete' => 'sendEmail',
         'Article.afterBuy' => 'decrementInventory',
         'User.onRegister' => ['callable' => 'logRegistration', 'priority' => 20, 'passParams' => true]
     ];
 }

Returns

array

layout() ¶ public

layout(string $layout): $this

Sets layout to use.

Parameters

string $layout: Name of the layout to use.

Returns

$this

loadModel() ¶ public

loadModel(string|null $modelClass = null, string|null $modelType = null): Cake\Datasource\RepositoryInterface

Loads and constructs repository objects required by this object

Typically used to load ORM Table objects as required. Can also be used to load other types of repository objects your application uses.

If a repository provider does not return an object a MissingModelException will be thrown.

Parameters

string|null $modelClass optional: Name of model class to load. Defaults to $this->modelClass. The name can be an alias like 'Post' or FQCN like App\Model\Table\PostsTable::class.
string|null $modelType optional: The type of repository to load. Defaults to the modelType() value.

Returns

Cake\Datasource\RepositoryInterface

Throws

Cake\Datasource\Exception\MissingModelException
If the model class cannot be found.
InvalidArgumentException
When using a type that has not been registered.
UnexpectedValueException
If no model type has been defined

message() ¶ public @method

message(mixed $type = null): Cake\Mailer\Mailer

Parameters

$type optional

Returns

Cake\Mailer\Mailer

messageId() ¶ public @method

messageId(mixed $message = null): Cake\Mailer\Mailer

Parameters

$message optional

Returns

Cake\Mailer\Mailer

modelFactory() ¶ public

modelFactory(string $type, callable $factory): void

Override a existing callable to generate repositories of a given type.

Parameters

string $type: The name of the repository type the factory function is for.
callable $factory: The factory function used to create instances.

Returns

void

modelType() ¶ public

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

Set or get the model type to be used by this class

Parameters

string|null $modelType optional: The model type or null to retrieve the current

Returns

string|$this

profile() ¶ public @method

profile(mixed $config = null): Cake\Mailer\Mailer

Parameters

$config optional

Returns

Cake\Mailer\Mailer

readReceipt() ¶ public @method

readReceipt(mixed $email = null, mixed $name = null): Cake\Mailer\Mailer

Parameters

$email optional
$name optional

Returns

Cake\Mailer\Mailer

replyTo() ¶ public @method

replyTo(mixed $email = null, mixed $name = null): Cake\Mailer\Mailer

Parameters

$email optional
$name optional

Returns

Cake\Mailer\Mailer

reset() ¶ protected

reset(): $this

Reset email instance.

Returns

$this

returnPath() ¶ public @method

returnPath(mixed $email = null, mixed $name = null): Cake\Mailer\Mailer

Parameters

$email optional
$name optional

Returns

Cake\Mailer\Mailer

send() ¶ public

send(string $action, array $args = [], array $headers = []): array

Sends email.

Parameters

string $action: The name of the mailer action to trigger.
array $args optional: Arguments to pass to the triggered mailer action.
array $headers optional: Headers to set.

Returns

array

Throws

Cake\Mailer\Exception\MissingActionException

BadMethodCallException

sender() ¶ public @method

sender(mixed $email = null, mixed $name = null): Cake\Mailer\Mailer

Parameters

$email optional
$name optional

Returns

Cake\Mailer\Mailer

set() ¶ public

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

Sets email view vars.

Parameters

string|array $key: Variable name or hash of view variables.
mixed $value optional: View variable value.

Returns

$this

setAttachments() ¶ public @method

setAttachments(mixed $attachments): Cake\Mailer\Mailer

Parameters

$attachments

Returns

Cake\Mailer\Mailer

setBcc() ¶ public @method

setBcc(mixed $email, mixed $name = null): Cake\Mailer\Mailer

Parameters

$email
$name optional

Returns

Cake\Mailer\Mailer

setCc() ¶ public @method

setCc(mixed $email, mixed $name = null): Cake\Mailer\Mailer

Parameters

$email
$name optional

Returns

Cake\Mailer\Mailer

setCharset() ¶ public @method

setCharset(mixed $charset): Cake\Mailer\Mailer

Parameters

$charset

Returns

Cake\Mailer\Mailer

setDomain() ¶ public @method

setDomain(mixed $domain): Cake\Mailer\Mailer

Parameters

$domain

Returns

Cake\Mailer\Mailer

setEmailFormat() ¶ public @method

setEmailFormat(mixed $format): Cake\Mailer\Mailer

Parameters

$format

Returns

Cake\Mailer\Mailer

setEmailPattern() ¶ public @method

setEmailPattern(mixed $regex): Cake\Mailer\Mailer

Parameters

$regex

Returns

Cake\Mailer\Mailer

setFrom() ¶ public @method

setFrom(mixed $email, mixed $name = null): Cake\Mailer\Mailer

Parameters

$email
$name optional

Returns

Cake\Mailer\Mailer

setHeaderCharset() ¶ public @method

setHeaderCharset(mixed $charset): Cake\Mailer\Mailer

Parameters

$charset

Returns

Cake\Mailer\Mailer

setHeaders() ¶ public @method

setHeaders(array $headers): Cake\Mailer\Mailer

Parameters

array $headers

Returns

Cake\Mailer\Mailer

setHelpers() ¶ public @method

setHelpers(array $helpers): Cake\Mailer\Mailer

Parameters

array $helpers

Returns

Cake\Mailer\Mailer

setLayout() ¶ public @method

setLayout(mixed $layout): Cake\Mailer\Mailer

Parameters

$layout

Returns

Cake\Mailer\Mailer

setMessageId() ¶ public @method

setMessageId(mixed $message): Cake\Mailer\Mailer

Parameters

$message

Returns

Cake\Mailer\Mailer

setModelType() ¶ public

setModelType(string $modelType): $this

Set the model type to be used by this class

Parameters

string $modelType: The model type

Returns

$this

setProfile() ¶ public @method

setProfile(mixed $config): Cake\Mailer\Mailer

Parameters

$config

Returns

Cake\Mailer\Mailer

setReadReceipt() ¶ public @method

setReadReceipt(mixed $email, mixed $name = null): Cake\Mailer\Mailer

Parameters

$email
$name optional

Returns

Cake\Mailer\Mailer

setReplyTo() ¶ public @method

setReplyTo(mixed $email, mixed $name = null): Cake\Mailer\Mailer

Parameters

$email
$name optional

Returns

Cake\Mailer\Mailer

setReturnPath() ¶ public @method

setReturnPath(mixed $email, mixed $name = null): Cake\Mailer\Mailer

Parameters

$email
$name optional

Returns

Cake\Mailer\Mailer

setSender() ¶ public @method

setSender(mixed $email, mixed $name = null): Cake\Mailer\Mailer

Parameters

$email
$name optional

Returns

Cake\Mailer\Mailer

setSubject() ¶ public @method

setSubject(mixed $subject): Cake\Mailer\Mailer

Parameters

$subject

Returns

Cake\Mailer\Mailer

setTemplate() ¶ public @method

setTemplate(mixed $template): Cake\Mailer\Mailer

Parameters

$template

Returns

Cake\Mailer\Mailer

setTheme() ¶ public @method

setTheme(mixed $theme): Cake\Mailer\Mailer

Parameters

$theme

Returns

Cake\Mailer\Mailer

setTo() ¶ public @method

setTo(mixed $email, mixed $name = null): Cake\Mailer\Mailer

Parameters

$email
$name optional

Returns

Cake\Mailer\Mailer

setTransport() ¶ public @method

setTransport(mixed $name): Cake\Mailer\Mailer

Parameters

$name

Returns

Cake\Mailer\Mailer

setViewRenderer() ¶ public @method

setViewRenderer(mixed $viewClass): Cake\Mailer\Mailer

Parameters

$viewClass

Returns

Cake\Mailer\Mailer

setViewVars() ¶ public @method

setViewVars(mixed $viewVars): Cake\Mailer\Mailer

Parameters

$viewVars

Returns

Cake\Mailer\Mailer

subject() ¶ public @method

subject(mixed $subject = null): Cake\Mailer\Mailer

Parameters

$subject optional

Returns

Cake\Mailer\Mailer

template() ¶ public @method

template(mixed $template = false, mixed $layout = false): Cake\Mailer\Mailer

Parameters

$template optional
$layout optional

Returns

Cake\Mailer\Mailer

theme() ¶ public @method

theme(mixed $theme = null): Cake\Mailer\Mailer

Parameters

$theme optional

Returns

Cake\Mailer\Mailer

to() ¶ public @method

to(mixed $email = null, mixed $name = null): Cake\Mailer\Mailer

Parameters

$email optional
$name optional

Returns

Cake\Mailer\Mailer

transport() ¶ public @method

transport(mixed $name = null): Cake\Mailer\Mailer

Parameters

$name optional

Returns

Cake\Mailer\Mailer

viewBuilder() ¶ public

viewBuilder(): Cake\View\ViewBuilder

Get Email instance's view builder.

Returns

Cake\View\ViewBuilder

viewRender() ¶ public @method

viewRender(mixed $viewClass = null): Cake\Mailer\Mailer

Parameters

$viewClass optional

Returns

Cake\Mailer\Mailer

viewVars() ¶ public @method

viewVars(mixed $viewVars = null): Cake\Mailer\Mailer

Parameters

$viewVars optional

Returns

Cake\Mailer\Mailer

Property Detail

`$_clonedEmail` ¶ protected

Cloned Email instance for restoring instance after email is sent by mailer action.

Type

Cake\Mailer\Email

`$_email` ¶ protected

Email instance.

Type

Cake\Mailer\Email

`$_modelFactories` ¶ protected

A list of overridden model factory functions.

Type

array

`$_modelType` ¶ protected

The model type to use.

Type

string

`$modelClass` ¶ public

This object's primary model class name. Should be a plural form. CakePHP will not inflect the name.

Example: For an object named 'Comments', the modelClass would be 'Comments'. Plugin classes should use Plugin.Comments style names to correctly load models from the correct plugin.

Use false to not use auto-loading on this object. Null auto-detects based on controller name.

Type

string|false|null

`$name` ¶ public static

Mailer's name.

Type

string

Namespaces

Class Mailer

Defining Messages

Sending Messages

Event Listener

Property Summary

Method Summary

__call() public

__construct() public

_setModelClass() protected

addAttachments() public @method

addBcc() public @method

addCc() public @method

addHeaders() public @method

addTo() public @method

attachments() public @method

bcc() public @method

cc() public @method

charset() public @method

domain() public @method

emailFormat() public @method

emailPattern() public @method

from() public @method

getAttachments() public @method

getBcc() public @method

getCc() public @method

getCharset() public @method

getDomain() public @method

getEmailFormat() public @method

getEmailPattern() public @method

getFrom() public @method

getHeaderCharset() public @method

getHeaders() public @method

getHelpers() public @method

getLayout() public @method

getMessageId() public @method

getModelType() public

getName() public

getProfile() public @method

getReadReceipt() public @method

getReplyTo() public @method

getReturnPath() public @method

getSender() public @method

getSubject() public @method

getTemplate() public @method

getTheme() public @method

getTo() public @method

getTransport() public @method

getViewRenderer() public @method

getViewVars() public @method

headerCharset() public @method

helpers() public @method

implementedEvents() public

layout() public deprecated

loadModel() public

message() public @method

messageId() public @method

modelFactory() public

modelType() public deprecated

profile() public @method

readReceipt() public @method

replyTo() public @method

reset() protected

returnPath() public @method

send() public

sender() public @method

set() public

setAttachments() public @method

setBcc() public @method

setCc() public @method

setCharset() public @method

setDomain() public @method

setEmailFormat() public @method

setEmailPattern() public @method

setFrom() public @method

setHeaderCharset() public @method

setHeaders() public @method

setHelpers() public @method

setLayout() public @method

setMessageId() public @method