E-mailek küldése

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

hogyan hozhatunk létre e-mailt, csatolmányokkal együtt
hogyan kell elküldeni
hogyan lehet e-maileket és sablonokat kombinálni

Telepítés

Töltse le és telepítse a csomagot a Composer segítségével:

composer require nette/mail

E-mailek létrehozása

Az e-mail egy Nette\Mail\Message objektum:

$mail = new Nette\Mail\Message;
$mail->setFrom('John <john@example.com>')
	->addTo('peter@example.com')
	->addTo('jack@example.com')
	->setSubject('Order Confirmation')
	->setBody("Hello, Your order has been accepted.");

Minden paramétert UTF-8 kódolásban kell megadni.

A addTo() módszerrel megadott címzettek mellett a addCc() módszerrel a másolat címzettjét, a addBcc() módszerrel pedig a vakmásolat címzettjét is megadhatja. Mindezek a módszerek, beleértve a setFrom()-t is, háromféleképpen fogadják el a címzettet:

$mail->setFrom('john.doe@example.com');
$mail->setFrom('john.doe@example.com', 'John Doe');
$mail->setFrom('John Doe <john.doe@example.com>');

A HTML-ben írt e-mail testét a setHtmlBody() módszerrel adja át:

$mail->setHtmlBody('<p>Hello,</p><p>Your order has been accepted.</p>');

Nem kell szöveges alternatívát létrehoznia, a Nette automatikusan generálja Önnek. Ha pedig az e-mailnek nincs beállított tárgya, akkor azt a Nette a <title> elemet.

A képek is rendkívül egyszerűen beilleszthetők az e-mail HTML testébe. Csak adja meg második paraméterként azt az elérési utat, ahol a képek fizikailag találhatók, és a Nette automatikusan beilleszti őket az e-mailbe:

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

A képbeágyazási algoritmus a következő mintákat támogatja: <img src=...>, <body background=...>, url(...) a HTML-attribútumon belül style és speciális szintaxis [[...]].

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

Az e-mailek olyanok, mint a képeslapok. Soha ne küldjön jelszavakat vagy más hitelesítő adatokat e-mailben.

Csatolmányok

Természetesen csatolhat csatolmányokat is az e-mailhez. Használja a addAttachment(string $file, ?string $content = null, ?string $contentType = null).

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

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

// csatolja az új example.txt fájl tartalmát "Hello John!"
$mail->addAttachment('example.txt', 'Hello John!');

Sablonok

Ha HTML e-maileket küldesz, érdemes a Latte sablonrendszerben megírni őket. Hogyan kell ezt megtenni?

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

$mail = new Nette\Mail\Message;
$mail->setFrom('John <john@example.com>')
	->addTo('jack@example.com')
	->setHtmlBody(
		$latte->renderToString('/path/to/email.latte', $params),
		'/path/to/images',
	);

Fájl email.latte:

<html>
<head>
	<meta charset="utf-8">
	<title>Order Confirmation</title>
	<style>
	body {
		background: url("background.png")
	}
	</style>
</head>
<body>
	<p>Hello,</p>

	<p>Your order number {$orderId} has been accepted.</p>
</body>
</html>

A Nette automatikusan beilleszti az összes képet, beállítja a témát a megadott <title> elemnek megfelelően, és alternatív szöveget generál a HTML-szövegtesthez.

Használat a Nette alkalmazásban

Ha e-maileket használ a Nette alkalmazással együtt, azaz előadókat, akkor a sablonokban linkeket hozhat létre a n:href attribútum vagy a {link} címke használatával. A Nette alapvetően nem ismeri ezeket, de nagyon könnyen hozzáadhatja őket. A linkek létrehozásához képes objektum Nette\Application\LinkGenerator, amelyet a függőségi injektálással történő átadással kapunk.

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 a linket úgy hozzuk létre, mint egy normál sablonban. Minden LinkGeneratoron keresztül létrehozott link abszolút:

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

E-mail küldése

