Email message interface extracted.

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 <klimov.paul@gmail.com>
  * @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 = [])
 	{

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]]:
  * ~~~

framework/yii/email/MessageInterface.php

@@ -0,0 +1,116 @@
+<?php
+/**
+ * @link http://www.yiiframework.com/
+ * @copyright Copyright (c) 2008 Yii Software LLC
+ * @license http://www.yiiframework.com/license/
+ */
+
+namespace yii\email;
+
+/**
+ * Class MessageInterface
+ *
+ * @author Paul Klimov <klimov.paul@gmail.com>
+ * @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 = []);
+}

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($to);
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public function setCc($cc)
+	{
+		$this->getSwiftMessage()->setCc($cc);
 	}
-		$this->getSwiftMessage()->setTo($address, $name);
+
+	/**
+	 * @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')
 	{

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) {}