Nette Documentation Preview

syntax 
Nette Mail
**********

<div class=perex>

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

</div>


Telepítés
=========

A könyvtárat a [Composer|best-practices:composer] segítségével töltheti le és telepítheti:

```shell
composer require nette/mail
```


E-mail létrehozása
==================

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

```php
$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:

```php
$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:

```php
$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:

```php
// 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?

.[tip]
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.

```php
// 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|latte:] sablonrendszerben írja meg őket. Hogyan csináljuk?

```php
$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:

```latte
<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 |dependency-injection:passing-dependencies] segítségével átadja magának:

```php
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.

```latte
<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 [api: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 |dependency-injection:passing-dependencies] segítségével átadja magának.


SendmailMailer
--------------

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

```php
$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 = '-fmy@email.com'` parancsot.


SmtpMailer
----------

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

```php
$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 "SSL context options":https://www.php.net/manual/en/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.

```php
$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 |#Konfiguráció]. Ha nem használ dependency injectiont, akkor így használatos:

```php
$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|bootstrap:].

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:

```neon
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 "adja hozzá a tanúsítványokat a tárolóhoz":https://www.php.net/manual/en/openssl.configuration.php.

A hitelesség növelése érdekében az e-maileket aláírhatjuk [DKIM technológiával |https://blog.nette.org/en/how-to-sign-emails-using-dkim]:

```neon
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`	  | [api:Nette\Mail\Mailer]   | [e-maileket küldő osztály |#E-mail küldése]
| `mail.signer`	  | [api:Nette\Mail\Signer]   | [DKIM aláírás |#DKIM]


{{leftbar: nette:@menu-topics}}

Nette Mail

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 = '-fmy@email.com' 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 SSL context options 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 adja hozzá a tanúsítványokat a tárolóhoz.

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