Nette Documentation Preview

syntax 
E-mailek küldése
****************

<div class=perex>

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

</div>


Telepítés .[#toc-installation]
==============================

Töltse le és telepítse a csomagot a [Composer |best-practices:composer] segítségével:

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


E-mailek létrehozása .[#toc-creating-emails]
============================================

Az e-mail egy [api:Nette\Mail\Message] objektum:

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

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

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

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


Csatolmányok .[#toc-attachments]
--------------------------------

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

```php
// 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 .[#toc-templates]
--------------------------

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

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

```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 .[#toc-using-in-nette-application]
------------------------------------------------------------------

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 |dependency-injection:passing-dependencies] történő átadással kapunk.

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

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


E-mail küldése .[#toc-sending-emails]
=====================================

A Mailer osztály felelős az e-mailek küldéséért. A [api: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ó |#Configuring] alapján a DI konténerhez, amit [függőségi injektálással |dependency-injection:passing-dependencies] átadva kapunk meg.


SendmailMailer .[#toc-sendmailmailer]
-------------------------------------

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

```php
$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 .[#toc-smtpmailer]
-----------------------------

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

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


FallbackMailer .[#toc-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.

```php
$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 .[#toc-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 |#Configuring] 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:

```php
$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. .[#toc-configuring]
=====================================

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

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:

```neon
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":https://www.php.net/manual/en/openssl.configuration.php.

A megbízhatóság növelése érdekében aláírhatjuk az e-maileket a [DKIM technológia |https://blog.nette.org/hu/e-mailek-alairasa-dkim-mel] segítségével:

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


DI szolgáltatások .[#toc-di-services]
=====================================

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

| Név | Típus | Leírás
|-----------------------------------------------------
| `mail.mailer`| [api:Nette\Mail\Mailer] | [e-mail küldési osztály |#Sending Emails]
| `mail.signer`| [api:Nette\Mail\Signer] | [DKIM aláírás |#DKIM]


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

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