From b611c4241f3a6a5318411c973ecf31d4204299c1 Mon Sep 17 00:00:00 2001 From: Paul Klimov Date: Wed, 23 Oct 2013 17:12:33 +0300 Subject: [PATCH] Email message interface extracted. --- framework/yii/email/BaseMessage.php | 79 ++---------------- framework/yii/email/Message.php | 11 +++ framework/yii/email/MessageInterface.php | 116 ++++++++++++++++++++++++++ framework/yii/email/swift/Message.php | 62 ++++++-------- tests/unit/framework/email/BaseMailerTest.php | 4 + 5 files changed, 166 insertions(+), 106 deletions(-) create mode 100644 framework/yii/email/MessageInterface.php diff --git a/framework/yii/email/BaseMessage.php b/framework/yii/email/BaseMessage.php index 00d27e0..aca71ee 100644 --- a/framework/yii/email/BaseMessage.php +++ b/framework/yii/email/BaseMessage.php @@ -21,10 +21,10 @@ use Yii; * @see BaseMailer * * @property \yii\email\BaseMailer $mailer mailer component instance. This property is read-only. - * @property string|array $from sender email address, if array is given, its first element should - * be sender email address, second - sender name. - * @property string|array $to receiver email address, if array is given, its first element should - * be receiver email address, second - receiver name. + * @property string|array $from sender email address. + * @property string|array $to receiver email address. + * @property string|array $cc copy receiver email address. + * @property string|array $bcc hidden copy receiver email address. * @property string $subject message subject. * @property string $text message plain text content. * @property string $html message HTML content. @@ -32,7 +32,7 @@ use Yii; * @author Paul Klimov * @since 2.0 */ -abstract class BaseMessage extends Object +abstract class BaseMessage extends Object implements MessageInterface { /** * @return \yii\email\BaseMailer @@ -53,8 +53,7 @@ abstract class BaseMessage extends Object } /** - * Sends this email message. - * @return boolean success. + * @inheritdoc */ public function send() { @@ -62,63 +61,7 @@ abstract class BaseMessage extends Object } /** - * Sets message sender. - * @param string|array $from sender email address, if array is given, - * its first element should be sender email address, second - sender name. - */ - abstract public function setFrom($from); - - /** - * Sets message receiver. - * @param string|array $to receiver email address, if array is given, - * its first element should be receiver email address, second - receiver name. - */ - abstract public function setTo($to); - - /** - * Sets message subject. - * @param string $subject message subject - */ - abstract public function setSubject($subject); - - /** - * Sets message plain text content. - * @param string $text message plain text content. - */ - abstract public function setText($text); - - /** - * Sets message HTML content. - * @param string $html message HTML content. - */ - abstract public function setHtml($html); - - /** - * Add message plain text content part. - * @param string $text message plain text content. - */ - abstract public function addText($text); - - /** - * Add message HTML content part. - * @param string $html message HTML content. - */ - abstract public function addHtml($html); - - /** - * Create file attachment for the email message. - * @param string $content attachment file content. - * @param string $fileName attachment file name. - * @param string $contentType MIME type of the attachment file, by default 'application/octet-stream' will be used. - */ - abstract public function createAttachment($content, $fileName, $contentType = 'application/octet-stream'); - - /** - * Attaches existing file to the email message. - * @param string $fileName full file name - * @param string $contentType MIME type of the attachment file, if empty it will be suggested automatically. - * @param string $attachFileName name, which should be used for attachment, if empty file base name will be used. - * @throws \yii\base\InvalidParamException if given file does not exist. + * @inheritdoc */ public function attachFile($fileName, $contentType = null, $attachFileName = null) { @@ -136,13 +79,7 @@ abstract class BaseMessage extends Object } /** - * Renders a view. - * The view to be rendered can be specified in one of the following formats: - * - path alias (e.g. "@app/emails/contact/body"); - * - relative path (e.g. "contact"): the actual view file will be resolved by [[resolveView]]. - * @param string $view the view name or the path alias of the view file. - * @param array $params the parameters (name-value pairs) that will be extracted and made available in the view file. - * @return string string the rendering result + * @inheritdoc */ public function render($view, $params = []) { diff --git a/framework/yii/email/Message.php b/framework/yii/email/Message.php index c7ec534..e8a14ab 100644 --- a/framework/yii/email/Message.php +++ b/framework/yii/email/Message.php @@ -22,6 +22,17 @@ use yii\email\swift\Message as SwiftMessage; * $email->send(); * ~~~ * + * You can use message object to render view, which can be used to compose the message content: + * ~~~ + * $email = new Message(); + * $email->from = $contactForm->email; + * $email->to = 'admin@domain.com'; + * $email->subject = $email->render('contact/subject', ['form' => $contactForm]); + * $email->addHtml($email->render('contact/html', ['form' => $contactForm])); + * $email->addText($email->render('contact/text', ['form' => $contactForm])); + * $email->send(); + * ~~~ + * * This particular class uses 'SwiftMailer' library to perform the message sending. * Note: you can replace usage of this class by your own one, using [[Yii::$classMap]]: * ~~~ diff --git a/framework/yii/email/MessageInterface.php b/framework/yii/email/MessageInterface.php new file mode 100644 index 0000000..c94d2ab --- /dev/null +++ b/framework/yii/email/MessageInterface.php @@ -0,0 +1,116 @@ + + * @since 2.0 + */ +interface MessageInterface +{ + /** + * Sets message sender. + * @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]. + */ + public function setFrom($from); + + /** + * Sets message receiver. + * @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]. + */ + public function setTo($to); + + /** + * Set the Cc (additional copy receiver) addresses of this message. + * @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]. + */ + public function setCc($cc); + + /** + * Set the Bcc (hidden copy receiver) addresses of this message. + * @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]. + */ + public function setBcc($bcc); + + /** + * Sets message subject. + * @param string $subject message subject + */ + public function setSubject($subject); + + /** + * Sets message plain text content. + * @param string $text message plain text content. + */ + public function setText($text); + + /** + * Sets message HTML content. + * @param string $html message HTML content. + */ + public function setHtml($html); + + /** + * Add message plain text content part. + * @param string $text message plain text content. + */ + public function addText($text); + + /** + * Add message HTML content part. + * @param string $html message HTML content. + */ + public function addHtml($html); + + /** + * Create file attachment for the email message. + * @param string $content attachment file content. + * @param string $fileName attachment file name. + * @param string $contentType MIME type of the attachment file, by default 'application/octet-stream' will be used. + */ + public function createAttachment($content, $fileName, $contentType = 'application/octet-stream'); + + /** + * Attaches existing file to the email message. + * @param string $fileName full file name + * @param string $contentType MIME type of the attachment file, if empty it will be suggested automatically. + * @param string $attachFileName name, which should be used for attachment, if empty file base name will be used. + */ + public function attachFile($fileName, $contentType = null, $attachFileName = null); + + /** + * Sends this email message. + * @return boolean success. + */ + public function send(); + + /** + * Renders a view. + * The view to be rendered can be specified in one of the following formats: + * - path alias (e.g. "@app/emails/contact/body"); + * - relative path (e.g. "contact"): the actual view file will be resolved by [[resolveView]]. + * @param string $view the view name or the path alias of the view file. + * @param array $params the parameters (name-value pairs) that will be extracted and made available in the view file. + * @return string string the rendering result + */ + public function render($view, $params = []); +} \ No newline at end of file diff --git a/framework/yii/email/swift/Message.php b/framework/yii/email/swift/Message.php index 5b8c575..04ef7b5 100644 --- a/framework/yii/email/swift/Message.php +++ b/framework/yii/email/swift/Message.php @@ -40,41 +40,40 @@ class Message extends BaseMessage } /** - * Sets message sender. - * @param string|array $from sender email address, if array is given, - * its first element should be sender email address, second - sender name. + * @inheritdoc */ public function setFrom($from) { - if (is_array($from)) { - list ($address, $name) = $from; - } else { - $address = $from; - $name = null; - } - $this->getSwiftMessage()->setFrom($address, $name); - $this->getSwiftMessage()->setReplyTo($address, $name); + $this->getSwiftMessage()->setFrom($from); + $this->getSwiftMessage()->setReplyTo($from); } /** - * Sets message receiver. - * @param string|array $to receiver email address, if array is given, - * its first element should be receiver email address, second - receiver name. + * @inheritdoc */ public function setTo($to) { - if (is_array($to)) { - list ($address, $name) = $to; - } else { - $address = $to; - $name = null; - } - $this->getSwiftMessage()->setTo($address, $name); + $this->getSwiftMessage()->setTo($to); + } + + /** + * @inheritdoc + */ + public function setCc($cc) + { + $this->getSwiftMessage()->setCc($cc); + } + + /** + * @inheritdoc + */ + public function setBcc($bcc) + { + $this->getSwiftMessage()->setBcc($bcc); } /** - * Sets message subject. - * @param string $subject message subject + * @inheritdoc */ public function setSubject($subject) { @@ -82,8 +81,7 @@ class Message extends BaseMessage } /** - * Sets message plain text content. - * @param string $text message plain text content. + * @inheritdoc */ public function setText($text) { @@ -91,8 +89,7 @@ class Message extends BaseMessage } /** - * Sets message HTML content. - * @param string $html message HTML content. + * @inheritdoc */ public function setHtml($html) { @@ -100,8 +97,7 @@ class Message extends BaseMessage } /** - * Add message plain text content part. - * @param string $text message plain text content. + * @inheritdoc */ public function addText($text) { @@ -109,8 +105,7 @@ class Message extends BaseMessage } /** - * Add message HTML content part. - * @param string $html message HTML content. + * @inheritdoc */ public function addHtml($html) { @@ -118,10 +113,7 @@ class Message extends BaseMessage } /** - * Create file attachment for the email message. - * @param string $content - attachment file content. - * @param string $fileName - attachment file name. - * @param string $contentType - MIME type of the attachment file, by default 'application/octet-stream' will be used. + * @inheritdoc */ public function createAttachment($content, $fileName, $contentType = 'application/octet-stream') { diff --git a/tests/unit/framework/email/BaseMailerTest.php b/tests/unit/framework/email/BaseMailerTest.php index bd97aeb..b75d628 100644 --- a/tests/unit/framework/email/BaseMailerTest.php +++ b/tests/unit/framework/email/BaseMailerTest.php @@ -173,6 +173,10 @@ class Message extends BaseMessage public function setTo($to) {} + public function setCc($cc) {} + + public function setBcc($bcc) {} + public function setSubject($subject) {} public function setText($text) {}