MessageInterface.php 6.89 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->mailer->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 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 45 46 47 48 49 50 51 52 53 54 55
     * @return static self reference.
     */
    public function setCharset($charset);

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

    /**
     * Sets the message sender.
56 57 58 59 60
     * @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:
     * `[email => name]`.
     * @return static self reference.
61 62 63 64 65 66 67 68 69 70 71
     */
    public function setFrom($from);

    /**
     * Returns the message recipient(s).
     * @return array the message recipients
     */
    public function getTo();

    /**
     * Sets the message recipient(s).
72 73 74 75 76
     * @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:
     * `[email => name]`.
     * @return static self reference.
77 78 79 80 81 82 83 84 85 86 87
     */
    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.
88 89 90 91 92
     * @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]`.
     * @return static self reference.
93 94 95 96 97 98 99 100 101 102 103
     */
    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();

    /**
     * Sets the Cc (additional copy receiver) addresses of this message.
104 105 106 107 108
     * @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:
     * `[email => name]`.
     * @return static self reference.
109 110 111 112 113 114 115 116 117 118 119
     */
    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();

    /**
     * Sets the Bcc (hidden copy receiver) addresses of this message.
120 121 122 123 124
     * @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:
     * `[email => name]`.
     * @return static self reference.
125 126 127 128 129 130 131 132 133 134 135
     */
    public function setBcc($bcc);

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

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

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

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

    /**
     * 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 162 163 164 165 166 167 168 169
     *
     * - fileName: name, which should be used to attach file.
     * - contentType: attached file MIME type.
     *
     * @return static self reference.
     */
    public function attach($fileName, array $options = []);

    /**
     * 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 174 175 176 177 178 179 180 181 182
     *
     * - fileName: name, which should be used to attach file.
     * - contentType: attached file MIME type.
     *
     * @return static self reference.
     */
    public function attachContent($content, array $options = []);

    /**
     * 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.
183
     * @param array $options options for embed file. Valid options are:
184 185 186 187 188 189 190 191 192 193 194 195
     *
     * - fileName: name, which should be used to attach file.
     * - contentType: attached file MIME type.
     *
     * @return string attachment CID.
     */
    public function embed($fileName, array $options = []);

    /**
     * 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.
196
     * @param array $options options for embed file. Valid options are:
197 198 199 200 201 202 203 204 205 206
     *
     * - fileName: name, which should be used to attach file.
     * - contentType: attached file MIME type.
     *
     * @return string attachment CID.
     */
    public function embedContent($content, array $options = []);

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

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