MailerInterface.php 2.32 KB
Newer Older
1 2 3 4 5 6 7 8 9 10
<?php
/**
 * @link http://www.yiiframework.com/
 * @copyright Copyright (c) 2008 Yii Software LLC
 * @license http://www.yiiframework.com/license/
 */

namespace yii\mail;

/**
Qiang Xue committed
11
 * MailerInterface is the interface that should be implemented by mailer classes.
12
 *
Qiang Xue committed
13 14 15 16
 * A mailer should mainly support creating and sending [[MessageInterface|mail messages]]. It should
 * also support composition of the message body through the view rendering mechanism. For example,
 *
 * ~~~
17
 * Yii::$app->mail->compose('contact/html', ['contactForm' => $form])
Qiang Xue committed
18 19 20
 *     ->setFrom('from@domain.com')
 *     ->setTo($form->email)
 *     ->setSubject($form->subject)
21 22
 *     ->send();
 * ~~~
23
 *
24 25
 * @see MessageInterface
 *
26 27 28 29 30 31
 * @author Paul Klimov <klimov.paul@gmail.com>
 * @since 2.0
 */
interface MailerInterface
{
	/**
Qiang Xue committed
32
	 * Creates a new message instance and optionally composes its body content via view rendering.
33
	 *
Qiang Xue committed
34
	 * @param string|array $view the view to be used for rendering the message body. This can be:
35
	 *
Qiang Xue committed
36 37 38 39 40 41
	 * - a string, which represents the view name or path alias for rendering the HTML body of the email.
	 *   In this case, the text body will be generated by applying `strip_tags()` to the HTML body.
	 * - an array with 'html' and/or 'text' elements. The 'html' element refers to the view name or path alias
	 *   for rendering the HTML body, while 'text' element is for rendering the text body. For example,
	 *   `['html' => 'contact-html', 'text' => 'contact-text']`.
	 * - null, meaning the message instance will be returned without body content.
42
	 *
43
	 * @param array $params the parameters (name-value pairs) that will be extracted and made available in the view file.
44 45
	 * @return MessageInterface message instance.
	 */
46
	public function compose($view = null, array $params = []);
47 48 49

	/**
	 * Sends the given email message.
Qiang Xue committed
50 51
	 * @param MessageInterface $message email message instance to be sent
	 * @return boolean whether the message has been sent successfully
52 53 54 55
	 */
	public function send($message);

	/**
Qiang Xue committed
56 57 58 59
	 * Sends multiple messages at once.
	 *
	 * This method may be implemented by some mailers which support more efficient way of sending multiple messages in the same batch.
	 *
60
	 * @param array $messages list of email messages, which should be sent.
Qiang Xue committed
61
	 * @return integer number of messages that are successfully sent.
62 63
	 */
	public function sendMultiple(array $messages);
64
}