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.
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.
-
getModelType() public
Get the model type to be used by this class
-
getName() public
Returns the mailer's name.
-
implementedEvents() public
Implemented events.
-
layout() public deprecated
Sets layout to use.
-
loadModel() public
Loads and constructs repository objects required by this object
-
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
-
reset() protected
Reset email instance.
-
send() public
Sends email.
-
set() public
Sets email view vars.
-
setModelType() public
Set the model type to be used by this class
-
viewBuilder() public
Get Email instance's view builder.
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
getModelType() ¶ public
getModelType(): string
Get the model type to be used by this class
Returns
string
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 likeApp\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
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
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
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
setModelType() ¶ public
setModelType(string $modelType): $this
Set the model type to be used by this class
Parameters
-
string
$modelType The model type
Returns
$this
viewBuilder() ¶ public
viewBuilder(): Cake\View\ViewBuilder
Get Email instance's view builder.
Returns
Cake\View\ViewBuilder
Property Detail
$_clonedEmail ¶ protected
Cloned Email instance for restoring instance after email is sent by mailer action.
Type
Cake\Mailer\Email
$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