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
            ->subject('Reset Password')
            ->to($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

string

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 model factory functions.
$_modelType protected

string

The model type to use.
$modelClass public

string

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
from() public @method
getHeaders() public @method
getName() public

Returns the mailer's name.
headerCharset() public @method
helpers() public @method
implementedEvents() public

Implemented events.
layout() public

Sets layout to use.
loadModel() public

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

Register a callable to generate repositories of a given type.
modelType() public

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

Magic method to forward method class to Email instance.

Parameters

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

Returns

$this

__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\Email

Parameters

$attachments

Returns

Cake\Mailer\Email

addBcc() ¶ public @method

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

Parameters

$email
$name optional

Returns

Cake\Mailer\Email

addCc() ¶ public @method

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

Parameters

$email
$name optional

Returns

Cake\Mailer\Email

addHeaders() ¶ public @method

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

Parameters

array $headers

Returns

Cake\Mailer\Email

addTo() ¶ public @method

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

Parameters

$email
$name optional

Returns

Cake\Mailer\Email

attachments() ¶ public @method

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

Parameters

$attachments optional

Returns

Cake\Mailer\Email

bcc() ¶ public @method

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

Parameters

$email optional
$name optional

Returns

Cake\Mailer\Email

cc() ¶ public @method

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

Parameters

$email optional
$name optional

Returns

Cake\Mailer\Email

charset() ¶ public @method

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

Parameters

$charset optional

Returns

Cake\Mailer\Email

domain() ¶ public @method

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

Parameters

$domain optional

Returns

Cake\Mailer\Email

emailFormat() ¶ public @method

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

Parameters

$format optional

Returns

Cake\Mailer\Email

from() ¶ public @method

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

Parameters

$email optional
$name optional

Returns

Cake\Mailer\Email

getHeaders() ¶ public @method

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

Parameters

array $include optional

Returns

Cake\Mailer\Email

getName() ¶ public

getName(): string

Returns the mailer's name.

Returns

string

headerCharset() ¶ public @method

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

Parameters

$charset optional

Returns

Cake\Mailer\Email

helpers() ¶ public @method

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

Parameters

$helpers optional

Returns

Cake\Mailer\Email

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
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\Email

Parameters

$type optional

Returns

Cake\Mailer\Email

messageId() ¶ public @method

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

Parameters

$message optional

Returns

Cake\Mailer\Email

modelFactory() ¶ public

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

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\Email

Parameters

$config optional

Returns

Cake\Mailer\Email

readReceipt() ¶ public @method

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

Parameters

$email optional
$name optional

Returns

Cake\Mailer\Email

replyTo() ¶ public @method

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

Parameters

$email optional
$name optional

Returns

Cake\Mailer\Email

reset() ¶ protected

reset(): $this

Reset email instance.

Returns

$this

returnPath() ¶ public @method

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

Parameters

$email optional
$name optional

Returns

Cake\Mailer\Email

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\Email

Parameters

$email optional
$name optional

Returns

Cake\Mailer\Email

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

setHeaders() ¶ public @method

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

Parameters

array $headers

Returns

Cake\Mailer\Email

subject() ¶ public @method

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

Parameters

$subject optional

Returns

Cake\Mailer\Email

template() ¶ public @method

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

Parameters

$template optional
$layout optional

Returns

Cake\Mailer\Email

theme() ¶ public @method

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

Parameters

$theme optional

Returns

Cake\Mailer\Email

to() ¶ public @method

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

Parameters

$email optional
$name optional

Returns

Cake\Mailer\Email

transport() ¶ public @method

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

Parameters

$name optional

Returns

Cake\Mailer\Email

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\Email

Parameters

$viewClass optional

Returns

Cake\Mailer\Email

viewVars() ¶ public @method

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

Parameters

$viewVars optional

Returns

Cake\Mailer\Email

Property Detail

`$_clonedEmail` ¶ protected

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

Type

string

`$_email` ¶ protected

Email instance.

Type

Cake\Mailer\Email

`$_modelFactories` ¶ protected

A list of 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.

Type

string

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

from() public @method

getHeaders() public @method

getName() public

headerCharset() public @method

helpers() public @method

implementedEvents() public

layout() public

loadModel() public

message() public @method

messageId() public @method

modelFactory() public

modelType() public

profile() public @method

readReceipt() public @method

replyTo() public @method

reset() protected

returnPath() public @method

send() public

sender() public @method

set() public

setHeaders() public @method

subject() public @method

template() public @method

theme() public @method

to() public @method

transport() public @method

viewBuilder() public

viewRender() public @method

viewVars() public @method

Method Detail

__call() ¶ public

Parameters

Returns

__construct() ¶ public

Parameters

_setModelClass() ¶ protected

Parameters

Returns

addAttachments() ¶ public @method

Parameters

Returns

addBcc() ¶ public @method

Parameters

Returns

addCc() ¶ public @method

Parameters

Returns

addHeaders() ¶ public @method

Parameters

Returns

addTo() ¶ public @method

Parameters

Returns

attachments() ¶ public @method

Parameters

Returns

bcc() ¶ public @method

Parameters

Returns