Nette Documentation Preview

syntax 
E-posta Gönderme
****************

<div class=perex>

Haber bültenleri veya sipariş onayları gibi e-postalar mı göndereceksiniz? Nette Framework çok güzel bir API ile gerekli araçları sağlar. Biz göstereceğiz:

- ekler de dahil olmak üzere bir e-posta nasıl oluşturulur
- nasıl gönderilir
- e-postalar ve şablonlar nasıl birleştirilir

</div>


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

[Composer'ı |best-practices:composer] kullanarak paketi indirin ve yükleyin:

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


E-posta Oluşturma .[#toc-creating-emails]
=========================================

E-posta bir [api:Nette\Mail\Message] nesnesidir:

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

Tüm parametreler UTF-8 olarak kodlanmalıdır.

Alıcıları `addTo()` yöntemiyle belirtmenin yanı sıra, `addCc()` ile kopyanın alıcısını veya `addBcc()` ile kör kopyanın alıcısını da belirtebilirsiniz. `setFrom()` dahil olmak üzere tüm bu yöntemler muhatabı üç şekilde kabul eder:

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

HTML ile yazılmış bir e-postanın gövdesi `setHtmlBody()` yöntemi kullanılarak aktarılır:

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

Metin alternatifi oluşturmak zorunda değilsiniz, Nette bunu sizin için otomatik olarak oluşturacaktır. Ve eğer e-postanın belirlenmiş bir konusu yoksa, konu `<title>` element.

Görüntüler ayrıca bir e-postanın HTML gövdesine son derece kolay bir şekilde eklenebilir. Görüntülerin fiziksel olarak bulunduğu yolu ikinci parametre olarak geçmeniz yeterlidir; Nette bunları otomatik olarak e-postaya dahil edecektir:

```php
// e-postaya otomatik olarak /path/to/images/background.gif ekler
$mail->setHtmlBody(
	'<b>Merhaba</b> <img src="background.gif">',
	'/path/to/images',
);
```

Görüntü gömme algoritması aşağıdaki kalıpları destekler: `<img src=...>`, `<body background=...>`, `url(...)` HTML özniteliğinin içinde `style` ve özel sözdizimi `[[...]]`.

E-posta göndermek daha da kolay olabilir mi?

E-postalar kartpostal gibidir. Parolaları veya diğer kimlik bilgilerini asla e-posta yoluyla göndermeyin. .[tip]


Ekler .[#toc-attachments]
-------------------------

Elbette e-postaya ekler de ekleyebilirsiniz. `addAttachment(string $file, ?string $content = null, ?string $contentType = null)` adresini kullanın.

```php
// /path/to/example.zip dosyasını example.zip adı altında e-postaya ekler
$mail->addAttachment('/path/to/example.zip');

// /path/to/example.zip dosyasını info.zip adı altında e-postaya ekler
$mail->addAttachment('info.zip', file_get_contents('/path/to/example.zip'));

// yeni example.txt dosya içeriğini ekler "Merhaba John!"
$mail->addAttachment('example.txt', 'Merhaba John!');
```


Şablonlar .[#toc-templates]
---------------------------

HTML e-postaları gönderiyorsanız, bunları [Latte |latte:] şablon sisteminde yazmak harika bir fikirdir. Nasıl Yapılır?

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

Dosya `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 tüm görüntüleri otomatik olarak ekler, konuyu `<title>` öğesine dönüştürür ve HTML gövdesi için metin alternatifi oluşturur.


Nette Uygulamasında Kullanım .[#toc-using-in-nette-application]
---------------------------------------------------------------

Nette Uygulaması ile birlikte e-posta kullanıyorsanız, yani sunum yapıyorsanız, `n:href` özniteliğini veya `{link}` etiketini kullanarak şablonlarda bağlantılar oluşturmak isteyebilirsiniz. Latte temelde bunları bilmez, ancak bunları eklemek çok kolaydır. Bağlantılar oluşturmak, [bağımlılık enjeksiyonu |dependency-injection:passing-dependencies] kullanarak geçirerek elde ettiğiniz nesne `Nette\Application\LinkGenerator` yapabilir.

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

Şablonda, normal bir şablonda olduğu gibi bağlantı oluşturulur. LinkGenerator üzerinden oluşturulan tüm linkler mutlaktır:

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


E-posta Gönderme .[#toc-sending-emails]
=======================================

Mailer, e-posta göndermekten sorumlu sınıftır. [api:Nette\Mail\Mailer] arayüzünü uygular ve tanıtacağımız birkaç hazır mailer mevcuttur.

Çerçeve, DI konteynerine [yapılandırmaya |#Configuring] dayalı olarak otomatik olarak bir `Nette\Mail\Mailer` hizmeti ekler; bu hizmeti [bağımlılık enjeksiyonu |dependency-injection:passing-dependencies] kullanarak geçirirsiniz.


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

Varsayılan posta göndericisi, [php:mail] PHP işlevini kullanan SendmailMailer'dir. Kullanım örneği:

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

Eğer `returnPath` adresini ayarlamak istiyorsanız ve sunucu hala üzerine yazıyorsa, `$mailer->commandArgs = '-fmy@email.com'` adresini kullanın.


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

SMTP sunucusu üzerinden posta göndermek için `SmtpMailer` adresini kullanın.

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

Aşağıdaki ek parametreler kurucuya aktarılabilir:

* `port` - ayarlanmamışsa, `ssl` için varsayılan 25 veya 465 kullanılacaktır
* `timeout` - SMTP bağlantısı için zaman aşımı
* `persistent` - kalıcı bağlantı kullanın
* `clientHost` - müşteri tanımı
* `streamOptions` - bağlantı için "SSL bağlam seçeneklerini":https://www.php.net/manual/en/context.ssl.php ayarlamanızı sağlar


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

E-posta göndermez, ancak bunları bir dizi postacı aracılığıyla gönderir. Bir postacı başarısız olursa, bir sonraki denemeyi tekrarlar. Sonuncusu başarısız olursa, ilkinden yeniden başlar.

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

Yapıcıdaki diğer parametreler tekrar sayısını ve milisaniye cinsinden bekleme süresini içerir.


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

DKIM (DomainKeys Identified Mail), sahte mesajların tespit edilmesine de yardımcı olan güvenilir bir e-posta teknolojisidir. Gönderilen mesaj, gönderenin etki alanının özel anahtarı ile imzalanır ve bu imza e-posta başlığında saklanır.
Alıcının sunucusu bu imzayı alan adının DNS kayıtlarında saklanan açık anahtarla karşılaştırır. İmzanın eşleştirilmesiyle, e-postanın gerçekten gönderenin etki alanından kaynaklandığı ve mesajın iletimi sırasında değiştirilmediği gösterilir.

[Yapılandırmada |#Configuring] e-postayı imzalamak için mailer'ı ayarlayabilirsiniz. Eğer dependency injection kullanmıyorsanız aşağıdaki gibi kullanılır:

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


Yapılandırma .[#toc-configuring]
================================

Nette Mail için yapılandırma seçeneklerine genel bakış. Tüm çerçeveyi değil, yalnızca bu kütüphaneyi kullanıyorsanız, [yapılandırmayı nasıl yükleyeceğinizi |bootstrap:] okuyun.

Varsayılan olarak, e-posta göndermek için `Nette\Mail\SendmailMailer` mailer kullanılır ve daha fazla yapılandırılmaz. Ancak, bunu `Nette\Mail\SmtpMailer` olarak değiştirebiliriz:

```neon
mail:
	# use SmtpMailer
	smtp: true       # (bool) varsayılan değer false

	host: ...        # (string)
	port: ...        # (int)
	username: ...    # (string)
	password: ...    # (string)
	timeout: ...     # (int)
	encryption: ...  # (ssl|tls|null) varsayılan olarak null ('secure' takma adına sahiptir)
	clientHost: ...  # (string) varsayılan olarak $_SERVER['HTTP_HOST']
	persistent: ...  # (bool) varsayılan değer false

	# SMTP sunucusuna bağlanmak için bağlam, varsayılan olarak stream_context_get_default()
	context:
		ssl:         # https://www.php.net/manual/en/context.ssl.php adresindeki tüm seçenekler
			allow_self_signed: ...
			...
		http:        # tüm seçenekler https://www.php.net/manual/en/context.http.php adresinde
			header: ...
			...
```

`context › ssl › verify_peer: false` seçeneğini kullanarak SSL sertifikası kimlik doğrulamasını devre dışı bırakabilirsiniz. Uygulamayı savunmasız hale getireceği için bunu yapmamanız **şiddetle tavsiye edilir**. Bunun yerine, "sertifikaları güven deposuna ekle":https://www.php.net/manual/en/openssl.configuration.php.

Güvenilirliği artırmak için [DKIM teknolojisini |https://blog.nette.org/tr/e-postalari-dkim-ile-imzalayin] kullanarak e-postaları imzalayabiliriz:

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


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

Bu hizmetler DI konteynerine eklenir:

| Ad | Tür | Açıklama
|-----------------------------------------------------
| `mail.mailer`| [api:Nette\Mail\Mailer] | [e-posta gönderme sınıfı |#Sending Emails]
| `mail.signer`| [api:Nette\Mail\Signer] | [DKIM imzalama |#DKIM]


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

E-posta Gönderme

Haber bültenleri veya sipariş onayları gibi e-postalar mı göndereceksiniz? Nette Framework çok güzel bir API ile gerekli araçları sağlar. Biz göstereceğiz:

  • ekler de dahil olmak üzere bir e-posta nasıl oluşturulur
  • nasıl gönderilir
  • e-postalar ve şablonlar nasıl birleştirilir

Kurulum

Composer'ı kullanarak paketi indirin ve yükleyin:

composer require nette/mail

E-posta Oluşturma

E-posta bir Nette\Mail\Message nesnesidir:

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

Tüm parametreler UTF-8 olarak kodlanmalıdır.

Alıcıları addTo() yöntemiyle belirtmenin yanı sıra, addCc() ile kopyanın alıcısını veya addBcc() ile kör kopyanın alıcısını da belirtebilirsiniz. setFrom() dahil olmak üzere tüm bu yöntemler muhatabı üç şekilde kabul eder:

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

HTML ile yazılmış bir e-postanın gövdesi setHtmlBody() yöntemi kullanılarak aktarılır:

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

Metin alternatifi oluşturmak zorunda değilsiniz, Nette bunu sizin için otomatik olarak oluşturacaktır. Ve eğer e-postanın belirlenmiş bir konusu yoksa, konu <title> element.

Görüntüler ayrıca bir e-postanın HTML gövdesine son derece kolay bir şekilde eklenebilir. Görüntülerin fiziksel olarak bulunduğu yolu ikinci parametre olarak geçmeniz yeterlidir; Nette bunları otomatik olarak e-postaya dahil edecektir:

// e-postaya otomatik olarak /path/to/images/background.gif ekler
$mail->setHtmlBody(
	'<b>Merhaba</b> <img src="background.gif">',
	'/path/to/images',
);

Görüntü gömme algoritması aşağıdaki kalıpları destekler: <img src=...>, <body background=...>, url(...) HTML özniteliğinin içinde style ve özel sözdizimi [[...]].

E-posta göndermek daha da kolay olabilir mi?

E-postalar kartpostal gibidir. Parolaları veya diğer kimlik bilgilerini asla e-posta yoluyla göndermeyin.

Ekler

Elbette e-postaya ekler de ekleyebilirsiniz. addAttachment(string $file, ?string $content = null, ?string $contentType = null) adresini kullanın.

// /path/to/example.zip dosyasını example.zip adı altında e-postaya ekler
$mail->addAttachment('/path/to/example.zip');

// /path/to/example.zip dosyasını info.zip adı altında e-postaya ekler
$mail->addAttachment('info.zip', file_get_contents('/path/to/example.zip'));

// yeni example.txt dosya içeriğini ekler "Merhaba John!"
$mail->addAttachment('example.txt', 'Merhaba John!');

Şablonlar

HTML e-postaları gönderiyorsanız, bunları Latte şablon sisteminde yazmak harika bir fikirdir. Nasıl Yapılır?

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

Dosya 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 tüm görüntüleri otomatik olarak ekler, konuyu <title> öğesine dönüştürür ve HTML gövdesi için metin alternatifi oluşturur.

Nette Uygulamasında Kullanım

Nette Uygulaması ile birlikte e-posta kullanıyorsanız, yani sunum yapıyorsanız, n:href özniteliğini veya {link} etiketini kullanarak şablonlarda bağlantılar oluşturmak isteyebilirsiniz. Latte temelde bunları bilmez, ancak bunları eklemek çok kolaydır. Bağlantılar oluşturmak, bağımlılık enjeksiyonu kullanarak geçirerek elde ettiğiniz nesne Nette\Application\LinkGenerator yapabilir.

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

Şablonda, normal bir şablonda olduğu gibi bağlantı oluşturulur. LinkGenerator üzerinden oluşturulan tüm linkler mutlaktır:

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

E-posta Gönderme

Mailer, e-posta göndermekten sorumlu sınıftır. Nette\Mail\Mailer arayüzünü uygular ve tanıtacağımız birkaç hazır mailer mevcuttur.

Çerçeve, DI konteynerine yapılandırmaya dayalı olarak otomatik olarak bir Nette\Mail\Mailer hizmeti ekler; bu hizmeti bağımlılık enjeksiyonu kullanarak geçirirsiniz.

SendmailMailer

Varsayılan posta göndericisi, mail PHP işlevini kullanan SendmailMailer'dir. Kullanım örneği:

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

Eğer returnPath adresini ayarlamak istiyorsanız ve sunucu hala üzerine yazıyorsa, $mailer->commandArgs = '-fmy@email.com' adresini kullanın.

SmtpMailer

SMTP sunucusu üzerinden posta göndermek için SmtpMailer adresini kullanın.

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

Aşağıdaki ek parametreler kurucuya aktarılabilir:

  • port – ayarlanmamışsa, ssl için varsayılan 25 veya 465 kullanılacaktır
  • timeout – SMTP bağlantısı için zaman aşımı
  • persistent – kalıcı bağlantı kullanın
  • clientHost – müşteri tanımı
  • streamOptions – bağlantı için SSL bağlam seçeneklerini ayarlamanızı sağlar

FallbackMailer

E-posta göndermez, ancak bunları bir dizi postacı aracılığıyla gönderir. Bir postacı başarısız olursa, bir sonraki denemeyi tekrarlar. Sonuncusu başarısız olursa, ilkinden yeniden başlar.

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

Yapıcıdaki diğer parametreler tekrar sayısını ve milisaniye cinsinden bekleme süresini içerir.

DKIM

DKIM (DomainKeys Identified Mail), sahte mesajların tespit edilmesine de yardımcı olan güvenilir bir e-posta teknolojisidir. Gönderilen mesaj, gönderenin etki alanının özel anahtarı ile imzalanır ve bu imza e-posta başlığında saklanır. Alıcının sunucusu bu imzayı alan adının DNS kayıtlarında saklanan açık anahtarla karşılaştırır. İmzanın eşleştirilmesiyle, e-postanın gerçekten gönderenin etki alanından kaynaklandığı ve mesajın iletimi sırasında değiştirilmediği gösterilir.

Yapılandırmada e-postayı imzalamak için mailer'ı ayarlayabilirsiniz. Eğer dependency injection kullanmıyorsanız aşağıdaki gibi kullanılır:

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

Yapılandırma

Nette Mail için yapılandırma seçeneklerine genel bakış. Tüm çerçeveyi değil, yalnızca bu kütüphaneyi kullanıyorsanız, yapılandırmayı nasıl yükleyeceğinizi okuyun.

Varsayılan olarak, e-posta göndermek için Nette\Mail\SendmailMailer mailer kullanılır ve daha fazla yapılandırılmaz. Ancak, bunu Nette\Mail\SmtpMailer olarak değiştirebiliriz:

mail:
	# use SmtpMailer
	smtp: true       # (bool) varsayılan değer false

	host: ...        # (string)
	port: ...        # (int)
	username: ...    # (string)
	password: ...    # (string)
	timeout: ...     # (int)
	encryption: ...  # (ssl|tls|null) varsayılan olarak null ('secure' takma adına sahiptir)
	clientHost: ...  # (string) varsayılan olarak $_SERVER['HTTP_HOST']
	persistent: ...  # (bool) varsayılan değer false

	# SMTP sunucusuna bağlanmak için bağlam, varsayılan olarak stream_context_get_default()
	context:
		ssl:         # https://www.php.net/manual/en/context.ssl.php adresindeki tüm seçenekler
			allow_self_signed: ...
			...
		http:        # tüm seçenekler https://www.php.net/manual/en/context.http.php adresinde
			header: ...
			...

context › ssl › verify_peer: false seçeneğini kullanarak SSL sertifikası kimlik doğrulamasını devre dışı bırakabilirsiniz. Uygulamayı savunmasız hale getireceği için bunu yapmamanız şiddetle tavsiye edilir. Bunun yerine, sertifikaları güven deposuna ekle.

Güvenilirliği artırmak için DKIM teknolojisini kullanarak e-postaları imzalayabiliriz:

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

DI Hizmetleri

Bu hizmetler DI konteynerine eklenir:

Ad Tür Açıklama
mail.mailer Nette\Mail\Mailer e-posta gönderme sınıfı
mail.signer Nette\Mail\Signer DKIM imzalama