Mailer base class.
Mailer classes let you encapsulate related Email logic into a reusable and testable class.
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.
After you have defined some messages you will want to send them:
$mailer = new UserMailer(); $mailer->send('resetPassword', $user);
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(): array { return [ 'Model.afterSave' => 'onRegistration', ]; } public function onRegistration(EventInterface $event, EntityInterface $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.
array<string, mixed>
Configuration sets.
array<string, string>
Mailer driver class map.
array<callableCake\Datasource\Locator\LocatorInterface>
A list of overridden model factory functions.
string
The model type to use.
Cake\ORM\Locator\LocatorInterface|null
Table locator instance
array<string, mixed>
Hold message, renderer and transport instance for restoring after running a mailer action.
string|null
This object's default table alias.
array|null
Cake\Mailer\Message
Message instance.
string
Message class name.
string|null
This object's primary model class name. Should be a plural form. CakePHP will not inflect the name.
string
Mailer's name.
Cake\Mailer\Renderer|null
Email Renderer
Cake\Mailer\AbstractTransport|null
The transport instance to use for sending mail.
Magic method to forward method class to Message instance.
Constructor
Set the modelClass property based on conventions.
Add attachments. {@see \Cake\Mailer\Message::addAttachments()}
Add "bcc" address. {@see \Cake\Mailer\Message::addBcc()}
Add "cc" address. {@see \Cake\Mailer\Message::addCc()}
Add header for the message. {@see \Cake\Mailer\Message::addHeaders()}
Add "Reply-To" address. {@see \Cake\Mailer\Message::addReplyTo()}
Add "To" address. {@see \Cake\Mailer\Message::addTo()}
Returns an array containing the named configurations
Render content and send email using configured transport.
Drops a constructed adapter.
Convenience method to get a table instance.
Converts given value to string
Gets attachments to the email message. {@see \Cake\Mailer\Message::getAttachments()}
Gets "bcc" address. {@see \Cake\Mailer\Message::getBcc()}
Get generated message body as array. {@see \Cake\Mailer\Message::getBody()}
Gets "cc" address. {@see \Cake\Mailer\Message::getCc()}
Charset getter. {@see \Cake\Mailer\Message::getCharset()}
Reads existing configuration.
Reads existing configuration for a specific key.
Gets domain. {@see \Cake\Mailer\Message::getDomain()}
Returns the DSN class map for this class.
Gets email format. {@see \Cake\Mailer\Message::getEmailFormat()}
Gets "from" address. {@see \Cake\Mailer\Message::getFrom()}
HeaderCharset getter. {@see \Cake\Mailer\Message::getHeaderCharset()}
Get list of headers. {@see \Cake\Mailer\Message::getHeaders()}
Get message instance.
Gets message ID. {@see \Cake\Mailer\Message::getMessageId()}
Get the model type to be used by this class
Gets Read Receipt (Disposition-Notification-To header). {@see \Cake\Mailer\Message::getReadReceipt()}
Get email renderer.
Gets "Reply-To" address. {@see \Cake\Mailer\Message::getReplyTo()}
Gets return path. {@see \Cake\Mailer\Message::getReturnPath()}
Gets "sender" address. {@see \Cake\Mailer\Message::getSender()}
Gets subject. {@see \Cake\Mailer\Message::getSubject()}
Gets the table locator.
Gets "to" address. {@see \Cake\Mailer\Message::getTo()}
Gets the transport.
Implemented events.
Loads and constructs repository objects required by this object
Log the email message delivery.
Override a existing callable to generate repositories of a given type.
Parses a DSN into a valid connection configuration
Render content and set message body.
Reset all the internal variables to be able to send out a new email.
Restore message, renderer, transport instances to state before an action was run.
Sends email.
Sets email view vars.
Add attachments to the email message. {@see \Cake\Mailer\Message::setAttachments()}
Sets "bcc" address. {@see \Cake\Mailer\Message::setBcc()}
Sets "cc" address. {@see \Cake\Mailer\Message::setCc()}
Charset setter. {@see \Cake\Mailer\Message::setCharset()}
This method can be used to define configuration adapters for an application.
Sets domain. {@see \Cake\Mailer\Message::setDomain()}
Updates the DSN class map for this class.
Sets email format. {@see \Cake\Mailer\Message::getHeaders()}
Sets "from" address. {@see \Cake\Mailer\Message::setFrom()}
HeaderCharset setter. {@see \Cake\Mailer\Message::setHeaderCharset()}
Sets headers for the message. {@see \Cake\Mailer\Message::setHeaders()}
Set logging config.
Set message instance.
Sets message ID. {@see \Cake\Mailer\Message::setMessageId()}
Set the model type to be used by this class
Sets the configuration profile to use for this instance.
Sets Read Receipt (Disposition-Notification-To header). {@see \Cake\Mailer\Message::setReadReceipt()}
Set email renderer.
Sets "Reply-To" address. {@see \Cake\Mailer\Message::setReplyTo()}
Sets return path. {@see \Cake\Mailer\Message::setReturnPath()}
Sets "sender" address. {@see \Cake\Mailer\Message::setSender()}
Sets subject. {@see \Cake\Mailer\Message::setSubject()}
Sets the table locator.
Sets "to" address. {@see \Cake\Mailer\Message::setTo()}
Sets the transport.
Sets email view vars.
Get the view builder.
__call(string $method, array $args): $this|mixed
Magic method to forward method class to Message instance.
string
$method Method name.
array
$args Method arguments
$this|mixed
__construct(array<string, mixed>|string|null $config = null)
Constructor
array<string, mixed>|string|null
$config optional Array of configs, or string to load configs from app.php
_setModelClass(string $name): void
Set the modelClass property based on conventions.
If the property is already set it will not be overwritten
string
$name Class name.
void
addAttachments(mixed $attachments): $this
Add attachments. {@see \Cake\Mailer\Message::addAttachments()}
$this
addBcc(mixed $email, mixed $name = null): $this
Add "bcc" address. {@see \Cake\Mailer\Message::addBcc()}
$this
addCc(mixed $email, mixed $name = null): $this
Add "cc" address. {@see \Cake\Mailer\Message::addCc()}
$this
addHeaders(array $headers): $this
Add header for the message. {@see \Cake\Mailer\Message::addHeaders()}
array
$headers $this
addReplyTo(mixed $email, mixed $name = null): $this
Add "Reply-To" address. {@see \Cake\Mailer\Message::addReplyTo()}
$this
addTo(mixed $email, mixed $name = null): $this
Add "To" address. {@see \Cake\Mailer\Message::addTo()}
$this
configured(): array<string>
Returns an array containing the named configurations
array<string>
deliver(string $content = ''): array
Render content and send email using configured transport.
string
$content optional Content.
array
drop(string $config): bool
Drops a constructed adapter.
If you wish to modify an existing configuration, you should drop it, change configuration and then re-add it.
If the implementing objects supports a $_registry
object the named configuration will also be unloaded from the registry.
string
$config An existing configuration you wish to remove.
bool
fetchTable(string|null $alias = null, array<string, mixed> $options = []): Cake\ORM\Table
Convenience method to get a table instance.
string|null
$alias optional The alias name you want to get. Should be in CamelCase format. If null
then the value of $defaultTable property is used.
array<string, mixed>
$options optional The options you want to build the table with. If a table has already been loaded the registry options will be ignored.
Cake\ORM\Table
Cake\Core\Exception\CakeException
flatten(array<string>|string $value): string
Converts given value to string
array<string>|string
$value The value to convert
string
getAttachments(): array
Gets attachments to the email message. {@see \Cake\Mailer\Message::getAttachments()}
array
getBcc(): array
Gets "bcc" address. {@see \Cake\Mailer\Message::getBcc()}
array
getBody(?string $type = null): array|string
Get generated message body as array. {@see \Cake\Mailer\Message::getBody()}
?string
$type optional array|string
getCc(): array
Gets "cc" address. {@see \Cake\Mailer\Message::getCc()}
array
getCharset(): string
Charset getter. {@see \Cake\Mailer\Message::getCharset()}
string
getConfig(string $key): mixed|null
Reads existing configuration.
string
$key The name of the configuration.
mixed|null
getConfigOrFail(string $key): mixed
Reads existing configuration for a specific key.
The config value for this key must exist, it can never be null.
string
$key The name of the configuration.
mixed
InvalidArgumentException
getDomain(): string
Gets domain. {@see \Cake\Mailer\Message::getDomain()}
string
getDsnClassMap(): array<string, string>
Returns the DSN class map for this class.
array<string, string>
getEmailFormat(): string
Gets email format. {@see \Cake\Mailer\Message::getEmailFormat()}
string
getFrom(): array
Gets "from" address. {@see \Cake\Mailer\Message::getFrom()}
array
getHeaderCharset(): string
HeaderCharset getter. {@see \Cake\Mailer\Message::getHeaderCharset()}
string
getHeaders(array $include = []): $this
Get list of headers. {@see \Cake\Mailer\Message::getHeaders()}
array
$include optional $this
getMessage(): Cake\Mailer\Message
Get message instance.
Cake\Mailer\Message
getMessageId(): string|bool
Gets message ID. {@see \Cake\Mailer\Message::getMessageId()}
string|bool
getModelType(): string
Get the model type to be used by this class
string
getReadReceipt(): array
Gets Read Receipt (Disposition-Notification-To header). {@see \Cake\Mailer\Message::getReadReceipt()}
array
getRenderer(): Cake\Mailer\Renderer
Get email renderer.
Cake\Mailer\Renderer
getReplyTo(): array
Gets "Reply-To" address. {@see \Cake\Mailer\Message::getReplyTo()}
array
getReturnPath(): array
Gets return path. {@see \Cake\Mailer\Message::getReturnPath()}
array
getSender(): array
Gets "sender" address. {@see \Cake\Mailer\Message::getSender()}
array
getSubject(): string
Gets subject. {@see \Cake\Mailer\Message::getSubject()}
string
getTableLocator(): Cake\ORM\Locator\LocatorInterface
Gets the table locator.
Cake\ORM\Locator\LocatorInterface
getTo(): array
Gets "to" address. {@see \Cake\Mailer\Message::getTo()}
array
getTransport(): Cake\Mailer\AbstractTransport
Gets the transport.
Cake\Mailer\AbstractTransport
implementedEvents(): array<string, mixed>
Implemented events.
public function implementedEvents() { return [ 'Order.complete' => 'sendEmail', 'Article.afterBuy' => 'decrementInventory', 'User.onRegister' => ['callable' => 'logRegistration', 'priority' => 20, 'passParams' => true] ]; }
array<string, mixed>
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.
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 getModelType() value.
Cake\Datasource\RepositoryInterface
Cake\Datasource\Exception\MissingModelException
UnexpectedValueException
logDelivery(array $contents): void
Log the email message delivery.
array
$contents The content with 'headers' and 'message' keys.
void
modelFactory(string $type, Cake\Datasource\Locator\LocatorInterface|callable $factory): void
Override a existing callable to generate repositories of a given type.
string
$type The name of the repository type the factory function is for.
Cake\Datasource\Locator\LocatorInterface|callable
$factory The factory function used to create instances.
void
parseDsn(string $dsn): array<string, mixed>
Parses a DSN into a valid connection configuration
This method allows setting a DSN using formatting similar to that used by PEAR::DB. The following is an example of its usage:
$dsn = 'mysql://user:pass@localhost/database?'; $config = ConnectionManager::parseDsn($dsn); $dsn = 'Cake\Log\Engine\FileLog://?types=notice,info,debug&file=debug&path=LOGS'; $config = Log::parseDsn($dsn); $dsn = 'smtp://user:secret@localhost:25?timeout=30&client=null&tls=null'; $config = Email::parseDsn($dsn); $dsn = 'file:///?className=\My\Cache\Engine\FileEngine'; $config = Cache::parseDsn($dsn); $dsn = 'File://?prefix=myapp_cake_core_&serialize=true&duration=+2 minutes&path=/tmp/persistent/'; $config = Cache::parseDsn($dsn);
For all classes, the value of scheme
is set as the value of both the className
unless they have been otherwise specified.
Note that querystring arguments are also parsed and set as values in the returned configuration.
string
$dsn The DSN string to convert to a configuration array
array<string, mixed>
InvalidArgumentException
render(string $content = ''): $this
Render content and set message body.
string
$content optional Content.
$this
reset(): $this
Reset all the internal variables to be able to send out a new email.
$this
restore(): $this
Restore message, renderer, transport instances to state before an action was run.
$this
send(string|null $action = null, array $args = [], array $headers = []): array
Sends email.
string|null
$action optional The name of the mailer action to trigger. If no action is specified then all other method arguments will be ignored.
array
$args optional Arguments to pass to the triggered mailer action.
array
$headers optional Headers to set.
array
Cake\Mailer\Exception\MissingActionException
BadMethodCallException
set(array|string $key, mixed $value = null): $this
Sets email view vars.
array|string
$key Variable name or hash of view variables.
mixed
$value optional View variable value.
$this
setAttachments(mixed $attachments): $this
Add attachments to the email message. {@see \Cake\Mailer\Message::setAttachments()}
$this
setBcc(mixed $email, mixed $name = null): $this
Sets "bcc" address. {@see \Cake\Mailer\Message::setBcc()}
$this
setCc(mixed $email, mixed $name = null): $this
Sets "cc" address. {@see \Cake\Mailer\Message::setCc()}
$this
setCharset(mixed $charset): $this
Charset setter. {@see \Cake\Mailer\Message::setCharset()}
$this
setConfig(array<string, mixed>|string $key, object|array<string, mixed>|null $config = null): void
This method can be used to define configuration adapters for an application.
To change an adapter's configuration at runtime, first drop the adapter and then reconfigure it.
Adapters will not be constructed until the first operation is done.
Assuming that the class' name is Cache
the following scenarios are supported:
Setting a cache engine up.
Cache::setConfig('default', $settings);
Injecting a constructed adapter in:
Cache::setConfig('default', $instance);
Configure multiple adapters at once:
Cache::setConfig($arrayOfConfig);
array<string, mixed>|string
$key The name of the configuration, or an array of multiple configs.
object|array<string, mixed>|null
$config optional An array of name => configuration data for adapter.
void
BadMethodCallException
LogicException
setDomain(mixed $domain): $this
Sets domain. {@see \Cake\Mailer\Message::setDomain()}
$this
setDsnClassMap(array<string, string> $map): void
Updates the DSN class map for this class.
array<string, string>
$map Additions/edits to the class map to apply.
void
setEmailFormat(mixed $format): $this
Sets email format. {@see \Cake\Mailer\Message::getHeaders()}
$this
setFrom(mixed $email, mixed $name = null): $this
Sets "from" address. {@see \Cake\Mailer\Message::setFrom()}
$this
setHeaderCharset(mixed $charset): $this
HeaderCharset setter. {@see \Cake\Mailer\Message::setHeaderCharset()}
$this
setHeaders(array $headers): $this
Sets headers for the message. {@see \Cake\Mailer\Message::setHeaders()}
array
$headers $this
setLogConfig(array<string, mixed>|string|true $log): void
Set logging config.
array<string, mixed>|string|true
$log Log config.
void
setMessage(Cake\Mailer\Message $message): $this
Set message instance.
Cake\Mailer\Message
$message Message instance.
$this
setMessageId(mixed $message): $this
Sets message ID. {@see \Cake\Mailer\Message::setMessageId()}
$this
setModelType(string $modelType): $this
Set the model type to be used by this class
string
$modelType The model type
$this
setProfile(array<string, mixed>|string $config): $this
Sets the configuration profile to use for this instance.
array<string, mixed>|string
$config String with configuration name, or an array with config.
$this
setReadReceipt(mixed $email, mixed $name = null): $this
Sets Read Receipt (Disposition-Notification-To header). {@see \Cake\Mailer\Message::setReadReceipt()}
$this
setRenderer(Cake\Mailer\Renderer $renderer): $this
Set email renderer.
Cake\Mailer\Renderer
$renderer Render instance.
$this
setReplyTo(mixed $email, mixed $name = null): $this
Sets "Reply-To" address. {@see \Cake\Mailer\Message::setReplyTo()}
$this
setReturnPath(mixed $email, mixed $name = null): $this
Sets return path. {@see \Cake\Mailer\Message::setReturnPath()}
$this
setSender(mixed $email, mixed $name = null): $this
Sets "sender" address. {@see \Cake\Mailer\Message::setSender()}
$this
setSubject(mixed $subject): $this
Sets subject. {@see \Cake\Mailer\Message::setSubject()}
$this
setTableLocator(Cake\ORM\Locator\LocatorInterface $tableLocator): $this
Sets the table locator.
Cake\ORM\Locator\LocatorInterface
$tableLocator LocatorInterface instance.
$this
setTo(mixed $email, mixed $name = null): $this
Sets "to" address. {@see \Cake\Mailer\Message::setTo()}
$this
setTransport(Cake\Mailer\AbstractTransport|string $name): $this
Sets the transport.
When setting the transport you can either use the name of a configured transport or supply a constructed transport.
Cake\Mailer\AbstractTransport|string
$name Either the name of a configured transport, or a transport instance.
$this
LogicException
InvalidArgumentException
setViewVars(array|string $key, mixed $value = null): $this
Sets email view vars.
array|string
$key Variable name or hash of view variables.
mixed
$value optional View variable value.
$this
viewBuilder(): Cake\View\ViewBuilder
Get the view builder.
Cake\View\ViewBuilder
Configuration sets.
array<string, mixed>
Mailer driver class map.
array<string, string>
A list of overridden model factory functions.
array<callableCake\Datasource\Locator\LocatorInterface>
The model type to use.
string
Table locator instance
Cake\ORM\Locator\LocatorInterface|null
Hold message, renderer and transport instance for restoring after running a mailer action.
array<string, mixed>
This object's default table alias.
string|null
array|null
Message instance.
Cake\Mailer\Message
Message class name.
string
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 empty string to not use auto-loading on this object. Null auto-detects based on controller name.
string|null
Mailer's name.
string
Email Renderer
Cake\Mailer\Renderer|null
The transport instance to use for sending mail.
Cake\Mailer\AbstractTransport|null
© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/4.4/class-Cake.Mailer.Mailer.html