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

Paul Klimov committed
8
namespace yii\mail;
9 10

/**
Qiang Xue committed
11
 * MessageInterface is the interface that should be implemented by mail message classes.
12
 *
Qiang Xue committed
13 14 15
 * A message represents the settings and content of an email, such as the sender, recipient,
 * subject, body, etc.
 *
16
 * Messages are sent by a [[\yii\mail\MailerInterface|mailer]], like the following,
Qiang Xue committed
17 18
 *
 * ~~~
19
 * Yii::$app->mail->compose()
Qiang Xue committed
20 21 22 23 24
 *     ->setFrom('from@domain.com')
 *     ->setTo($form->email)
 *     ->setSubject($form->subject)
 *     ->setTextBody('Plain text content')
 *     ->setHtmlBody('<b>HTML content</b>')
25 26 27 28
 *     ->send();
 * ~~~
 *
 * @see MailerInterface
29 30 31 32 33 34
 *
 * @author Paul Klimov <klimov.paul@gmail.com>
 * @since 2.0
 */
interface MessageInterface
{
35
	/**
Qiang Xue committed
36 37 38 39 40 41 42
	 * Returns the character set of this message.
	 * @return string the character set of this message.
	 */
	public function getCharset();

	/**
	 * Sets the character set of this message.
43
	 * @param string $charset character set name.
44
	 * @return static self reference.
45
	 */
Qiang Xue committed
46 47 48 49 50 51 52
	public function setCharset($charset);

	/**
	 * Returns the message sender.
	 * @return string the sender
	 */
	public function getFrom();
53

54
	/**
Qiang Xue committed
55
	 * Sets the message sender.
56 57 58
	 * @param string|array $from sender email address.
	 * You may pass an array of addresses if this message is from multiple people.
	 * You may also specify sender name in addition to email address using format:
Qiang Xue committed
59
	 * `[email => name]`.
60
	 * @return static self reference.
61
	 */
Qiang Xue committed
62
	public function setFrom($from);
63 64

	/**
Qiang Xue committed
65 66 67 68 69 70 71
	 * Returns the message recipient(s).
	 * @return array the message recipients
	 */
	public function getTo();

	/**
	 * Sets the message recipient(s).
72 73 74
	 * @param string|array $to receiver email address.
	 * You may pass an array of addresses if multiple recipients should receive this message.
	 * You may also specify receiver name in addition to email address using format:
Qiang Xue committed
75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91
	 * `[email => name]`.
	 * @return static self reference.
	 */
	public function setTo($to);

	/**
	 * Returns the reply-to address of this message.
	 * @return string the reply-to address of this message.
	 */
	public function getReplyTo();

	/**
	 * Sets the reply-to address of this message.
	 * @param string|array $replyTo the reply-to address.
	 * You may pass an array of addresses if this message should be replied to multiple people.
	 * You may also specify reply-to name in addition to email address using format:
	 * `[email => name]`.
92
	 * @return static self reference.
93
	 */
Qiang Xue committed
94 95 96 97 98 99 100
	public function setReplyTo($replyTo);

	/**
	 * Returns the Cc (additional copy receiver) addresses of this message.
	 * @return array the Cc (additional copy receiver) addresses of this message.
	 */
	public function getCc();
101 102

	/**
Qiang Xue committed
103
	 * Sets the Cc (additional copy receiver) addresses of this message.
104 105 106
	 * @param string|array $cc copy receiver email address.
	 * You may pass an array of addresses if multiple recipients should receive this message.
	 * You may also specify receiver name in addition to email address using format:
Qiang Xue committed
107
	 * `[email => name]`.
108
	 * @return static self reference.
109
	 */
Qiang Xue committed
110 111 112 113 114 115 116
	public function setCc($cc);

	/**
	 * Returns the Bcc (hidden copy receiver) addresses of this message.
	 * @return array the Bcc (hidden copy receiver) addresses of this message.
	 */
	public function getBcc();
117 118

	/**
Qiang Xue committed
119
	 * Sets the Bcc (hidden copy receiver) addresses of this message.
120 121 122
	 * @param string|array $bcc hidden copy receiver email address.
	 * You may pass an array of addresses if multiple recipients should receive this message.
	 * You may also specify receiver name in addition to email address using format:
Qiang Xue committed
123
	 * `[email => name]`.
124
	 * @return static self reference.
125
	 */
Qiang Xue committed
126 127 128 129 130 131 132
	public function setBcc($bcc);

	/**
	 * Returns the message subject.
	 * @return string the message subject
	 */
	public function getSubject();
133 134

	/**
Qiang Xue committed
135
	 * Sets the message subject.
136
	 * @param string $subject message subject
137
	 * @return static self reference.
138
	 */
Qiang Xue committed
139
	public function setSubject($subject);
140 141 142 143

	/**
	 * Sets message plain text content.
	 * @param string $text message plain text content.
144
	 * @return static self reference.
145
	 */
Qiang Xue committed
146
	public function setTextBody($text);
147 148 149 150

	/**
	 * Sets message HTML content.
	 * @param string $html message HTML content.
151
	 * @return static self reference.
152
	 */
Qiang Xue committed
153
	public function setHtmlBody($html);
154 155

	/**
156 157
	 * Attaches existing file to the email message.
	 * @param string $fileName full file name
158
	 * @param array $options options for embed file. Valid options are:
159
	 *
160 161
	 * - fileName: name, which should be used to attach file.
	 * - contentType: attached file MIME type.
162
	 *
163
	 * @return static self reference.
164
	 */
165
	public function attach($fileName, array $options = []);
166 167

	/**
168 169
	 * Attach specified content as file for the email message.
	 * @param string $content attachment file content.
170
	 * @param array $options options for embed file. Valid options are:
171
	 *
172 173
	 * - fileName: name, which should be used to attach file.
	 * - contentType: attached file MIME type.
174
	 *
175
	 * @return static self reference.
176
	 */
177
	public function attachContent($content, array $options = []);
178 179 180 181 182 183

	/**
	 * Attach a file and return it's CID source.
	 * This method should be used when embedding images or other data in a message.
	 * @param string $fileName file name.
	 * @param array $options options for embed file. Valid options are:
184
	 *
185 186
	 * - fileName: name, which should be used to attach file.
	 * - contentType: attached file MIME type.
187
	 *
188 189
	 * @return string attachment CID.
	 */
190
	public function embed($fileName, array $options = []);
191 192 193 194 195 196

	/**
	 * Attach a content as file and return it's CID source.
	 * This method should be used when embedding images or other data in a message.
	 * @param string $content  attachment file content.
	 * @param array $options options for embed file. Valid options are:
197
	 *
198 199
	 * - fileName: name, which should be used to attach file.
	 * - contentType: attached file MIME type.
200
	 *
201 202 203
	 * @return string attachment CID.
	 */
	public function embedContent($content, array $options = []);
204 205 206

	/**
	 * Sends this email message.
207 208
	 * @param MailerInterface $mailer the mailer that should be used to send this message.
	 * If null, the "mail" application component will be used instead.
Qiang Xue committed
209
	 * @return boolean whether this message is sent successfully.
210
	 */
211
	public function send(MailerInterface $mailer = null);
212

213
	/**
214 215
	 * Returns string representation of this message.
	 * @return string the string representation of this message.
216
	 */
217
	public function toString();
218
}