Nette Documentation Preview

syntax 
Trimiterea de e-mailuri
***********************

<div class=perex>

Aveți de gând să trimiteți e-mailuri, cum ar fi buletine informative sau confirmări de comenzi? Nette Framework oferă instrumentele necesare cu un API foarte bun. Vom arăta:

- cum să creați un e-mail, inclusiv atașamente
- cum să îl trimiteți
- cum să combinați e-mailurile și șabloanele

</div>


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

Descărcați și instalați pachetul folosind [Composer |best-practices:composer]:

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


Crearea de e-mailuri .[#toc-creating-emails]
============================================

E-mailul este un obiect [api:Nette\Mail\Message]:

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

Toți parametrii trebuie să fie codificați în UTF-8.

Pe lângă specificarea destinatarilor cu metoda `addTo()`, puteți specifica și destinatarul copiei cu `addCc()`, sau destinatarul copiei oarbe cu `addBcc()`. Toate aceste metode, inclusiv `setFrom()`, acceptă destinatarii în trei moduri:

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

Corpul unui e-mail scris în HTML este transmis cu ajutorul metodei `setHtmlBody()`:

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

Nu trebuie să creați o alternativă de text, Nette o va genera automat pentru dumneavoastră. Iar dacă e-mailul nu are un subiect setat, acesta va fi preluat din fișierul `<title>` element.

Imaginile pot fi, de asemenea, extrem de ușor de inserat în corpul HTML al unui e-mail. Trebuie doar să treceți ca al doilea parametru calea în care se află fizic imaginile, iar Nette le va include automat în e-mail:

```php
// adaugă automat /path/to/images/background.gif la e-mail
$mail->setHtmlBody(
	'<b>Hello</b> <img src="background.gif">',
	'/path/to/images',
);
```

Algoritmul de încorporare a imaginilor acceptă următoarele modele: `<img src=...>`, `<body background=...>`, `url(...)` în interiorul atributului HTML `style` și sintaxa specială `[[...]]`.

Poate trimiterea de e-mailuri să fie și mai ușoară?

E-mailurile sunt ca niște cărți poștale. Nu trimiteți niciodată parole sau alte credențiale prin e-mail. .[tip]


Atașamente .[#toc-attachments]
------------------------------

Puteți, desigur, să atașați atașamente la e-mail. Folosiți opțiunea `addAttachment(string $file, string $content = null, string $contentType = null)`.

```php
// inserează fișierul /path/to/example.zip în e-mail sub numele example.zip
$mail->addAttachment('/path/to/example.zip');

// inserează fișierul /path/to/example.zip în e-mail sub numele info.zip
$mail->addAttachment('info.zip', file_get_contents('/path/to/example.zip'));

// atașează noul conținut al fișierului example.txt "Hello John!"
$mail->addAttachment('example.txt', 'Hello John!');
```


Șabloane .[#toc-templates]
--------------------------

Dacă trimiteți e-mailuri HTML, este o idee excelentă să le scrieți în sistemul de șabloane [Latte |latte:]. Cum să o faceți?

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

Fișier `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 inserează automat toate imaginile, stabilește subiectul în funcție de `<title>` element, și generează o alternativă de text pentru corpul HTML.


Utilizare în aplicația Nette .[#toc-using-in-nette-application]
---------------------------------------------------------------

Dacă utilizați e-mailuri împreună cu Nette Application, adică prezentatori, este posibil să doriți să creați legături în șabloane utilizând atributul `n:href` sau eticheta `{link}`. Practic, Latte nu le cunoaște, dar este foarte ușor să le adăugați. Crearea de link-uri poate face obiectul `Nette\Application\LinkGenerator`, pe care îl obțineți prin trecerea acestuia folosind [injecția de dependență |dependency-injection:passing-dependencies].

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

În șablon, legătura este creată ca într-un șablon normal. Toate legăturile create prin intermediul LinkGenerator sunt absolute:

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


Trimiterea de e-mailuri .[#toc-sending-emails]
==============================================

Mailer este clasa responsabilă pentru trimiterea de e-mailuri. Ea implementează interfața [api:Nette\Mail\Mailer] și sunt disponibile mai multe clase de maileri gata făcute, pe care le vom prezenta.

Cadrul de lucru adaugă automat un serviciu `Nette\Mail\Mailer` bazat pe [configurație |#Configuring] la containerul DI, pe care îl obțineți trecându-l folosind [injecția de dependență |dependency-injection:passing-dependencies].


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

Mailerul implicit este SendmailMailer care folosește funcția PHP [php:mail]. Exemplu de utilizare:

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

Dacă doriți să setați `returnPath` și serverul încă îl suprascrie, utilizați `$mailer->commandArgs = '-fmy@email.com'`.


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

Pentru a trimite mesaje prin intermediul serverului SMTP, utilizați `SmtpMailer`.

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

Următorii parametri suplimentari pot fi trecuți în constructor:

* `port` - dacă nu este setat, se va utiliza valoarea implicită 25 sau 465 pentru `ssl`
* `timeout` - timeout pentru conexiunea SMTP
* `persistent` - utilizează o conexiune persistentă
* `clientHost` - desemnarea clientului
* `streamOptions` - vă permite să setați "SSL context options":https://www.php.net/manual/en/context.ssl.php pentru conexiune


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

Nu trimite e-mailuri, ci le trimite prin intermediul unui set de expeditori. În cazul în care un maililer eșuează, repetă încercarea la următorul. Dacă ultimul eșuează, o ia de la capăt de la primul.

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

Alți parametri din constructor includ numărul de repetări și timpul de așteptare în milisecunde.


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

DKIM (DomainKeys Identified Mail) este o tehnologie de e-mail de încredere care ajută la detectarea mesajelor false. Mesajul trimis este semnat cu cheia privată a domeniului expeditorului, iar această semnătură este stocată în antetul e-mailului.
Serverul destinatarului compară această semnătură cu cheia publică stocată în înregistrările DNS ale domeniului. Prin compararea semnăturii, se demonstrează că mesajul electronic provine de fapt din domeniul expeditorului și că mesajul nu a fost modificat în timpul transmiterii acestuia.

Puteți seta mailer pentru a semna e-mailurile în [configurare |#Configuring]. Dacă nu utilizați injecția de dependență, aceasta este utilizată după cum urmează:

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

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


Configurarea .[#toc-configuring]
================================

Prezentare generală a opțiunilor de configurare pentru Nette Mail. Dacă nu utilizați întregul cadru, ci doar această bibliotecă, citiți [cum se încarcă configurația |bootstrap:].

În mod implicit, pentru trimiterea de e-mailuri se utilizează aplicația de poștă electronică `Nette\Mail\SendmailMailer`, care nu este configurată suplimentar. Cu toate acestea, îl putem comuta la `Nette\Mail\SmtpMailer`:

```neon
mail:
	# utilizați SmtpMailer
	smtp: true       # (bool) valoarea implicită este false

	host: ...        # (string)
	port: ...        # (int)
	username: ...    # (string)
	password: ...    # (string)
	timeout: ...     # (int)
	encryption: ...  # (ssl|tls|null) valoarea implicită este null (are aliasul "secure")
	clientHost: ...  # (string) valoarea implicită este $_SERVER['HTTP_HOST']]
	persistent: ...  # (bool) valoarea implicită este false

	# context pentru conectarea la serverul SMTP, valoarea implicită este stream_context_get_default()
	context:
		ssl:         # toate opțiunile la https://www.php.net/manual/en/context.ssl.php
			allow_self_signed: ...
			...
		http:        # toate opțiunile la https://www.php.net/manual/en/context.http.php
			header: ...
			...
```

Puteți dezactiva autentificarea certificatului SSL folosind opțiunea `context › ssl › verify_peer: false`. Se **recomandă cu tărie să nu faceți** acest lucru, deoarece va face aplicația vulnerabilă. În schimb, "add certificates to trust store":https://www.php.net/manual/en/openssl.configuration.php.

Pentru a crește gradul de încredere, putem semna e-mailurile folosind [tehnologia DKIM |https://blog.nette.org/ro/semnati-e-mailurile-cu-dkim]:

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


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

Aceste servicii sunt adăugate la containerul DI:

Nume | Tip | Tip | Descriere
|-----------------------------------------------------
| `mail.mailer`| [api:Nette\Mail\Mailer] | [Clasa de trimitere de e-mail |#Sending Emails]
| `mail.signer`| [api:Nette\Mail\Signer] | [Semnarea DKIM |#DKIM]


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

Trimiterea de e-mailuri

Aveți de gând să trimiteți e-mailuri, cum ar fi buletine informative sau confirmări de comenzi? Nette Framework oferă instrumentele necesare cu un API foarte bun. Vom arăta:

  • cum să creați un e-mail, inclusiv atașamente
  • cum să îl trimiteți
  • cum să combinați e-mailurile și șabloanele

Instalare

Descărcați și instalați pachetul folosind Composer:

composer require nette/mail

Crearea de e-mailuri

E-mailul este un obiect Nette\Mail\Message:

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

Toți parametrii trebuie să fie codificați în UTF-8.

Pe lângă specificarea destinatarilor cu metoda addTo(), puteți specifica și destinatarul copiei cu addCc(), sau destinatarul copiei oarbe cu addBcc(). Toate aceste metode, inclusiv setFrom(), acceptă destinatarii în trei moduri:

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

Corpul unui e-mail scris în HTML este transmis cu ajutorul metodei setHtmlBody():

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

Nu trebuie să creați o alternativă de text, Nette o va genera automat pentru dumneavoastră. Iar dacă e-mailul nu are un subiect setat, acesta va fi preluat din fișierul <title> element.

Imaginile pot fi, de asemenea, extrem de ușor de inserat în corpul HTML al unui e-mail. Trebuie doar să treceți ca al doilea parametru calea în care se află fizic imaginile, iar Nette le va include automat în e-mail:

// adaugă automat /path/to/images/background.gif la e-mail
$mail->setHtmlBody(
	'<b>Hello</b> <img src="background.gif">',
	'/path/to/images',
);

Algoritmul de încorporare a imaginilor acceptă următoarele modele: <img src=...>, <body background=...>, url(...) în interiorul atributului HTML style și sintaxa specială [[...]].

Poate trimiterea de e-mailuri să fie și mai ușoară?

E-mailurile sunt ca niște cărți poștale. Nu trimiteți niciodată parole sau alte credențiale prin e-mail.

Atașamente

Puteți, desigur, să atașați atașamente la e-mail. Folosiți opțiunea addAttachment(string $file, string $content = null, string $contentType = null).

// inserează fișierul /path/to/example.zip în e-mail sub numele example.zip
$mail->addAttachment('/path/to/example.zip');

// inserează fișierul /path/to/example.zip în e-mail sub numele info.zip
$mail->addAttachment('info.zip', file_get_contents('/path/to/example.zip'));

// atașează noul conținut al fișierului example.txt "Hello John!"
$mail->addAttachment('example.txt', 'Hello John!');

Șabloane

Dacă trimiteți e-mailuri HTML, este o idee excelentă să le scrieți în sistemul de șabloane Latte. Cum să o faceți?

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

Fișier 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 inserează automat toate imaginile, stabilește subiectul în funcție de <title> element, și generează o alternativă de text pentru corpul HTML.

Utilizare în aplicația Nette

Dacă utilizați e-mailuri împreună cu Nette Application, adică prezentatori, este posibil să doriți să creați legături în șabloane utilizând atributul n:href sau eticheta {link}. Practic, Latte nu le cunoaște, dar este foarte ușor să le adăugați. Crearea de link-uri poate face obiectul Nette\Application\LinkGenerator, pe care îl obțineți prin trecerea acestuia folosind injecția de dependență.

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

În șablon, legătura este creată ca într-un șablon normal. Toate legăturile create prin intermediul LinkGenerator sunt absolute:

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

Trimiterea de e-mailuri

Mailer este clasa responsabilă pentru trimiterea de e-mailuri. Ea implementează interfața Nette\Mail\Mailer și sunt disponibile mai multe clase de maileri gata făcute, pe care le vom prezenta.

Cadrul de lucru adaugă automat un serviciu Nette\Mail\Mailer bazat pe configurație la containerul DI, pe care îl obțineți trecându-l folosind injecția de dependență.

SendmailMailer

Mailerul implicit este SendmailMailer care folosește funcția PHP mail. Exemplu de utilizare:

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

Dacă doriți să setați returnPath și serverul încă îl suprascrie, utilizați $mailer->commandArgs = '-fmy@email.com'.

SmtpMailer

Pentru a trimite mesaje prin intermediul serverului SMTP, utilizați SmtpMailer.

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

Următorii parametri suplimentari pot fi trecuți în constructor:

  • port – dacă nu este setat, se va utiliza valoarea implicită 25 sau 465 pentru ssl
  • timeout – timeout pentru conexiunea SMTP
  • persistent – utilizează o conexiune persistentă
  • clientHost – desemnarea clientului
  • streamOptions – vă permite să setați SSL context options pentru conexiune

FallbackMailer

Nu trimite e-mailuri, ci le trimite prin intermediul unui set de expeditori. În cazul în care un maililer eșuează, repetă încercarea la următorul. Dacă ultimul eșuează, o ia de la capăt de la primul.

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

Alți parametri din constructor includ numărul de repetări și timpul de așteptare în milisecunde.

DKIM

DKIM (DomainKeys Identified Mail) este o tehnologie de e-mail de încredere care ajută la detectarea mesajelor false. Mesajul trimis este semnat cu cheia privată a domeniului expeditorului, iar această semnătură este stocată în antetul e-mailului. Serverul destinatarului compară această semnătură cu cheia publică stocată în înregistrările DNS ale domeniului. Prin compararea semnăturii, se demonstrează că mesajul electronic provine de fapt din domeniul expeditorului și că mesajul nu a fost modificat în timpul transmiterii acestuia.

Puteți seta mailer pentru a semna e-mailurile în configurare. Dacă nu utilizați injecția de dependență, aceasta este utilizată după cum urmează:

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

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

Configurarea

Prezentare generală a opțiunilor de configurare pentru Nette Mail. Dacă nu utilizați întregul cadru, ci doar această bibliotecă, citiți cum se încarcă configurația.

În mod implicit, pentru trimiterea de e-mailuri se utilizează aplicația de poștă electronică Nette\Mail\SendmailMailer, care nu este configurată suplimentar. Cu toate acestea, îl putem comuta la Nette\Mail\SmtpMailer:

mail:
	# utilizați SmtpMailer
	smtp: true       # (bool) valoarea implicită este false

	host: ...        # (string)
	port: ...        # (int)
	username: ...    # (string)
	password: ...    # (string)
	timeout: ...     # (int)
	encryption: ...  # (ssl|tls|null) valoarea implicită este null (are aliasul "secure")
	clientHost: ...  # (string) valoarea implicită este $_SERVER['HTTP_HOST']]
	persistent: ...  # (bool) valoarea implicită este false

	# context pentru conectarea la serverul SMTP, valoarea implicită este stream_context_get_default()
	context:
		ssl:         # toate opțiunile la https://www.php.net/manual/en/context.ssl.php
			allow_self_signed: ...
			...
		http:        # toate opțiunile la https://www.php.net/manual/en/context.http.php
			header: ...
			...

Puteți dezactiva autentificarea certificatului SSL folosind opțiunea context › ssl › verify_peer: false. Se recomandă cu tărie să nu faceți acest lucru, deoarece va face aplicația vulnerabilă. În schimb, add certificates to trust store.

Pentru a crește gradul de încredere, putem semna e-mailurile folosind tehnologia DKIM:

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

Servicii DI

Aceste servicii sunt adăugate la containerul DI:

Nume | Tip | Tip | Descriere

mail.mailer Nette\Mail\Mailer Clasa de trimitere de e-mail
mail.signer Nette\Mail\Signer Semnarea DKIM