Nette Documentation Preview

Odesílání e-mailů

Chystáte se odesílat e-maily, například newslettery nebo potvrzení objednávek? Nette Framework poskytuje potřebné nástroje s velmi příjemným API. Ukážeme si:

  • jak e-mail vytvořit včetně příloh
  • jak ho odeslat
  • jak spojit e-maily a šablony

Instalace:

composer require nette/mail

Vytvoření e-mailu

E-mail je objektem třídy Nette\Mail\Message:

use Nette\Mail\Message;

$mail = new Message;
$mail->setFrom('Franta <franta@example.com>')
	->addTo('petr@example.com')
	->addTo('jirka@example.com')
	->setSubject('Potvrzení objednávky')
	->setBody("Dobrý den,\nvaše objednávka byla přijata.");

Všechny zadávané parametry musí být v UTF-8.

Kromě uvedení příjemce metodou addTo() lze uvést i příjemce kopie addCc(), nebo příjemce skryté kopie addBcc(). Ve všech těchto metodách včetně setFrom() můžeme adresáta zapsat třemi způsoby:

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

Tělo emailu v HTML se nastavuje metodou setHtmlBody().

$mail->setHtmlBody('<b>Sample HTML</b> <img src="background.gif">');

Pokud HTML email nemá textovou alternativu, bude vygenerována automaticky. A pokud HTML email nemá nastavený subjekt, bude vzat z elementu <title>.

Nikdy neposílejte e-mailem hesla ani jiné přístupové údaje.

Vložené obrázky (embedded)

Vložené obrázky lze do emailu vkládat metodou $mail->addEmbeddedFile('background.gif'), nicméně není to potřeba. Proč? Protože Nette Framework sám vyhledá a vloží všechny soubory odkazované v HTML kódu (pouze relativní cesty). Toto chování lze vypnout uvedením false jakožto druhého parametru metody setHtmlBody(), v tomto parametru je též možno předat absolutní cestu ke složce s obrázky.

Přílohy

Do e-mailu lze samozřejmě vkládat i přílohy. Slouží k tomu metoda addAttachment():

// vloží do e-mailu soubor example.zip
$mail->addAttachment('path/to/example.zip');

// vloží do e-mailu soubor example.txt s textem "Hello John!"
$mail->addAttachment('example.txt', 'Hello John!');

// vloží do e-mailu soubor example.zip pojmenovaný info.zip
$mail->addAttachment('info.zip', file_get_contents('path/to/example.zip'));

Může být odesílání e-mailů ještě jednodušší?

Šablony

Skutečná síla se projeví při zkombinování se šablonovacím systémem Latte:

$latte = new Latte\Engine;
$params = array(
	'orderId' => 123,
);

$mail = new Message;
$mail->setFrom('Franta <franta@example.com>')
	->addTo('petr@example.com')
	->setHtmlBody($latte->renderToString('email.latte', $params));

Soubor email.latte:

<html>
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
	<title>Potvrzení objednávky</title>
	<style>
	body {
		background: url("background.png")
	}
	</style>
</head>
<body>
	<p>Dobrý den,</p>

	<p>Vaše objednávka číslo {$orderId} byla přijata.</p>
</body>
</html>

Tvorba odkazů

Samotné šablony nepodporují makro {link}. Pokud ho chceme používat, můžeme si šablonu nechat vytvořit v presenteru nebo komponentě příkazem $template = $this->createTemplate()->setFile('email.latte') a tu předat do setHtmlBody(). Poté budeme v šabloně moci generovat odkazy.

use Nette;

class MyPresenter
{
	public function actionFoo()
	{
		$template = $this->createTemplate()->setFile('email.latte');
		$mail = new Message();
		$mail->setHtmlBody($template);
	}
}

Druhou možností je makro do šablony zaregistrovat ručně. Protože k vytváření odkazů je potřeba presenter, musíme ho předat jako parametr šabloně.

use Nette;
use Nette\Bridges\ApplicationLatte\UIMacros;

function createMessage(Nette\Application\Application $application)

	/** @var Nette\Application\IPresenter */
	$presenter = $application->getPresenter();

	$latte = new Latte\Engine;
	$params = array(
		'orderId' => 123,
		'_presenter' => $presenter, // kvůli makru {plink}
		'_control' => $presenter    // kvůli makru {link}
	);

	UIMacros::install($latte->getCompiler()); // Kromě jiných zaregistruje makro link a plink

	// ...
}

V šabloně pak odkaz vytvoříme pomocí makra {link} tak, jak jsme zvyklí. Použijeme absolutní adresu, aby odkaz vždy směřoval na správnou doménu:

<a href="{link //Presenter:action}">Odkaz</a>

Odeslání e-mailu

Mailer je třída zajišťující odesílání e-mailů. Implementuje rozhraní Nette\Mail\IMailer a k dispozici je několik předpřipravených mailerů.

Příklad použití:

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

Framework automaticky přidává do DI kontejneru službu typu Nette\Mail\IMailer sestavenou na základě konfigurace, ke které se dostanete tak, že si ji necháte předat pomocí dependency injection.

SendmailMailer

Výchozí mailer je SendmailMailer, který používá PHP funkci mail.

Pokud chcete nastavit returnPath a server vám ho pořád přepisuje, použijte $commandArgs.

$mailer->commandArgs = '-fMuj@email.cz';

SmtpMailer

K odeslání pošty přes SMTP server slouží SmtpMailer.

$mailer = new Nette\Mail\SmtpMailer(array(
	'host' => 'smtp.gmail.com', //  pokud není nastaven, použijí se hodnoty z php.ini
	'username' => 'franta@gmail.com',
	'password' => '*****',
	'secure' => 'ssl',
));
$mailer->send($mail);

Kromě nastavení výše, SmtpMailer nabízí další klíče pro přizpůsobení:

  • port – Pokud není nastaven, určí se podle klíče secure: 465 pro hodnotu ssl, jinak 25.
  • timeout – Timeout pro SMTP spojení
  • persistent – Použít persistent spojení