MailController

MMO\core\controllers · 1 symbol · generated 5 Oct 2026

class

MailController

Send templated HTML emails (mail/Send), rendering a template file (via Document::import) into an HtmlDocument and passing its output as the body of a Mail.

class MMO\core\controllers\MailController extends MMO\core\classes\aController

Namespace: MMO\core\controllers
Extends: aController
See: $repository is set to a repository holding a collection of MailLog.

Every mail it sends ([`sendMail`](https://mcp.mmoframework.fr/documentation/mmo.core/php/controllers/MailController.md#mailcontroller-sendmail)) is journaled as a [`MailLog`](https://mcp.mmoframework.fr/documentation/mmo.core/php/entities/MailLog.md#maillog) -- sent or failed, to whom, by what -- once

MailController::Shared()->templateFolder = '{root}/templates/mail'; MailController::Shared()->setEmail('from', 'noreply@example.com'); MailController::Send('welcome.phtml', 'user@example.com', 'Welcome!', ['name' => 'Marc']);

Index

	domain	Fallback domain used by `toEmail`'s `@alias` shorthand when the alias isn't a registered email (`setEmail`).
	emails	name => email, e.g. `['from' => 'noreply@example.com']` -- `getEmail`/`setEmail`/`toEmail`'s `@name` shorthand.
	journalBody	Keep the html of each mail in its journal (`MailLog::$body`), to read what was sent.
	repository	The repository every mail sent is journaled into (`journal`): its collection of `MailLog`.
	routeAnyRecipient	Let `POST email.html` (`routeMail`) mail any address.
	templateFolder	Path (or path-alias, e.g.
	findTemplate($template)	Resolve $template to its file, which must be within `$templateFolder`.
	getEmail($name)
	getTemplateFolder()
	journal($mail, $template, $error)	Record $mail in `$repository`'s collection of `MailLog`, saving that entry alone (never the other changes waiting for a commit).
	mail($template, $email, $subject, $data, $from)	Render $template (a file under `$templateFolder`, `findTemplate` -- by its filename, extension included: `welcome.phtml`) with $data available as template variables (`$_VARS['name']`), and em…
	RealFilename($filename) static	`realpath()` that also works in a stream (`phar://...`): a release runs its packages from their phar, where `realpath()` answers false for every file.
	routeMail($route)	API endpoint: send a templated email per the request body (`template`/`email`/`subject`/`data`), then respond with the rendered document.
	Send($template, $email, $subject, $data, $from) static	Shorthand for `static::Shared()->mail(...)` -- `mail`.
	sendMail($mail, $template)	Send $mail and journal it (`journal`), whether it left or not: a mail built by hand (attachments, cc...) goes through here to be journaled too.
	setEmail($name, $email)	Register a named email address, usable via `toEmail`'s `@name` shorthand.
	toEmail($name)	Resolve an email address or a `@name`-style shorthand.
	__wakeup()	Defaults `$domain` to the server's hostname and `$emails[`'from'] to the `sendmail_from` ini setting, if not already set.

Properties6

domain

Fallback domain used by toEmail's @alias shorthand when the alias isn't a registered email (setEmail). Defaults to the server's hostname (__wakeup).

string $domain

Type: string

emails

name => email, e.g. ['from' => 'noreply@example.com'] -- getEmail/setEmail/toEmail's @name shorthand.

array $emails = []

Type: array

journalBody

Keep the html of each mail in its journal (MailLog::$body), to read what was sent.

bool $journalBody = true

Type: bool

repository

The repository every mail sent is journaled into (journal): its collection of MailLog. null (or no such collection): nothing is journaled.

?MMO\core\classes\aRepository $repository = null

Type: null | aRepository

routeAnyRecipient

Let POST email.html (routeMail) mail any address. By default it only mails a name registered in $emails (@support): any user logged in could otherwise send the application's mails, from its address, to anyone.

bool $routeAnyRecipient = false

Type: bool

templateFolder

Path (or path-alias, e.g. '{root}/templates') template names are resolved against (getTemplateFolder).

string $templateFolder

Type: string

Methods12

findTemplate($template)

MailController.php:94

Resolve $template to its file, which must be within $templateFolder.

function findTemplate(string $template): string

$template	string	a filename relative to `$templateFolder`, extension included (`welcome.phtml`).
returns	string	the template's absolute filename.
throws		if `$templateFolder` isn't set.
throws		if $template is no file of `$templateFolder`: missing, absolute, or out of it through `..`.

$ctrl->findTemplate('welcome.phtml'); // '/var/www/app/templates/mail/welcome.phtml'

getEmail($name)

MailController.php:53

function getEmail(string $name): ?string

$name	string
returns	null \| string	the email registered under $name (`setEmail`), or null if none is.

getTemplateFolder()

MailController.php:82

function getTemplateFolder(): string

returns string $templateFolder resolved to an absolute path (path-aliases like {root} expanded).

journal($mail, $template, $error)

MailController.php:181

Record $mail in $repository's collection of MailLog, saving that entry alone (never the other changes waiting for a commit). The entry is dispatched before being saved: a listener can complete it, or ignore() it.

function journal( MMO\core\server\Mail $mail, ?string $template = null, ?Throwable $error = null ): ?MMO\core\entities\MailLog

A journal that cannot be written is a warning, never a failure: the mail is gone already.

$mail	Mail
$template = null	null \| string
$error = null	null \| Throwable	why it did not leave; null when it did.
returns	null \| MailLog	the entry saved; null if there is no journal, or a listener ignored it.

mail($template, $email, $subject, $data, $from)

MailController.php:134

Render $template (a file under $templateFolder, findTemplate -- by its filename, extension included: welcome.phtml) with $data available as template variables ($_VARS['name']), and email the result.

function mail( string $template, string $email, string $subject, ArrayAccess|array $data = [], ?string $from = null ): MMO\core\documents\HtmlDocument

$template	string
$email	string	`toEmail`.
$subject	string
$data = []	ArrayAccess \| array	variables available to the template.
$from = null	null \| string	`toEmail`; defaults to `$emails[`'from'].
returns	HtmlDocument	the rendered document (already sent as the email body).
throws		if `$templateFolder` isn't set, or the mail cannot be sent (`Mail::send`).
throws		if $template is not found (nothing is sent).

RealFilename($filename)

staticMailController.php:114

realpath() that also works in a stream (phar://...): a release runs its packages from their phar, where realpath() answers false for every file. There, . and .. are resolved by hand (a phar has no symlink).

static function RealFilename(string $filename): string|false

$filename	string
returns	string \| false	the canonical filename, without trailing separator; false if it does not exist.

MailController::RealFilename('phar:///var/www/app.phar/src/pages/../pages/emails'); // 'phar:///var/www/app.phar/src/pages/emails'

routeMail($route)

MailController.php:231

API endpoint: send a templated email per the request body (template/email/subject/data), then respond with the rendered document. email is a name registered in $emails (@support), unless

#[MMO\core\attributes\APIRoute('POST|email.html', body: […4 items])] function routeMail(MMO\core\server\Route $route): MMO\core\server\Response

See: $routeAnyRecipient; template a file of $templateFolder (findTemplate).

$route	Route
returns	Response
throws		403 if `email` is not a registered name, 404 if `template` is not found.

Send($template, $email, $subject, $data, $from)

staticMailController.php:39

Shorthand for static::Shared()->mail(...) -- mail.

static function Send( string $template, string $email, string $subject, ArrayAccess|array $data = [], ?string $from = null ): MMO\core\documents\HtmlDocument

$template	string
$email	string
$subject	string
$data = []	ArrayAccess \| array
$from = null	null \| string
returns	HtmlDocument

sendMail($mail, $template)

MailController.php:163

Send $mail and journal it (journal), whether it left or not: a mail built by hand (attachments, cc...) goes through here to be journaled too.

function sendMail(MMO\core\server\Mail $mail, ?string $template = null): void

$mail	Mail
$template = null	null \| string	the template its body was rendered from, for the journal.
returns	void
throws		if it cannot be sent (`Mail::send`) -- after journaling it as failed.

$mail = new Mail('a@example.com', 'Invoice', $html, MailController::Shared()->getEmail('from')); $mail->addAttachment('/path/to/invoice.pdf'); MailController::Shared()->sendMail($mail);

setEmail($name, $email)

MailController.php:58

function setEmail(string $name, string $email): void

$name	string
$email	string
returns	void

toEmail($name)

MailController.php:72

Resolve an email address or a @name-style shorthand.

function toEmail(string $name): string

$name	string	a literal email address, or `@name` (looked up via `getEmail`, falling back to `name@`.`$domain` if not registered).
returns	string

$ctrl->setEmail('support', 'help@example.com'); $ctrl->toEmail('@support'); // 'help@example.com' $ctrl->toEmail('@sales'); // 'sales@' . $ctrl->domain -- not registered, falls back to the domain $ctrl->toEmail('a@b.com'); // 'a@b.com' -- not an @-shorthand, returned as-is

__wakeup()

MailController.php:44

Defaults $domain to the server's hostname and $emails['from'] to the sendmail_from ini setting, if not already set.

function __wakeup(): void

returns

void

Inherited members (55)

Constants	Declared by	Description
`ALERT`	iLogLevel	Alert: Action must be taken immediately.
`ALL`	iLogLevel	Mask for all
`ALL_PLUS`	iLogLevel	debug everything
`BACKTRACE`	iLogLevel
`CRITICAL`	iLogLevel	Critical: Critical conditions.
`DEBUG`	iLogLevel	Debug: Detailed debug information.
`DEEP`	iLogLevel	debug everything with arguments
`EMERGENCY`	iLogLevel	Emergency: System is unusable.
`ERROR`	iLogLevel	Error: Runtime errors that do not require immediate action but should typically be logged and monitored.
`ERROR_PLUS`	iLogLevel	Mask for all error
`FATAL`	iLogLevel	Mask for all fatal error
`INFO`	iLogLevel	Info: Interesting events.
`INFO_PLUS`	iLogLevel	Mask for all errors/warning/notices/info
`MEMORY`	iLogLevel	include backtrace object
`NOTICE`	iLogLevel	Notice: Normal but significant events.
`NOTICE_PLUS`	iLogLevel	Mask for all errors/warning/notices/info
`TRACE`	iLogLevel	include backtrace as origins
`WARNING`	iLogLevel	Warning: Exceptional occurrences that are not errors.
`WARNING_PLUS`	iLogLevel	Mask for all errors and warnings

	Properties	Declared by	Description
	`verbosity`	aModule

Methods	Declared by	Description
`alert($message, $context)`	aModule	Action must be taken immediately.
`backtraces($message, $context)`	aModule	Force-log a message at INFO level together with a full stack trace/memory snapshot (`iLogLevel::BACKTRACE`), bypassing the verbosity mask entirely (any non-zero verbosity is enough to trigger it).
`Configure($config)`	aModule	Merge $config into this module's configuration in the shared `Configuration`.
`critical($message, $context)`	aModule	Critical conditions. No-op if CRITICAL is currently filtered out by the verbosity mask.
`debug($message, $context)`	aModule	Detailed debug information.
`debugName()`	aModule	Human-readable identifier used as the default `{origin}` in this instance's log messages.
`DefaultConfig()`	aModule	The config a module starts from before anything loaded via `Configuration` is merged in.
`emergency($message, $context)`	aModule	System is unusable. No-op if EMERGENCY is currently filtered out by the verbosity mask.
`error($message, $context)`	aModule	Runtime errors that do not require immediate action but should typically be logged and monitored.
`ExtractRoutes($config)`	aController	Extract all the APIRoute from this class, regardless of the fact they are registered in the application
`getVerbosity()`	aModule
`HasRoutes()`	aController	Tells if any APIRoute are registered in the application
`info($message, $context)`	aModule	Interesting events. No-op if INFO is currently filtered out by the verbosity mask.
`Instantiate($config)`	aModule	(Re)create the shared instance immediately, configured with $config merged into the class's existing config.
`IsShared()`	aModule
`Link($method, $data)`	aController	Build a `Link` (URL + label/icon/description/title, taken from the route's APIRoute metadata) for a registered route.
`log($level, $message, $context)`	aModule	Logs with an arbitrary level.
`notice($message, $context)`	aModule	Normal but significant events.
`offsetExists($key)`	aModule	\ArrayAccess::offsetExists -- tells whether $key is a declared property at all, regardless of whether it is currently readable/writable through array access.
`offsetGet($key)`	aModule	\ArrayAccess::offsetGet -- reads a property directly, unless it has a `#[Serialize(serialize: 'methodName')]` attribute, in which case that zero-argument method is called instead (e.g.
`offsetSet($key, $value)`	aModule	\ArrayAccess::offsetSet -- sets a property directly, unless it has a `#[Serialize(unserialize: 'methodName')]` attribute, in which case that method is called with $value instead (e.g.
`offsetUnset($key)`	aModule	\ArrayAccess::offsetUnset -- equivalent to `$module[$key] = null`.
`onRoute($route)`	aController	This function is called before any api route declared.
`Route($method)`	aController	Get a registered APIRoute WARNING: if this class was not registered in the application, it will return null.
`Routes()`	aController	Get a list of registered APIRoutes (from this class) in the application WARNING: if this class was not registered in the application, it will return an empty array.
`serialize($path, $serializer)`	aModule	\MMO\core\interfaces\iSerializable::serialize -- exports every property (via
`setVerbosity($verb)`	aModule	Set the current verbosity mask, replacing whatever it was before.
`Shared()`	aModule	Get the shared instance, creating (and configuring) it on first call.
`testVerbosity($level)`	aModule	Test whether a given level (or set of levels) is currently enabled by this instance's verbosity mask.
`traitUnshare($serialize)`	aModule	Remove the shared instance, so the next `Shared()` call creates a fresh one.
`unserialize($data, $path, $instances)`	aModule	\MMO\core\interfaces\iSerializable::unserialize -- merges $data onto `DefaultConfig`, runs it through the (possibly overridden) constructor, then applies each resulting value to its property (via
`Unshare($serialize)`	aModule	Like `tSingleton::Unshare`, but also disconnects this module's instance from every event it was listening to (via `Event::DisconnectListeners`) before dropping it.
`Url($method, $data)`	aController	Build the URL for a registered route, filling in any `{placeholder}` from $data.
`warning($message, $context)`	aModule	Exceptional occurrences that are not errors.
`__construct($config)`	aModule	protected constructor, so it is not possible to do `new Module(...)` called by the serialization process just before being injected with data.