Αποστολή μηνυμάτων ηλεκτρονικού ταχυδρομείου

Ετοιμάζεστε να στείλετε μηνύματα ηλεκτρονικού ταχυδρομείου, όπως ενημερωτικά δελτία ή επιβεβαιώσεις παραγγελιών; Το Nette Framework παρέχει τα απαραίτητα εργαλεία με ένα πολύ φιλικό API. Θα δείξουμε:

πώς να δημιουργήσετε ένα μήνυμα ηλεκτρονικού ταχυδρομείου, συμπεριλαμβανομένων των συνημμένων
πώς να το στείλετε
πώς να συνδυάσετε μηνύματα ηλεκτρονικού ταχυδρομείου και πρότυπα

Εγκατάσταση

Μπορείτε να κατεβάσετε και να εγκαταστήσετε τη βιβλιοθήκη χρησιμοποιώντας το Composer:

composer require nette/mail

Δημιουργία μηνύματος ηλεκτρονικού ταχυδρομείου

Το μήνυμα ηλεκτρονικού ταχυδρομείου είναι ένα αντικείμενο της κλάσης Nette\Mail\Message. Ας το δημιουργήσουμε ως εξής:

$mail = new Nette\Mail\Message;
$mail->setFrom('Franta <franta@example.com>')
	->addTo('petr@example.com')
	->addTo('jirka@example.com')
	->setSubject('Επιβεβαίωση παραγγελίας')
	->setBody("Γεια σας,\nη παραγγελία σας έγινε αποδεκτή.");

Όλες οι παρεχόμενες παράμετροι πρέπει να είναι σε UTF-8.

Εκτός από τον καθορισμό του παραλήπτη με τη μέθοδο addTo(), μπορείτε επίσης να καθορίσετε έναν παραλήπτη κοινοποίησης (CC) addCc() ή έναν παραλήπτη κρυφής κοινοποίησης (BCC) addBcc(). Σε όλες αυτές τις μεθόδους, συμπεριλαμβανομένης της setFrom(), μπορούμε να γράψουμε τον παραλήπτη με τρεις τρόπους:

$mail->setFrom('franta@example.com');
$mail->setFrom('franta@example.com', 'Franta');
$mail->setFrom('Franta <franta@example.com>');

Το σώμα του μηνύματος ηλεκτρονικού ταχυδρομείου γραμμένο σε HTML περνιέται χρησιμοποιώντας τη μέθοδο setHtmlBody():

$mail->setHtmlBody('<p>Γεια σας,</p><p>η παραγγελία σας έγινε αποδεκτή.</p>');

Δεν χρειάζεται να δημιουργήσετε μια εναλλακτική λύση κειμένου, το Nette θα τη δημιουργήσει αυτόματα για εσάς. Και αν το μήνυμα ηλεκτρονικού ταχυδρομείου δεν έχει ορισμένο θέμα, θα προσπαθήσει να το πάρει από το στοιχείο <title>.

Μπορείτε επίσης να εισαγάγετε εικόνες στο σώμα HTML εξαιρετικά εύκολα. Απλώς περάστε τη διαδρομή όπου βρίσκονται φυσικά οι εικόνες ως δεύτερη παράμετρο, και το Nette θα τις συμπεριλάβει αυτόματα στο μήνυμα ηλεκτρονικού ταχυδρομείου:

// προσθέτει αυτόματα το /path/to/images/background.gif στο email
$mail->setHtmlBody(
	'<b>Hello</b> <img src="background.gif">',
	'/path/to/images',
);

Ο αλγόριθμος που εισάγει εικόνες αναζητά αυτά τα πρότυπα: <img src=...>, <body background=...>, url(...) μέσα στο attribute HTML style, και την ειδική σύνταξη [[...]].

Μπορεί η αποστολή μηνυμάτων ηλεκτρονικού ταχυδρομείου να γίνει ακόμα πιο εύκολη;

Ένα μήνυμα ηλεκτρονικού ταχυδρομείου είναι σαν μια ταχυδρομική κάρτα. Ποτέ μην στέλνετε κωδικούς πρόσβασης ή άλλα διαπιστευτήρια μέσω μηνύματος ηλεκτρονικού ταχυδρομείου.

Συνημμένα

Φυσικά, μπορείτε να επισυνάψετε συνημμένα στο μήνυμα ηλεκτρονικού ταχυδρομείου. Η μέθοδος addAttachment(string $file, ?string $content = null, ?string $contentType = null) χρησιμοποιείται για αυτόν τον σκοπό.

// εισάγει το αρχείο /path/to/example.zip στο email με το όνομα example.zip
$mail->addAttachment('/path/to/example.zip');

