Nette Documentation Preview

syntax 
Versenden von E-Mails
*********************

<div class=perex>

Wollen Sie E-Mails wie Newsletter oder Auftragsbestätigungen versenden? Nette Framework bietet die notwendigen Werkzeuge mit einer sehr schönen API. Wir werden es zeigen:

- wie man eine E-Mail erstellt, einschließlich Anhängen
- wie man sie versendet
- wie man E-Mails und Vorlagen kombiniert

</div>


Einrichtung .[#toc-installation]
================================

Laden Sie das Paket herunter und installieren Sie es mit [Composer |best-practices:composer]:

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


Emails erstellen .[#toc-creating-emails]
========================================

E-Mail ist ein [api:Nette\Mail\Message] Objekt:

```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.");
```

Alle Parameter müssen in UTF-8 kodiert sein.

Neben der Angabe von Empfängern mit der Methode `addTo()` können Sie auch den Empfänger einer Kopie mit `addCc()` oder den Empfänger einer Blindkopie mit `addBcc()` angeben. Alle diese Methoden, einschließlich `setFrom()`, akzeptieren den Adressaten auf drei Arten:

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

Der Textkörper einer in HTML geschriebenen E-Mail wird mit der Methode `setHtmlBody()` übergeben:

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

Sie müssen keine Textalternative erstellen, Nette generiert sie automatisch für Sie. Und wenn die E-Mail keinen Betreff hat, wird dieser aus dem `<title>` Element.

Auch Bilder lassen sich sehr einfach in den HTML-Text einer E-Mail einfügen. Übergeben Sie einfach den Pfad, in dem sich die Bilder physisch befinden, als zweiten Parameter, und Nette fügt sie automatisch in die E-Mail ein:

```php
// fügt automatisch /path/to/images/background.gif in die E-Mail ein
$mail->setHtmlBody(
	'<b>Hello</b> <img src="background.gif">',
	'/path/to/images',
);
```

Der Algorithmus zum Einbetten von Bildern unterstützt die folgenden Muster: `<img src=...>`, `<body background=...>`, `url(...)` innerhalb des HTML-Attributs `style` und die spezielle Syntax `[[...]]`.

Kann das Versenden von E-Mails noch einfacher sein?

E-Mails sind wie Postkarten. Senden Sie niemals Passwörter oder andere Anmeldeinformationen per E-Mail. .[tip]


Anhänge .[#toc-attachments]
---------------------------

Sie können natürlich auch Anhänge an E-Mails anhängen. Verwenden Sie dazu die `addAttachment(string $file, ?string $content = null, ?string $contentType = null)`.

```php
// fügt die Datei /path/to/example.zip in die E-Mail unter dem Namen example.zip ein
$mail->addAttachment('/path/to/example.zip');

// fügt die Datei /path/to/example.zip in die E-Mail mit dem Namen info.zip ein
$mail->addAttachment('info.zip', file_get_contents('/path/to/example.zip'));

// Hängt den Inhalt der neuen Datei example.txt an "Hello John!"
$mail->addAttachment('example.txt', 'Hello John!');
```


Schablonen .[#toc-templates]
----------------------------

Wenn Sie HTML-E-Mails versenden, ist es eine gute Idee, diese im [Latte-Vorlagensystem |latte:] zu schreiben. Wie man das macht?

```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',
	);
```

Datei `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>
```

Nette fügt automatisch alle Bilder ein, setzt den Betreff entsprechend dem `<title>` Element ein und erzeugt einen Alternativtext für den HTML-Body.


Verwendung in der Nette-Anwendung .[#toc-using-in-nette-application]
--------------------------------------------------------------------

Wenn Sie E-Mails zusammen mit Nette Application verwenden, z.B. Moderatoren, möchten Sie vielleicht Links in Vorlagen mit dem `n:href` Attribut oder dem `{link}` Tag erstellen. Latte kennt diese grundsätzlich nicht, aber es ist sehr einfach, sie hinzuzufügen. Das Erstellen von Links kann das Objekt `Nette\Application\LinkGenerator` tun, das Sie durch Übergabe mittels [Dependency Injection |dependency-injection:passing-dependencies] erhalten.

```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;
	}
}
```

In der Vorlage wird der Link wie in einer normalen Vorlage erstellt. Alle über LinkGenerator erstellten Links sind absolut:

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


Emails verschicken .[#toc-sending-emails]
=========================================

Mailer ist die Klasse, die für den Versand von E-Mails zuständig ist. Sie implementiert die Schnittstelle [api:Nette\Mail\Mailer] und es gibt mehrere fertige Mailer, die wir vorstellen werden.

Das Framework fügt dem DI-Container automatisch einen auf der [Konfiguration |#Configuring] basierenden `Nette\Mail\Mailer` -Dienst hinzu, den Sie durch Übergabe mittels [Dependency Injection |dependency-injection:passing-dependencies] erhalten.


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

Der Standard-Mailer ist SendmailMailer, der die PHP-Funktion [php:mail] verwendet. Beispiel für die Verwendung:

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

Wenn Sie `returnPath` setzen wollen und der Server es trotzdem überschreibt, verwenden Sie `$mailer->commandArgs = '-fmy@email.com'`.


SmtpMailer .[#toc-smtpmailer]
-----------------------------

Um E-Mails über den SMTP-Server zu versenden, verwenden Sie `SmtpMailer`.

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

Die folgenden zusätzlichen Parameter können an den Konstruktor übergeben werden:

* `port` - wenn nicht gesetzt, wird der Standardwert 25 oder 465 für `ssl` verwendet
* `timeout` - Timeout für SMTP-Verbindung
* `persistent` - persistente Verbindung verwenden
* `clientHost` - Client-Bezeichnung
* `streamOptions` - ermöglicht die Einstellung von "SSL-Kontextoptionen":https://www.php.net/manual/en/context.ssl.php für die Verbindung


FallbackMailer .[#toc-fallbackmailer]
-------------------------------------

Der FallbackMailer versendet keine E-Mails, sondern sendet sie über eine Reihe von Mailern. Wenn ein Mailer fehlschlägt, wiederholt er den Versuch beim nächsten Mailer. Wenn der letzte fehlschlägt, beginnt er wieder mit dem ersten.

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

Weitere Parameter im Konstruktor sind die Anzahl der Wiederholungen und die Wartezeit in Millisekunden.


DKIM .[#toc-dkim]
=================

DKIM (DomainKeys Identified Mail) ist eine vertrauenswürdige E-Mail-Technologie, die auch hilft, gefälschte Nachrichten zu erkennen. Die gesendete Nachricht wird mit dem privaten Schlüssel der Domäne des Absenders signiert, und diese Signatur wird in der Kopfzeile der E-Mail gespeichert.
Der Server des Empfängers vergleicht diese Signatur mit dem öffentlichen Schlüssel, der in den DNS-Einträgen der Domäne gespeichert ist. Durch den Abgleich der Signatur wird nachgewiesen, dass die E-Mail tatsächlich von der Domäne des Absenders stammt und dass die Nachricht während der Übertragung nicht verändert wurde.

Sie können den Mailer in der [Konfiguration |#Configuring] so einrichten, dass er E-Mails signiert. Wenn Sie die Dependency Injection nicht verwenden, wird sie wie folgt eingesetzt:

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

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


Konfigurieren von .[#toc-configuring]
=====================================

Überblick über die Konfigurationsmöglichkeiten für Nette Mail. Wenn Sie nicht das gesamte Framework, sondern nur diese Bibliothek verwenden, lesen Sie [, wie Sie die Konfiguration laden |bootstrap:].

Standardmäßig wird zum Versenden von E-Mails der Mailer `Nette\Mail\SendmailMailer` verwendet, der nicht weiter konfiguriert ist. Wir können ihn jedoch auf `Nette\Mail\SmtpMailer` umstellen:

```neon
mail:
	# SmtpMailer verwenden
	smtp: true       # (bool) ist standardmäßig auf false eingestellt

	host: ...        # (string)
	port: ...        # (int)
	username: ...    # (string)
	password: ...    # (Zeichenkette)
	timeout: ...     # (int)
	encryption: ...  # (ssl|tls|null) Standardwert ist null (hat den Alias 'secure')
	clientHost: ...  # (string) Standardwert ist $_SERVER['HTTP_HOST']
	persistent: ...  # (bool) Standardwert ist false

	# Kontext für die Verbindung zum SMTP-Server, Standardwert ist stream_context_get_default()
	context :
		ssl:         # alle Optionen unter https://www.php.net/manual/en/context.ssl.php
			allow_self_signed: ...
			...
		http:        # alle Optionen unter https://www.php.net/manual/en/context.http.php
			header: ...
			...
```

Sie können die Authentifizierung von SSL-Zertifikaten mit der Option `context › ssl › verify_peer: false` deaktivieren. Es wird **strengstens empfohlen**, dies nicht zu tun, da es die Anwendung angreifbar macht. Fügen Sie stattdessen "Zertifikate zum Vertrauensspeicher hinzu":https://www.php.net/manual/en/openssl.configuration.php.

Um die Vertrauenswürdigkeit zu erhöhen, können wir E-Mails mit der [DKIM-Technologie |https://blog.nette.org/de/e-mails-mit-dkim-signieren] signieren:

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


DI-Dienste .[#toc-di-services]
==============================

Diese Dienste werden dem DI-Container hinzugefügt:

| Name | Typ | Beschreibung
|-----------------------------------------------------
| `mail.mailer`| [api:Nette\Mail\Mailer] | [E-Mail-Versandklasse |#Sending Emails]
| `mail.signer`| [api:Nette\Mail\Signer] | [DKIM-Signierung |#DKIM]


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

Versenden von E-Mails

Wollen Sie E-Mails wie Newsletter oder Auftragsbestätigungen versenden? Nette Framework bietet die notwendigen Werkzeuge mit einer sehr schönen API. Wir werden es zeigen:

  • wie man eine E-Mail erstellt, einschließlich Anhängen
  • wie man sie versendet
  • wie man E-Mails und Vorlagen kombiniert

Einrichtung

Laden Sie das Paket herunter und installieren Sie es mit Composer:

composer require nette/mail

Emails erstellen

E-Mail ist ein Nette\Mail\Message Objekt:

$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.");

Alle Parameter müssen in UTF-8 kodiert sein.

Neben der Angabe von Empfängern mit der Methode addTo() können Sie auch den Empfänger einer Kopie mit addCc() oder den Empfänger einer Blindkopie mit addBcc() angeben. Alle diese Methoden, einschließlich setFrom(), akzeptieren den Adressaten auf drei Arten:

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

Der Textkörper einer in HTML geschriebenen E-Mail wird mit der Methode setHtmlBody() übergeben:

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

Sie müssen keine Textalternative erstellen, Nette generiert sie automatisch für Sie. Und wenn die E-Mail keinen Betreff hat, wird dieser aus dem <title> Element.

Auch Bilder lassen sich sehr einfach in den HTML-Text einer E-Mail einfügen. Übergeben Sie einfach den Pfad, in dem sich die Bilder physisch befinden, als zweiten Parameter, und Nette fügt sie automatisch in die E-Mail ein:

// fügt automatisch /path/to/images/background.gif in die E-Mail ein
$mail->setHtmlBody(
	'<b>Hello</b> <img src="background.gif">',
	'/path/to/images',
);

Der Algorithmus zum Einbetten von Bildern unterstützt die folgenden Muster: <img src=...>, <body background=...>, url(...) innerhalb des HTML-Attributs style und die spezielle Syntax [[...]].

Kann das Versenden von E-Mails noch einfacher sein?

E-Mails sind wie Postkarten. Senden Sie niemals Passwörter oder andere Anmeldeinformationen per E-Mail.

Anhänge

Sie können natürlich auch Anhänge an E-Mails anhängen. Verwenden Sie dazu die addAttachment(string $file, ?string $content = null, ?string $contentType = null).

// fügt die Datei /path/to/example.zip in die E-Mail unter dem Namen example.zip ein
$mail->addAttachment('/path/to/example.zip');

// fügt die Datei /path/to/example.zip in die E-Mail mit dem Namen info.zip ein
$mail->addAttachment('info.zip', file_get_contents('/path/to/example.zip'));

// Hängt den Inhalt der neuen Datei example.txt an "Hello John!"
$mail->addAttachment('example.txt', 'Hello John!');

Schablonen

Wenn Sie HTML-E-Mails versenden, ist es eine gute Idee, diese im Latte-Vorlagensystem zu schreiben. Wie man das macht?

$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',
	);

Datei 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>

Nette fügt automatisch alle Bilder ein, setzt den Betreff entsprechend dem <title> Element ein und erzeugt einen Alternativtext für den HTML-Body.

Verwendung in der Nette-Anwendung

Wenn Sie E-Mails zusammen mit Nette Application verwenden, z.B. Moderatoren, möchten Sie vielleicht Links in Vorlagen mit dem n:href Attribut oder dem {link} Tag erstellen. Latte kennt diese grundsätzlich nicht, aber es ist sehr einfach, sie hinzuzufügen. Das Erstellen von Links kann das Objekt Nette\Application\LinkGenerator tun, das Sie durch Übergabe mittels Dependency Injection erhalten.

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;
	}
}

In der Vorlage wird der Link wie in einer normalen Vorlage erstellt. Alle über LinkGenerator erstellten Links sind absolut:

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

Emails verschicken

Mailer ist die Klasse, die für den Versand von E-Mails zuständig ist. Sie implementiert die Schnittstelle Nette\Mail\Mailer und es gibt mehrere fertige Mailer, die wir vorstellen werden.

Das Framework fügt dem DI-Container automatisch einen auf der Konfiguration basierenden Nette\Mail\Mailer -Dienst hinzu, den Sie durch Übergabe mittels Dependency Injection erhalten.

SendmailMailer

Der Standard-Mailer ist SendmailMailer, der die PHP-Funktion mail verwendet. Beispiel für die Verwendung:

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

Wenn Sie returnPath setzen wollen und der Server es trotzdem überschreibt, verwenden Sie $mailer->commandArgs = '-fmy@email.com'.

SmtpMailer

Um E-Mails über den SMTP-Server zu versenden, verwenden Sie SmtpMailer.

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

Die folgenden zusätzlichen Parameter können an den Konstruktor übergeben werden:

  • port – wenn nicht gesetzt, wird der Standardwert 25 oder 465 für ssl verwendet
  • timeout – Timeout für SMTP-Verbindung
  • persistent – persistente Verbindung verwenden
  • clientHost – Client-Bezeichnung
  • streamOptions – ermöglicht die Einstellung von SSL-Kontextoptionen für die Verbindung

FallbackMailer

Der FallbackMailer versendet keine E-Mails, sondern sendet sie über eine Reihe von Mailern. Wenn ein Mailer fehlschlägt, wiederholt er den Versuch beim nächsten Mailer. Wenn der letzte fehlschlägt, beginnt er wieder mit dem ersten.

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

Weitere Parameter im Konstruktor sind die Anzahl der Wiederholungen und die Wartezeit in Millisekunden.

DKIM

DKIM (DomainKeys Identified Mail) ist eine vertrauenswürdige E-Mail-Technologie, die auch hilft, gefälschte Nachrichten zu erkennen. Die gesendete Nachricht wird mit dem privaten Schlüssel der Domäne des Absenders signiert, und diese Signatur wird in der Kopfzeile der E-Mail gespeichert. Der Server des Empfängers vergleicht diese Signatur mit dem öffentlichen Schlüssel, der in den DNS-Einträgen der Domäne gespeichert ist. Durch den Abgleich der Signatur wird nachgewiesen, dass die E-Mail tatsächlich von der Domäne des Absenders stammt und dass die Nachricht während der Übertragung nicht verändert wurde.

Sie können den Mailer in der Konfiguration so einrichten, dass er E-Mails signiert. Wenn Sie die Dependency Injection nicht verwenden, wird sie wie folgt eingesetzt:

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

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

Konfigurieren von

Überblick über die Konfigurationsmöglichkeiten für Nette Mail. Wenn Sie nicht das gesamte Framework, sondern nur diese Bibliothek verwenden, lesen Sie , wie Sie die Konfiguration laden.

Standardmäßig wird zum Versenden von E-Mails der Mailer Nette\Mail\SendmailMailer verwendet, der nicht weiter konfiguriert ist. Wir können ihn jedoch auf Nette\Mail\SmtpMailer umstellen:

mail:
	# SmtpMailer verwenden
	smtp: true       # (bool) ist standardmäßig auf false eingestellt

	host: ...        # (string)
	port: ...        # (int)
	username: ...    # (string)
	password: ...    # (Zeichenkette)
	timeout: ...     # (int)
	encryption: ...  # (ssl|tls|null) Standardwert ist null (hat den Alias 'secure')
	clientHost: ...  # (string) Standardwert ist $_SERVER['HTTP_HOST']
	persistent: ...  # (bool) Standardwert ist false

	# Kontext für die Verbindung zum SMTP-Server, Standardwert ist stream_context_get_default()
	context :
		ssl:         # alle Optionen unter https://www.php.net/manual/en/context.ssl.php
			allow_self_signed: ...
			...
		http:        # alle Optionen unter https://www.php.net/manual/en/context.http.php
			header: ...
			...

Sie können die Authentifizierung von SSL-Zertifikaten mit der Option context › ssl › verify_peer: false deaktivieren. Es wird strengstens empfohlen, dies nicht zu tun, da es die Anwendung angreifbar macht. Fügen Sie stattdessen Zertifikate zum Vertrauensspeicher hinzu.

Um die Vertrauenswürdigkeit zu erhöhen, können wir E-Mails mit der DKIM-Technologie signieren:

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

DI-Dienste

Diese Dienste werden dem DI-Container hinzugefügt:

Name Typ Beschreibung
mail.mailer Nette\Mail\Mailer E-Mail-Versandklasse
mail.signer Nette\Mail\Signer DKIM-Signierung