E-mailek küldése

E-maileket szeretne küldeni, például hírleveleket vagy megrendelés-visszaigazolásokat? A Nette Framework biztosítja a szükséges eszközöket egy nagyon kellemes API-val. Megmutatjuk:

hogyan hozzon létre e-mailt mellékletekkel együtt
hogyan küldje el
hogyan kapcsolja össze az e-maileket és a sablonokat

Telepítés

A könyvtárat a Composer segítségével töltheti le és telepítheti:

composer require nette/mail

E-mail létrehozása

Az e-mail a Nette\Mail\Message osztály objektuma. Hozzuk létre például így:

$mail = new Nette\Mail\Message;
$mail->setFrom('Franta <franta@example.com>')
	->addTo('petr@example.com')
	->addTo('jirka@example.com')
	->setSubject('Megrendelés visszaigazolása')
	->setBody("Jó napot,\na megrendelését elfogadtuk.");

Minden megadott paraméternek UTF-8 kódolásúnak kell lennie.

A címzett addTo() metódussal történő megadása mellett megadhatunk másolatot kapó címzettet (addCc()) vagy rejtett másolatot kapó címzettet (addBcc()) is. Mindezekben a metódusokban, beleértve a setFrom() metódust is, a címzettet háromféleképpen adhatjuk meg:

$mail->setFrom('franta@example.com');
$mail->setFrom('franta@example.com', 'Franta');
$mail->setFrom('Franta <franta@example.com>');

A HTML formátumú e-mail törzsét a setHtmlBody() metódussal adjuk át:

$mail->setHtmlBody('<p>Jó napot,</p><p>a megrendelését elfogadtuk.</p>');

Nem kell szöveges alternatívát létrehoznia, a Nette automatikusan legenerálja Ön helyett. És ha az e-mailnek nincs beállított tárgya, megpróbálja átvenni a <title> elemből.

Képeket is rendkívül egyszerűen beilleszthet a HTML törzsbe. Csak adja át második paraméterként az elérési utat, ahol a képek fizikailag találhatók, és a Nette automatikusan belefoglalja őket az e-mailbe:

// automatikusan hozzáadja a /path/to/images/background.gif fájlt az e-mailhez
$mail->setHtmlBody(
	'<b>Hello</b> <img src="background.gif">',
	'/path/to/images',
);

A képeket beillesztő algoritmus ezeket a mintákat keresi: <img src=...>, <body background=...>, url(...) a HTML style attribútumon belül és a speciális [[...]] szintaxist.

Lehet még ennél is egyszerűbb az e-mailek küldése?

Az e-mail olyan, mint egy képeslap. Soha ne küldjön jelszavakat vagy más hozzáférési adatokat e-mailben.

Mellékletek

Természetesen mellékleteket is csatolhatunk az e-mailhez. Erre szolgál az addAttachment(string $file, ?string $content = null, ?string $contentType = null) metódus.

// beilleszti az e-mailbe a /path/to/example.zip fájlt example.zip néven
$mail->addAttachment('/path/to/example.zip');

// beilleszti az e-mailbe a /path/to/example.zip fájlt info.zip néven
$mail->addAttachment('info.zip', file_get_contents('/path/to/example.zip'));

// beilleszti az e-mailbe az example.txt fájlt "Hello John!" tartalommal
$mail->addAttachment('example.txt', 'Hello John!');

Sablonok

Ha HTML e-maileket küld, kézenfekvő, hogy a Latte sablonrendszerben írja meg őket. Hogyan csináljuk?

$latte = new Latte\Engine;
$params = [
	'orderId' => 123,
];

$mail = new Nette\Mail\Message;
$mail->setFrom('Franta <franta@example.com>')
	->addTo('petr@example.com')
	->setHtmlBody(
		$latte->renderToString('/path/to/email.latte', $params),
		'/path/to/images', // elérési út a képekhez
	);

Az email.latte fájl:

<html>
<head>
	<meta charset="utf-8">
	<title>Megrendelés visszaigazolása</title>
	<style>
	body {
		background: url("background.png")
	}
	</style>
</head>
<body>
	<p>Jó napot,</p>

	<p>A(z) {$orderId} számú megrendelését elfogadtuk.</p>
</body>
</html>

A Nette automatikusan beilleszti az összes képet, beállítja a tárgyat a <title> elem alapján, és legenerálja a szöveges alternatívát a HTML-hez.

Használat a Nette Applicationben

Ha az e-maileket a Nette Applicationnel együtt használja, azaz presenterekkel, akkor lehet, hogy a sablonokban linkeket szeretne létrehozni az n:href attribútummal vagy a {link} taggel. Ezeket a Latte alapból nem ismeri, de nagyon könnyű hozzáadni őket. A linkeket a Nette\Application\LinkGenerator objektum tudja létrehozni, amelyhez úgy juthat hozzá, hogy dependency injection segítségével átadja magának:

use Nette;

class MailSender
{
	public function __construct(
		private Nette\Application\LinkGenerator $linkGenerator,
		private Nette\Bridges\ApplicationLatte\TemplateFactory $templateFactory,
	) {
	}

	private function createTemplate(): Nette\Application\UI\Template
	{
		$template = $this->templateFactory->createTemplate();
		$template->getLatte()->addProvider('uiControl', $this->linkGenerator);
		return $template;
	}

	public function createEmail(): Nette\Mail\Message
	{
		$template = $this->createTemplate();
		$html = $template->renderToString('/path/to/email.latte', $params);

		$mail = new Nette\Mail\Message;
		$mail->setHtmlBody($html);
		// ...
		return $mail;
	}
}

