Sending an email¶
To send an email there are two methods in response called sendEmail() and sendEmailToUser().
$subject can be an array keyed by language (keys are lowercased) to serve subjects for multiple languages. The entry of $lang is used, falling back to en, so an en entry is required.
$document is the path to a view. Any view can be used as a mail. But it is wise to create extra ones, because script stuff won't work. Be careful not to leak data that only the requested account has access to.
$opt are parameters to pass into the view. There, $opt["overwrite_lang"] holds the lowercased $lang (null becomes en), $opt["application_root"] the host plus root folder for absolute links, and $opt["user"] the user of the current request, not the recipient.
This method uses render() internally. render() does not throw for a missing $document or layout: it catches the view-not-found error and renders the framework's 500 view in layout/min_layout instead, so the mail is still sent with the error page as its body. Check the view name, especially for views you ship yourself.
sendEmail() sends synchronously to a single recipient (no CC, BCC, reply-to, queue or retry) and returns true after sending. The body goes out as UTF-8 HTML with a plain-text alternative made by stripping its tags. If PHPMailer fails (SMTP unreachable, rejected login), it echoes Message could not be sent. Mailer Error: ... into the response output and returns false; nothing is logged. The default $layout is email, which resolves to layout/email_layout (mail, mail_layout and layout/mail_layout.php all name the same layout); the framework only ships layout/mail_layout, so create email_layout yourself or pass another layout.
Bundled mail views¶
The framework ships three mail views, each a .blade.php file that a view of the same name in your z_views directory replaces:
email_verifyis sent when someone signs up or asks for a new verification link. It expects the optionurl. The subject is<pageName> - Sign Upand thepageNamesetting must exist in the booter settings: the framework reads it withgetBooterSettings("pageName", ""), whose second argument is$useDefault, and the empty string counts as false, so a missing key throws anInvalidArgumentExceptioninstead of falling back to an empty prefix.email_password_resetis sent by the forgot-password flow. It expects the optionreset_link.email_too_many_loginsexpects the optionsdateandip.$req->ip()can be spoofed with a request header and the view prints it unescaped, validate it first. The framework no longer sends it itself, see Send the login warning yourself.
A mail view you add yourself should not reuse these names unless it is meant to replace the bundled one. All three are written in Blade and extend $layout.
For this feature to work a mail address needs to be configured in the booter settings and a SMTP service needs to be available. PHP need to be setup correctly too.
Example code for sending a mail:
public function action_register(Request $req, Response $res) {
if($req->isAction("register")) {
$email = $req->getPost("email");
$password = $req->getPost("password");
$response = $req->getModel("Employee")->register($email, $password);
if(!$response) {
return $res->error();
}
$res->sendEmail(
$email , // Target address
["en" => "Welcome Mail", "de" => "Willkommens Mail"], // Subject
"email_welcome", // Path to the email view
"en", // Language used in the email
[
"email" => $email
], // Options
"employee/mail_layout" // Layout to use
);
}
}
Example Layout¶
<html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
@yield("head")
</head>
<body>
Welcome <?= $opt["email"] ?>!
@yield("content")
</body>
</html>
Send to registered users¶
sendEmailToUser() sends a mail to an user identified by its user id. The mail address and language are fetched from the database, so less information is needed; if the z_language row of z_user.languageId has no value, the anonymous_language setting (no default) is used, and en if that is unset too. It returns the result of sendEmail(), and its default layout is the bundled layout/mail_layout, which only prints the view's content. It throws an Exception if the user does not exist or has no email address.
Exmaple:
$res->sendEmailToUser(
1, // User ID
["en" => "New cooking recipes!", "de" => "Neue Kochrezepte!"], // Subject
"email_recipes", // Path to the mail view
["r1" => "Cake", "r2" => "Cookies!!!"], // Options
"layout/email_layout" // Layout to use
);