A Mailer osztály felelős az e-mailek küldéséért. A Nette\Mail\Mailer interfészt valósítja meg, és számos kész mailer áll rendelkezésre, amelyeket be fogunk mutatni.

A keretrendszer automatikusan hozzáad egy Nette\Mail\Mailer szolgáltatást a konfiguráció alapján a DI konténerhez, amit függőségi injektálással átadva kapunk meg.

SendmailMailer

Az alapértelmezett levelező a SendmailMailer, amely a mail PHP függvényt használja. Használati példa:

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

Ha a returnPath címet szeretné beállítani, és a szerver mégis felülírja, használja a $mailer->commandArgs = '-fmy@email.com' címet.

SmtpMailer

Az SMTP-kiszolgálón keresztül történő levélküldéshez használja a SmtpMailer címet.

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

A következő további paraméterek adhatók át a konstruktornak:

port – ha nincs megadva, akkor az alapértelmezett 25 vagy 465 lesz használva a ssl esetében.
timeout – az SMTP-kapcsolat időkorlátja.
persistent – állandó kapcsolat használata
clientHost – ügyfélkijelölés
streamOptions – lehetővé teszi a kapcsolat SSL-kontextus beállításait.

FallbackMailer

Nem küld e-maileket, hanem egy sor levelezőn keresztül küldi azokat. Ha az egyik levelező nem sikerül, megismétli a kísérletet a következővel. Ha az utolsó is sikertelen, akkor az elsőtől kezdi újra.

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

A konstruktor további paraméterei közé tartozik az ismétlés száma és a várakozási idő milliszekundumban.

DKIM

A DKIM (DomainKeys Identified Mail) egy megbízható e-mail technológia, amely segít a hamisított üzenetek felismerésében is. Az elküldött üzenetet a feladó tartományának magánkulcsával írják alá, és ez az aláírás az e-mail fejlécében tárolódik. A címzett szervere ezt az aláírást összehasonlítja a tartomány DNS-bejegyzésében tárolt nyilvános kulccsal. Az aláírás összevetésével kimutatható, hogy az e-mail valóban a feladó tartományából származik, és hogy az üzenetet nem módosították az üzenet továbbítása során.

A konfigurációban beállíthatja, hogy a mailer aláírja az e-maileket. Ha nem használja a függőségi injektálást, akkor a következőképpen használja:

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

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

A konfigurálása.

A Nette Mail konfigurációs lehetőségeinek áttekintése. Ha nem a teljes keretrendszert, hanem csak ezt a könyvtárat használja, olvassa el , hogyan töltse be a konfigurációt.

Alapértelmezés szerint a Nette\Mail\SendmailMailer levelezőt használja az e-mailek küldésére, amely nincs tovább konfigurálva. Azonban átállíthatjuk a Nette\Mail\SmtpMailer címre:

mail:
	# use SmtpMailer
	smtp: true       # (bool) alapértelmezett értéke false

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

	# kontextus az SMTP-kiszolgálóhoz való csatlakozáshoz, alapértelmezés szerint stream_context_get_default()
	context:
		ssl:         # all options at https://www.php.net/manual/en/context.ssl.php
			allow_self_signed: ...
			...
		http:        # minden opció a https://www.php.net/manual/en/context.http.php oldalon
			header: ...
			...

A context › ssl › verify_peer: false opcióval kikapcsolhatjuk az SSL-tanúsítvány hitelesítését. Ezt határozottan nem ajánlott megtenni, mivel sebezhetővé teszi az alkalmazást. Ehelyett a tanúsítványok hozzáadása a bizalmi tárolóhoz.

A megbízhatóság növelése érdekében aláírhatjuk az e-maileket a DKIM technológia segítségével:

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

DI szolgáltatások

Ezek a szolgáltatások hozzáadódnak a DI konténerhez:

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

Nette Documentation Preview

E-mailek küldése

Telepítés

E-mailek létrehozása

Csatolmányok

Sablonok

Használat a Nette alkalmazásban

E-mail küldése

SendmailMailer

SmtpMailer

FallbackMailer

DKIM

A konfigurálása.

DI szolgáltatások