A sablonban ezután a megszokott módon hozunk létre linkeket. A LinkGeneratoron keresztül létrehozott összes link abszolút lesz.

<a n:href="Presenter:action">Link</a>

E-mail küldése

A Mailer egy osztály, amely biztosítja az e-mailek küldését. Implementálja a Nette\Mail\Mailer interfészt, és több előre elkészített mailer áll rendelkezésre, amelyeket bemutatunk.

A keretrendszer automatikusan hozzáad egy Nette\Mail\Mailer típusú szolgáltatást a DI konténerhez, amely a #konfiguráció alapján van összeállítva, és amelyhez úgy juthat hozzá, hogy dependency injection segítségével átadja magának.

SendmailMailer

Az alapértelmezett mailer a SendmailMailer, amely a PHP mail függvényét használja. Példa a használatra:

$mailer = new Nette\Mail\SendmailMailer;
$mailer->send($mail);

Ha be szeretné állítani a returnPath-t, és a szerver folyamatosan felülírja, használja a $mailer->commandArgs = '-fMuj@email.cz' parancsot.

SmtpMailer

Az SmtpMailer az e-mailek SMTP szerveren keresztüli küldésére szolgál.

$mailer = new Nette\Mail\SmtpMailer(
	host: 'smtp.gmail.com',
	username: 'franta@gmail.com',
	password: '*****',
	encryption: 'ssl',
);
$mailer->send($mail);

A konstruktornak a következő további paramétereket lehet átadni:

port – ha nincs beállítva, az alapértelmezett 25 vagy 465 lesz használva ssl esetén
timeout – időtúllépés az SMTP kapcsolathoz
persistent – perzisztens kapcsolat használata
clientHost – a kliens Host fejlécének beállítása
streamOptions – lehetővé teszi az context.ssl.php beállítását a kapcsolathoz

FallbackMailer

Nem küld közvetlenül e-maileket, hanem egy mailer készleten keresztül közvetíti a küldést. Ha az egyik mailer meghibásodik, megismétli a próbálkozást a következővel. Ha az utolsó is meghibásodik, újra kezdi az elsőtől.

$mailer = new Nette\Mail\FallbackMailer([
	$smtpMailer,
	$backupSmtpMailer,
	$sendmailMailer,
]);
$mailer->send($mail);

További paraméterként a konstruktorban megadhatjuk az ismétlések számát és a várakozási időt milliszekundumban.

DKIM

A DKIM (DomainKeys Identified Mail) egy technológia az e-mailek hitelességének növelésére, amely segít a hamisított üzenetek felderítésében is. Az elküldött üzenetet a feladó domainjének privát kulcsával írják alá, és ezt az aláírást az e-mail fejlécében tárolják. A címzett szervere összehasonlítja ezt az aláírást a domain DNS rekordjaiban tárolt nyilvános kulccsal. Az aláírás egyezése bizonyítja, hogy az e-mail valóban a feladó domainjéből származik, és hogy az üzenet továbbítása során nem módosították.

Az e-mailek aláírását beállíthatja a mailernek közvetlenül a konfigurációt. Ha nem használ dependency injectiont, akkor így használatos:

$signer = new Nette\Mail\DkimSigner(
	domain: 'nette.org',
	selector: 'dkim',
	privateKey: file_get_contents('../dkim/dkim.key'),
	passPhrase: '****',
);

$mailer = new Nette\Mail\SendmailMailer; // vagy SmtpMailer
$mailer->setSigner($signer);
$mailer->send($mail);

Konfiguráció

A Nette Mail konfigurációs opcióinak áttekintése. Ha nem a teljes keretrendszert használja, csak ezt a könyvtárat, olvassa el, hogyan kell betölteni a konfigurációt.

Az e-mailek küldéséhez alapértelmezés szerint a Nette\Mail\SendmailMailer mailert használjuk, amelyet nem kell tovább konfigurálni. Átkapcsolhatjuk azonban a Nette\Mail\SmtpMailer-re:

mail:
	# SmtpMailer használata
	smtp: true       # (bool) alapértelmezett: false

	host: ...        # (string)
	port: ...        # (int)
	username: ...    # (string)
	password: ...    # (string)
	timeout: ...     # (int)
	encryption: ...  # (ssl|tls|null) alapértelmezett: null (alias: 'secure')
	clientHost: ...  # (string) alapértelmezett: $_SERVER['HTTP_HOST']
	persistent: ...  # (bool) alapértelmezett: false

	# kontextus az SMTP szerverhez való csatlakozáshoz, alapértelmezett: stream_context_get_default()
	context:
		ssl:         # opciók áttekintése: https://www.php.net/manual/en/context.ssl.php
			allow_self_signed: ...
			...
		http:        # opciók áttekintése: https://www.php.net/manual/en/context.http.php
			header: ...
			...

A context › ssl › verify_peer: false opcióval kikapcsolható az SSL tanúsítványok ellenőrzése. Erősen nem ajánljuk ezt tenni, mert az alkalmazás sebezhetővé válik. Ehelyett openssl.configuration.php.

A hitelesség növelése érdekében az e-maileket aláírhatjuk DKIM technológiával:

mail:
	dkim:
		domain: myweb.com
		selector: lovenette
		privateKey: %appDir%/cert/dkim.priv
		passPhrase: ...

DI Szolgáltatások

Ezek a szolgáltatások kerülnek hozzáadásra a DI konténerhez:

Név	Típus	Leírás
`mail.mailer`	Nette\Mail\Mailer	e-maileket küldő osztály
`mail.signer`	Nette\Mail\Signer	DKIM aláírás