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\EmailCloned Email instance for restoring instance after email is sent by mailer action.
-
$_email protected
Cake\Mailer\EmailEmail instance.
-
$_modelFactories protected
arrayA list of overridden model factory functions.
-
$_modelType protected
stringThe model type to use.
-
$modelClass public
string|false|nullThis object's primary model class name. Should be a plural form. CakePHP will not inflect the name.
-
$name public static
stringMailer'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|mixedMagic 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): voidSet 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
voidgetModelType() ¶ public
getModelType(): stringGet the model type to be used by this class
Returns
stringimplementedEvents() ¶ public
implementedEvents(): arrayImplemented events.
Example:
public function implementedEvents()
{
return [
'Order.complete' => 'sendEmail',
'Article.afterBuy' => 'decrementInventory',
'User.onRegister' => ['callable' => 'logRegistration', 'priority' => 20, 'passParams' => true]
];
}Returns
arraylayout() ¶ public
layout(string $layout): $thisSets layout to use.
Parameters
-
string$layout Name of the layout to use.
Returns
$thisloadModel() ¶ public
loadModel(string|null $modelClass = null, string|null $modelType = null): Cake\Datasource\RepositoryInterfaceLoads 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\RepositoryInterfaceThrows
Cake\Datasource\Exception\MissingModelExceptionIf the model class cannot be found.
InvalidArgumentExceptionWhen using a type that has not been registered.
UnexpectedValueExceptionIf no model type has been defined
modelFactory() ¶ public
modelFactory(string $type, callable $factory): voidOverride 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
voidmodelType() ¶ public
modelType(string|null $modelType = null): string|$thisSet 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|$thissend() ¶ public
send(string $action, array $args = [], array $headers = []): arraySends 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
arrayThrows
Cake\Mailer\Exception\MissingActionExceptionBadMethodCallExceptionset() ¶ public
set(string|array $key, mixed $value = null): $thisSets email view vars.
Parameters
-
string|array$key Variable name or hash of view variables.
-
mixed$value optional View variable value.
Returns
$thissetModelType() ¶ public
setModelType(string $modelType): $thisSet the model type to be used by this class
Parameters
-
string$modelType The model type
Returns
$thisviewBuilder() ¶ public
viewBuilder(): Cake\View\ViewBuilderGet Email instance's view builder.
Returns
Cake\View\ViewBuilderProperty 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