// εισάγει το αρχείο /path/to/example.zip με το όνομα info.zip στο email
$mail->addAttachment('info.zip', file_get_contents('/path/to/example.zip'));

// εισάγει το αρχείο example.txt με το περιεχόμενο "Hello John!" στο email
$mail->addAttachment('example.txt', 'Hello John!');

Πρότυπα

Αν στέλνετε μηνύματα ηλεκτρονικού ταχυδρομείου HTML, είναι φυσικό να τα γράφετε στο σύστημα προτύπων Latte. Πώς να το κάνετε;

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

Αρχείο email.latte:

<html>
<head>
	<meta charset="utf-8">
	<title>Επιβεβαίωση παραγγελίας</title>
	<style>
	body {
		background: url("background.png")
	}
	</style>
</head>
<body>
	<p>Γεια σας,</p>

	<p>Η παραγγελία σας με αριθμό {$orderId} έγινε αποδεκτή.</p>
</body>
</html>

Το Nette εισάγει αυτόματα όλες τις εικόνες, ορίζει το θέμα σύμφωνα με το στοιχείο <title> και δημιουργεί μια εναλλακτική λύση κειμένου για το HTML.

Χρήση στην εφαρμογή Nette

Αν χρησιμοποιείτε μηνύματα ηλεκτρονικού ταχυδρομείου μαζί με την Nette Application, δηλαδή με presenters, μπορεί να θέλετε να δημιουργήσετε συνδέσμους στα πρότυπα χρησιμοποιώντας το attribute n:href ή το tag {link}. Το Latte δεν τα γνωρίζει από προεπιλογή, αλλά είναι πολύ εύκολο να τα προσθέσετε. Το αντικείμενο Nette\Application\LinkGenerator μπορεί να δημιουργήσει συνδέσμους, και μπορείτε να το αποκτήσετε περνώντας το χρησιμοποιώντας dependency injection:

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

Στο πρότυπο, δημιουργούμε συνδέσμους όπως έχουμε συνηθίσει. Όλοι οι σύνδεσμοι που δημιουργούνται μέσω του LinkGenerator θα είναι απόλυτοι.

<a n:href="Presenter:action">Σύνδεσμος</a>

Αποστολή μηνύματος ηλεκτρονικού ταχυδρομείου

Ο Mailer είναι μια κλάση που χειρίζεται την αποστολή μηνυμάτων ηλεκτρονικού ταχυδρομείου. Υλοποιεί το interface Nette\Mail\Mailer και υπάρχουν αρκετοί προκατασκευασμένοι mailers διαθέσιμοι, τους οποίους θα παρουσιάσουμε.

Το Framework προσθέτει αυτόματα μια υπηρεσία τύπου Nette\Mail\Mailer στο DI container, διαμορφωμένη βάσει της διαμόρφωσης, στην οποία μπορείτε να αποκτήσετε πρόσβαση περνώντας την χρησιμοποιώντας dependency injection.

SendmailMailer

Ο προεπιλεγμένος mailer είναι ο SendmailMailer, ο οποίος χρησιμοποιεί τη συνάρτηση PHP mail. Παράδειγμα χρήσης:

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

Αν θέλετε να ορίσετε το returnPath και ο διακομιστής σας το αντικαθιστά συνεχώς, χρησιμοποιήστε $mailer->commandArgs = '-fmy@email.com'.

SmtpMailer

Ο SmtpMailer χρησιμοποιείται για την αποστολή αλληλογραφίας μέσω ενός διακομιστή SMTP.

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

Οι ακόλουθες πρόσθετες παράμετροι μπορούν να περάσουν στον κατασκευαστή:

port – αν δεν οριστεί, χρησιμοποιείται η προεπιλογή 25 ή 465 για ssl
timeout – timeout για τη σύνδεση SMTP
persistent – χρήση μόνιμης σύνδεσης
clientHost – ρύθμιση της κεφαλίδας Host του client
streamOptions – επιτρέπει τη ρύθμιση των SSL context options για τη σύνδεση

FallbackMailer

Δεν στέλνει απευθείας μηνύματα ηλεκτρονικού ταχυδρομείου, αλλά μεσολαβεί στην αποστολή μέσω ενός συνόλου mailers. Αν ένας mailer αποτύχει, επαναλαμβάνει την προσπάθεια με τον επόμενο. Αν και ο τελευταίος αποτύχει, ξεκινά ξανά από τον πρώτο.

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

Ως πρόσθετες παράμετροι στον κατασκευαστή, μπορούμε να καθορίσουμε τον αριθμό των επαναλήψεων και τον χρόνο αναμονής σε χιλιοστά του δευτερολέπτου.

