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.
Property Summary
-
$_clonedEmail protected
stringCloned Email instance for restoring instance after email is sent by mailer action.
-
$_email protected
Cake\Mailer\EmailEmail instance.
-
$_modelFactories protected
arrayA list of model factory functions.
-
$_modelType protected
stringThe model type to use.
-
$modelClass public
stringThis 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.
-
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): $thisMagic 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): 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
voidaddAttachments() ¶ public @method
addAttachments(mixed $attachments): Cake\Mailer\EmailParameters
-
$attachments
Returns
Cake\Mailer\EmailaddBcc() ¶ public @method
addBcc(mixed $email, mixed $name = null): Cake\Mailer\EmailParameters
-
$email -
$name optional
Returns
Cake\Mailer\EmailaddCc() ¶ public @method
addCc(mixed $email, mixed $name = null): Cake\Mailer\EmailParameters
-
$email -
$name optional
Returns
Cake\Mailer\EmailaddHeaders() ¶ public @method
addHeaders(array $headers): Cake\Mailer\EmailParameters
-
array$headers
Returns
Cake\Mailer\EmailaddTo() ¶ public @method
addTo(mixed $email, mixed $name = null): Cake\Mailer\EmailParameters
-
$email -
$name optional
Returns
Cake\Mailer\Emailattachments() ¶ public @method
attachments(mixed $attachments = null): Cake\Mailer\EmailParameters
-
$attachments optional
Returns
Cake\Mailer\Emailbcc() ¶ public @method
bcc(mixed $email = null, mixed $name = null): Cake\Mailer\EmailParameters
-
$email optional -
$name optional
Returns
Cake\Mailer\Emailcc() ¶ public @method
cc(mixed $email = null, mixed $name = null): Cake\Mailer\EmailParameters
-
$email optional -
$name optional
Returns
Cake\Mailer\Emailcharset() ¶ public @method
charset(mixed $charset = null): Cake\Mailer\EmailParameters
-
$charset optional
Returns
Cake\Mailer\Emaildomain() ¶ public @method
domain(mixed $domain = null): Cake\Mailer\EmailParameters
-
$domain optional
Returns
Cake\Mailer\EmailemailFormat() ¶ public @method
emailFormat(mixed $format = null): Cake\Mailer\EmailParameters
-
$format optional
Returns
Cake\Mailer\Emailfrom() ¶ public @method
from(mixed $email = null, mixed $name = null): Cake\Mailer\EmailParameters
-
$email optional -
$name optional
Returns
Cake\Mailer\EmailgetHeaders() ¶ public @method
getHeaders(array $include = []): Cake\Mailer\EmailParameters
-
array$include optional
Returns
Cake\Mailer\EmailheaderCharset() ¶ public @method
headerCharset(mixed $charset = null): Cake\Mailer\EmailParameters
-
$charset optional
Returns
Cake\Mailer\Emailhelpers() ¶ public @method
helpers(mixed $helpers = null): Cake\Mailer\EmailParameters
-
$helpers optional
Returns
Cake\Mailer\EmailimplementedEvents() ¶ 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
-
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
message() ¶ public @method
message(mixed $type = null): Cake\Mailer\EmailParameters
-
$type optional
Returns
Cake\Mailer\EmailmessageId() ¶ public @method
messageId(mixed $message = null): Cake\Mailer\EmailParameters
-
$message optional
Returns
Cake\Mailer\EmailmodelFactory() ¶ public
modelFactory(string $type, callable $factory): voidRegister a 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|$thisprofile() ¶ public @method
profile(mixed $config = null): Cake\Mailer\EmailParameters
-
$config optional
Returns
Cake\Mailer\EmailreadReceipt() ¶ public @method
readReceipt(mixed $email = null, mixed $name = null): Cake\Mailer\EmailParameters
-
$email optional -
$name optional
Returns
Cake\Mailer\EmailreplyTo() ¶ public @method
replyTo(mixed $email = null, mixed $name = null): Cake\Mailer\EmailParameters
-
$email optional -
$name optional
Returns
Cake\Mailer\EmailreturnPath() ¶ public @method
returnPath(mixed $email = null, mixed $name = null): Cake\Mailer\EmailParameters
-
$email optional -
$name optional
Returns
Cake\Mailer\Emailsend() ¶ 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\MissingActionExceptionBadMethodCallExceptionsender() ¶ public @method
sender(mixed $email = null, mixed $name = null): Cake\Mailer\EmailParameters
-
$email optional -
$name optional
Returns
Cake\Mailer\Emailset() ¶ 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
$thissetHeaders() ¶ public @method
setHeaders(array $headers): Cake\Mailer\EmailParameters
-
array$headers
Returns
Cake\Mailer\Emailsubject() ¶ public @method
subject(mixed $subject = null): Cake\Mailer\EmailParameters
-
$subject optional
Returns
Cake\Mailer\Emailtemplate() ¶ public @method
template(mixed $template = false, mixed $layout = false): Cake\Mailer\EmailParameters
-
$template optional -
$layout optional
Returns
Cake\Mailer\Emailtheme() ¶ public @method
theme(mixed $theme = null): Cake\Mailer\EmailParameters
-
$theme optional
Returns
Cake\Mailer\Emailto() ¶ public @method
to(mixed $email = null, mixed $name = null): Cake\Mailer\EmailParameters
-
$email optional -
$name optional
Returns
Cake\Mailer\Emailtransport() ¶ public @method
transport(mixed $name = null): Cake\Mailer\EmailParameters
-
$name optional
Returns
Cake\Mailer\EmailviewBuilder() ¶ public
viewBuilder(): Cake\View\ViewBuilderGet Email instance's view builder.
Returns
Cake\View\ViewBuilderviewRender() ¶ public @method
viewRender(mixed $viewClass = null): Cake\Mailer\EmailParameters
-
$viewClass optional
Returns
Cake\Mailer\EmailviewVars() ¶ public @method
viewVars(mixed $viewVars = null): Cake\Mailer\EmailParameters
-
$viewVars optional
Returns
Cake\Mailer\EmailProperty Detail
$_clonedEmail ¶ protected
Cloned Email instance for restoring instance after email is sent by mailer action.
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