DKIM

Το DKIM (DomainKeys Identified Mail) είναι μια τεχνολογία για την αύξηση της αξιοπιστίας των μηνυμάτων ηλεκτρονικού ταχυδρομείου, η οποία βοηθά επίσης στην ανίχνευση πλαστών μηνυμάτων. Το απεσταλμένο μήνυμα υπογράφεται με το ιδιωτικό κλειδί του τομέα του αποστολέα και αυτή η υπογραφή αποθηκεύεται στην κεφαλίδα του μηνύματος ηλεκτρονικού ταχυδρομείου. Ο διακομιστής του παραλήπτη συγκρίνει αυτήν την υπογραφή με το δημόσιο κλειδί που είναι αποθηκευμένο στις εγγραφές DNS του τομέα. Εάν η υπογραφή ταιριάζει, αποδεικνύεται ότι το μήνυμα ηλεκτρονικού ταχυδρομείου προέρχεται πράγματι από τον τομέα του αποστολέα και ότι δεν υπήρξε τροποποίηση κατά τη μεταφορά του μηνύματος.

Μπορείτε να ρυθμίσετε την υπογραφή μηνυμάτων ηλεκτρονικού ταχυδρομείου για τον mailer απευθείας στη διαμόρφωση. Αν δεν χρησιμοποιείτε dependency injection, χρησιμοποιείται με αυτόν τον τρόπο:

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

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

Διαμόρφωση

Επισκόπηση των επιλογών διαμόρφωσης για το Nette Mail. Αν δεν χρησιμοποιείτε ολόκληρο το framework, αλλά μόνο αυτή τη βιβλιοθήκη, διαβάστε πώς να φορτώσετε τη διαμόρφωση.

Για την αποστολή μηνυμάτων ηλεκτρονικού ταχυδρομείου, χρησιμοποιείται από προεπιλογή ο mailer Nette\Mail\SendmailMailer, ο οποίος δεν διαμορφώνεται περαιτέρω. Ωστόσο, μπορούμε να τον αλλάξουμε σε Nette\Mail\SmtpMailer:

mail:
	# χρησιμοποιεί SmtpMailer
	smtp: true       # (bool) προεπιλογή είναι false

	host: ...        # (string)
	port: ...        # (int)
	username: ...    # (string)
	password: ...    # (string)
	timeout: ...     # (int)
	encryption: ...  # (ssl|tls|null) προεπιλογή είναι null (έχει ψευδώνυμο 'secure')
	clientHost: ...  # (string) προεπιλογή είναι $_SERVER['HTTP_HOST']
	persistent: ...  # (bool) προεπιλογή είναι false

	# context για σύνδεση στον SMTP server, προεπιλογή είναι stream_context_get_default()
	context:
		ssl:         # επισκόπηση επιλογών στο https://www.php.net/manual/en/context.ssl.php
			allow_self_signed: ...
			...
		http:        # επισκόπηση επιλογών στο https://www.php.net/manual/en/context.http.php
			header: ...
			...

Χρησιμοποιώντας την επιλογή context › ssl › verify_peer: false, μπορείτε να απενεργοποιήσετε την επαλήθευση των πιστοποιητικών SSL. Συνιστούμε έντονα να μην το κάνετε αυτό, καθώς η εφαρμογή θα γίνει ευάλωτη. Αντ' αυτού, προσθέστε τα πιστοποιητικά στην αποθήκη.

Για να αυξήσουμε την αξιοπιστία, μπορούμε να υπογράφουμε τα μηνύματα ηλεκτρονικού ταχυδρομείου χρησιμοποιώντας την τεχνολογία DKIM:

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

Υπηρεσίες DI

Αυτές οι υπηρεσίες προστίθενται στο DI container:

Όνομα	Τύπος	Περιγραφή
`mail.mailer`	Nette\Mail\Mailer	κλάση που στέλνει μηνύματα ηλεκτρονικού ταχυδρομείου
`mail.signer`	Nette\Mail\Signer	Υπογραφή DKIM

Ταχυδρομείο

Αποστολή μηνυμάτων ηλεκτρονικού ταχυδρομείου

Εγκατάσταση

Δημιουργία μηνύματος ηλεκτρονικού ταχυδρομείου

Συνημμένα

Πρότυπα

Χρήση στην εφαρμογή Nette

Αποστολή μηνύματος ηλεκτρονικού ταχυδρομείου

SendmailMailer

SmtpMailer

FallbackMailer

DKIM

Διαμόρφωση

Υπηρεσίες DI