Refactored mail.

extensions/swiftmailer/Mailer.php

@@ -12,10 +12,10 @@ use yii\base\InvalidConfigException;
 use yii\mail\BaseMailer;
 
 /**
- * Mailer based on SwiftMailer library.
+ * Mailer implements a mailer based on SwiftMailer.
+ *
+ * To use Mailer, you should configure it in the application configuration like the following,
  *
- * By default PHP 'mail' function will be used as default email transport.
- * You can setup different email transport via [[vendorMailer]] property:
  * ~~~
  * 'components' => array(
  *     ...
@@ -34,9 +34,20 @@ use yii\mail\BaseMailer;
  * ),
  * ~~~
  *
- * @see http://swiftmailer.org
+ * You may also skip the configuration of the [[transport]] property. In that case, the default
+ * PHP `mail()` function will be used to send emails.
+ *
+ * To send an email, you may use the following code:
+ *
+ * ~~~
+ * Yii::$app->mail->compose('contact/html', ['contactForm' => $form])
+ *     ->setFrom('from@domain.com')
+ *     ->setTo($form->email)
+ *     ->setSubject($form->subject)
+ *     ->send();
+ * ~~~
  *
- * @method Message compose($view = null, array $params = []) creates new message optionally filling up its body via view rendering.
+ * @see http://swiftmailer.org
  *
  * @author Paul Klimov <klimov.paul@gmail.com>
  * @since 2.0
@@ -69,7 +80,7 @@ class Mailer extends BaseMailer
 
 	/**
 	 * @param array|\Swift_Transport $transport
-	 * @throws \yii\base\InvalidConfigException on invalid argument.
+	 * @throws InvalidConfigException on invalid argument.
 	 */
 	public function setTransport($transport)
 	{
@@ -95,8 +106,12 @@ class Mailer extends BaseMailer
 	 */
 	public function send($message)
 	{
-		Yii::trace('Sending email message', __METHOD__);
-		return ($this->getSwiftMailer()->send($message->getSwiftMessage()) > 0);
+		$address = $message->getTo();
+		if (is_array($address)) {
+			$address = implode(', ', $address);
+		}
+		Yii::trace('Sending email "' . $message->getSubject() . '" to "' . $address . '"', __METHOD__);
+		return $this->getSwiftMailer()->send($message->getSwiftMessage()) > 0;
 	}
 
 	/**

extensions/swiftmailer/Message.php

@@ -10,10 +10,10 @@ namespace yii\swiftmailer;
 use yii\mail\BaseMessage;
 
 /**
- * Email message based on SwiftMailer library.
+ * Message implements a message class based on SwiftMailer.
  *
  * @see http://swiftmailer.org/docs/messages.html
- * @see \yii\swiftmailer\Mailer
+ * @see Mailer
  *
  * @method Mailer getMailer() returns mailer instance.
  * @property \Swift_Message $swiftMessage vendor message instance.
@@ -42,7 +42,15 @@ class Message extends BaseMessage
 	/**
 	 * @inheritdoc
 	 */
-	public function charset($charset)
+	public function getCharset()
+	{
+		$this->getSwiftMessage()->getCharset();
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public function setCharset($charset)
 	{
 		$this->getSwiftMessage()->setCharset($charset);
 		return $this;
@@ -51,17 +59,49 @@ class Message extends BaseMessage
 	/**
 	 * @inheritdoc
 	 */
-	public function from($from)
+	public function getFrom()
+	{
+		$this->getSwiftMessage()->getFrom();
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public function setFrom($from)
 	{
 		$this->getSwiftMessage()->setFrom($from);
-		$this->getSwiftMessage()->setReplyTo($from);
 		return $this;
 	}
 
 	/**
 	 * @inheritdoc
 	 */
-	public function to($to)
+	public function getReplyTo()
+	{
+		$this->getSwiftMessage()->getReplyTo();
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public function setReplyTo($replyTo)
+	{
+		$this->getSwiftMessage()->setReplyTo($replyTo);
+		return $this;
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public function getTo()
+	{
+		$this->getSwiftMessage()->getTo();
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public function setTo($to)
 	{
 		$this->getSwiftMessage()->setTo($to);
 		return $this;
@@ -70,7 +110,15 @@ class Message extends BaseMessage
 	/**
 	 * @inheritdoc
 	 */
-	public function cc($cc)
+	public function getCc()
+	{
+		$this->getSwiftMessage()->getCc();
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public function setCc($cc)
 	{
 		$this->getSwiftMessage()->setCc($cc);
 		return $this;
@@ -79,7 +127,15 @@ class Message extends BaseMessage
 	/**
 	 * @inheritdoc
 	 */
-	public function bcc($bcc)
+	public function getBcc()
+	{
+		$this->getSwiftMessage()->getBcc();
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public function setBcc($bcc)
 	{
 		$this->getSwiftMessage()->setBcc($bcc);
 		return $this;
@@ -88,7 +144,15 @@ class Message extends BaseMessage
 	/**
 	 * @inheritdoc
 	 */
-	public function subject($subject)
+	public function getSubject()
+	{
+		$this->getSwiftMessage()->getSubject();
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public function setSubject($subject)
 	{
 		$this->getSwiftMessage()->setSubject($subject);
 		return $this;
@@ -97,7 +161,7 @@ class Message extends BaseMessage
 	/**
 	 * @inheritdoc
 	 */
-	public function textBody($text)
+	public function setTextBody($text)
 	{
 		$this->setBody($text, 'text/plain');
 		return $this;
@@ -106,7 +170,7 @@ class Message extends BaseMessage
 	/**
 	 * @inheritdoc
 	 */
-	public function htmlBody($html)
+	public function setHtmlBody($html)
 	{
 		$this->setBody($html, 'text/html');
 		return $this;

framework/yii/mail/BaseMessage.php

@@ -11,14 +11,14 @@ use yii\base\Object;
 use Yii;
 
 /**
- * BaseMessage represent the single email message.
- * It functionality depends on application component 'email',
- * which should provide the actual email sending functionality as well as
- * default message configuration.
+ * BaseMessage serves as a base class that implements the [[send()]] method required by [[MessageInterface]].
+ *
+ * By default, [[send()]] will use the "mail" application component to send the current message.
+ * The "mail" application component should be a mailer instance implementing [[MailerInterface]].
  *
  * @see BaseMailer
  *
- * @property \yii\mail\BaseMailer $mailer mailer component instance. This property is read-only.
+ * @property BaseMailer $mailer mailer component instance. This property is read-only.
  *
  * @author Paul Klimov <klimov.paul@gmail.com>
  * @since 2.0
@@ -26,7 +26,7 @@ use Yii;
 abstract class BaseMessage extends Object implements MessageInterface
 {
 	/**
-	 * @return \yii\mail\BaseMailer mailer component instance.
+	 * @return MailerInterface the mailer component
 	 */
 	public function getMailer()
 	{

framework/yii/mail/MailerInterface.php

@@ -8,15 +8,16 @@
 namespace yii\mail;
 
 /**
- * MailerInterface is an interface, which any mailer should apply.
- * Mailer creates and sends messages. Also it allows composition of the message
- * body via view rendering:
+ * MailerInterface is the interface that should be implemented by mailer classes.
  *
- * ~~~php
+ * 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,
+ *
+ * ~~~
  * Yii::$app->mail->compose('contact/html', ['contactForm' => $form])
- *     ->from('from@domain.com')
- *     ->to($form->email)
- *     ->subject($form->subject)
+ *     ->setFrom('from@domain.com')
+ *     ->setTo($form->email)
+ *     ->setSubject($form->subject)
  *     ->send();
  * ~~~
  *
@@ -28,17 +29,16 @@ namespace yii\mail;
 interface MailerInterface
 {
 	/**
-	 * Creates new message optionally filling up its body via view rendering.
-	 * The view to be rendered can be specified in one of the following formats:
-	 *
-	 * - path alias (e.g. "@app/mails/contact/body");
-	 * - relative path (e.g. "contact"): the actual view file will be resolved by [[\yii\base\ViewContextInterface]].
+	 * Creates a new message instance and optionally composes its body content via view rendering.
 	 *
-	 * @param string|array $view view, which should be used to render message body
+	 * @param string|array $view the view to be used for rendering the message body. This can be:
 	 *
-	 *  - if string - the view name or the path alias of the HTML body view file, in this case
-	 * text body will be composed automatically from html one.
-	 *  - if array - list of views for each body type in format: ['html' => 'htmlView', 'text' => 'textView']
+	 * - 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.
 	 *
 	 * @param array $params the parameters (name-value pairs) that will be extracted and made available in the view file.
 	 * @return MessageInterface message instance.
@@ -47,17 +47,18 @@ interface MailerInterface
 
 	/**
 	 * Sends the given email message.
-	 * @param object $message email message instance
-	 * @return boolean whether the message has been sent.
+	 * @param MessageInterface $message email message instance to be sent
+	 * @return boolean whether the message has been sent successfully
 	 */
 	public function send($message);
 
 	/**
-	 * Sends a couple of messages at once.
-	 * Note: some particular mailers may benefit from sending messages as batch,
-	 * saving resources, for example on open/close connection operations.
+	 * 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.
+	 *
 	 * @param array $messages list of email messages, which should be sent.
-	 * @return integer number of successful sends.
+	 * @return integer number of messages that are successfully sent.
 	 */
 	public function sendMultiple(array $messages);
 }

framework/yii/mail/MessageInterface.php

@@ -8,17 +8,20 @@
 namespace yii\mail;
 
 /**
- * MessageInterface is an interface, which email message should apply.
- * Together with application component, which matches the [[MailerInterface]],
- * it introduces following mail sending syntax:
+ * MessageInterface is the interface that should be implemented by mail message classes.
  *
- * ~~~php
+ * A message represents the settings and content of an email, such as the sender, recipient,
+ * subject, body, etc.
+ *
+ * Messages are sent by a [[MailerInterface||mailer]], like the following,
+ *
+ * ~~~
  * Yii::$app->mail->compose()
- *     ->from('from@domain.com')
- *     ->to('to@domain.com')
- *     ->subject('Message Subject')
- *     ->textBody('Plain text content')
- *     ->htmlBody('<b>HTML content</b>')
+ *     ->setFrom('from@domain.com')
+ *     ->setTo($form->email)
+ *     ->setSubject($form->subject)
+ *     ->setTextBody('Plain text content')
+ *     ->setHtmlBody('<b>HTML content</b>')
  *     ->send();
  * ~~~
  *
@@ -30,72 +33,124 @@ namespace yii\mail;
 interface MessageInterface
 {
 	/**
-	 * Set the character set of this message.
+	 * 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.
 	 * @param string $charset character set name.
 	 * @return static self reference.
 	 */
-	public function charset($charset);
+	public function setCharset($charset);
+
+	/**
+	 * Returns the message sender.
+	 * @return string the sender
+	 */
+	public function getFrom();
 
 	/**
-	 * Sets message sender.
+	 * Sets the 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].
+	 * `[email => name]`.
 	 * @return static self reference.
 	 */
-	public function from($from);
+	public function setFrom($from);
 
 	/**
-	 * Sets message receiver.
+	 * Returns the message recipient(s).
+	 * @return array the message recipients
+	 */
+	public function getTo();
+
+	/**
+	 * Sets the message recipient(s).
 	 * @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].
+	 * `[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]`.
 	 * @return static self reference.
 	 */
-	public function to($to);
+	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();
 
 	/**
-	 * Set the Cc (additional copy receiver) addresses of this message.
+	 * Sets 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].
+	 * `[email => name]`.
 	 * @return static self reference.
 	 */
-	public function cc($cc);
+	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();
 
 	/**
-	 * Set the Bcc (hidden copy receiver) addresses of this message.
+	 * Sets 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].
+	 * `[email => name]`.
 	 * @return static self reference.
 	 */
-	public function bcc($bcc);
+	public function setBcc($bcc);
+
+	/**
+	 * Returns the message subject.
+	 * @return string the message subject
+	 */
+	public function getSubject();
 
 	/**
-	 * Sets message subject.
+	 * Sets the message subject.
 	 * @param string $subject message subject
 	 * @return static self reference.
 	 */
-	public function subject($subject);
+	public function setSubject($subject);
 
 	/**
 	 * Sets message plain text content.
 	 * @param string $text message plain text content.
 	 * @return static self reference.
 	 */
-	public function textBody($text);
+	public function setTextBody($text);
 
 	/**
 	 * Sets message HTML content.
 	 * @param string $html message HTML content.
 	 * @return static self reference.
 	 */
-	public function htmlBody($html);
+	public function setHtmlBody($html);
 
 	/**
 	 * Attaches existing file to the email message.
@@ -149,7 +204,7 @@ interface MessageInterface
 
 	/**
 	 * Sends this email message.
-	 * @return boolean success.
+	 * @return boolean whether this message is sent successfully.
 	 */
 	public function send();
 

tests/unit/extensions/swiftmailer/MessageTest.php

@@ -124,11 +124,11 @@ class MessageTest extends VendorTestCase
 		$bcc = 'bccuser@somedomain.com';
 
 		$messageString = $this->createTestMessage()
-			->charset($charset)
-			->subject($subject)
-			->to($to)
-			->cc($cc)
-			->bcc($bcc)
+			->setCharset($charset)
+			->setSubject($subject)
+			->setTo($to)
+			->setCc($cc)
+			->setBcc($bcc)
 			->toString();
 
 		$this->assertContains('charset=' . $charset, $messageString, 'Incorrect charset!');
@@ -145,7 +145,7 @@ class MessageTest extends VendorTestCase
 	{
 		$from = 'someuser@somedomain.com';
 		$messageString = $this->createTestMessage()
-			->from($from)
+			->setFrom($from)
 			->toString();
 		$this->assertContains('From: ' . $from, $messageString, 'Incorrect "From" header!');
 		$this->assertContains('Reply-To: ' . $from, $messageString, 'Incorrect "Reply-To" header!');
@@ -157,10 +157,10 @@ class MessageTest extends VendorTestCase
 	public function testSend()
 	{
 		$message = $this->createTestMessage();
-		$message->to($this->testEmailReceiver);
-		$message->from('someuser@somedomain.com');
-		$message->subject('Yii Swift Test');
-		$message->textBody('Yii Swift Test body');
+		$message->setTo($this->testEmailReceiver);
+		$message->setFrom('someuser@somedomain.com');
+		$message->setSubject('Yii Swift Test');
+		$message->setTextBody('Yii Swift Test body');
 		$this->assertTrue($message->send());
 	}
 
@@ -171,10 +171,10 @@ class MessageTest extends VendorTestCase
 	{
 		$message = $this->createTestMessage();
 
-		$message->to($this->testEmailReceiver);
-		$message->from('someuser@somedomain.com');
-		$message->subject('Yii Swift Attach File Test');
-		$message->textBody('Yii Swift Attach File Test body');
+		$message->setTo($this->testEmailReceiver);
+		$message->setFrom('someuser@somedomain.com');
+		$message->setSubject('Yii Swift Attach File Test');
+		$message->setTextBody('Yii Swift Attach File Test body');
 		$fileName = __FILE__;
 		$message->attach($fileName);
 
@@ -192,10 +192,10 @@ class MessageTest extends VendorTestCase
 	{
 		$message = $this->createTestMessage();
 
-		$message->to($this->testEmailReceiver);
-		$message->from('someuser@somedomain.com');
-		$message->subject('Yii Swift Create Attachment Test');
-		$message->textBody('Yii Swift Create Attachment Test body');
+		$message->setTo($this->testEmailReceiver);
+		$message->setFrom('someuser@somedomain.com');
+		$message->setSubject('Yii Swift Create Attachment Test');
+		$message->setTextBody('Yii Swift Create Attachment Test body');
 		$fileName = 'test.txt';
 		$fileContent = 'Test attachment content';
 		$message->attachContent($fileContent, ['fileName' => $fileName]);
@@ -218,10 +218,10 @@ class MessageTest extends VendorTestCase
 
 		$cid = $message->embed($fileName);
 
-		$message->to($this->testEmailReceiver);
-		$message->from('someuser@somedomain.com');
-		$message->subject('Yii Swift Embed File Test');
-		$message->htmlBody('Embed image: <img src="' . $cid. '" alt="pic">');
+		$message->setTo($this->testEmailReceiver);
+		$message->setFrom('someuser@somedomain.com');
+		$message->setSubject('Yii Swift Embed File Test');
+		$message->setHtmlBody('Embed image: <img src="' . $cid. '" alt="pic">');
 
 		$this->assertTrue($message->send());
 
@@ -244,10 +244,10 @@ class MessageTest extends VendorTestCase
 
 		$cid = $message->embedContent($fileContent, ['fileName' => $fileName, 'contentType' => $contentType]);
 
-		$message->to($this->testEmailReceiver);
-		$message->from('someuser@somedomain.com');
-		$message->subject('Yii Swift Embed File Test');
-		$message->htmlBody('Embed image: <img src="' . $cid. '" alt="pic">');
+		$message->setTo($this->testEmailReceiver);
+		$message->setFrom('someuser@somedomain.com');
+		$message->setSubject('Yii Swift Embed File Test');
+		$message->setHtmlBody('Embed image: <img src="' . $cid. '" alt="pic">');
 
 		$this->assertTrue($message->send());
 
@@ -264,11 +264,11 @@ class MessageTest extends VendorTestCase
 	{
 		$message = $this->createTestMessage();
 
-		$message->to($this->testEmailReceiver);
-		$message->from('someuser@somedomain.com');
-		$message->subject('Yii Swift Alternative Body Test');
-		$message->htmlBody('<b>Yii Swift</b> test HTML body');
-		$message->textBody('Yii Swift test plain text body');
+		$message->setTo($this->testEmailReceiver);
+		$message->setFrom('someuser@somedomain.com');
+		$message->setSubject('Yii Swift Alternative Body Test');
+		$message->setHtmlBody('<b>Yii Swift</b> test HTML body');
+		$message->setTextBody('Yii Swift test plain text body');
 
 		$this->assertTrue($message->send());
 
@@ -297,10 +297,10 @@ class MessageTest extends VendorTestCase
 	{
 		$message = $this->createTestMessage();
 
-		$message->to($this->testEmailReceiver);
-		$message->from('someuser@somedomain.com');
-		$message->subject('Yii Swift Alternative Body Test');
-		$message->textBody('Yii Swift test plain text body');
+		$message->setTo($this->testEmailReceiver);
+		$message->setFrom('someuser@somedomain.com');
+		$message->setSubject('Yii Swift Alternative Body Test');
+		$message->setTextBody('Yii Swift test plain text body');
 
 		$serializedMessage = serialize($message);
 		$this->assertNotEmpty($serializedMessage, 'Unable to serialize message!');

tests/unit/framework/mail/BaseMailerTest.php

@@ -240,49 +240,49 @@ class Message extends BaseMessage
 	public $_textBody;
 	public $_htmlBody;
 
-	public function charset($charset)
+	public function setCharset($charset)
 	{
 		$this->_charset = $charset;
 		return $this;
 	}
 
-	public function from($from)
+	public function setFrom($from)
 	{
 		$this->_from = $from;
 		return $this;
 	}
 
-	public function to($to)
+	public function setTo($to)
 	{
 		$this->_to = $to;
 		return $this;
 	}
 
-	public function cc($cc)
+	public function setCc($cc)
 	{
 		$this->_cc = $cc;
 		return $this;
 	}
 
-	public function bcc($bcc)
+	public function setBcc($bcc)
 	{
 		$this->_bcc = $bcc;
 		return $this;
 	}
 
-	public function subject($subject)
+	public function setSubject($subject)
 	{
 		$this->_subject = $subject;
 		return $this;
 	}
 
-	public function textBody($text)
+	public function setTextBody($text)
 	{
 		$this->_textBody = $text;
 		return $this;
 	}
 
-	public function htmlBody($html)
+	public function setHtmlBody($html)
 	{
 		$this->_htmlBody = $html;
 		return $this;

tests/unit/framework/mail/BaseMessageTest.php

@@ -85,23 +85,23 @@ class TestMessage extends BaseMessage
 	public $text;
 	public $html;
 
-	public function charset($charset) {}
+	public function setCharset($charset) {}
 
-	public function from($from) {}
+	public function setFrom($from) {}
 
-	public function to($to) {}
+	public function setTo($to) {}
 
-	public function cc($cc) {}
+	public function setCc($cc) {}
 
-	public function bcc($bcc) {}
+	public function setBcc($bcc) {}
 
-	public function subject($subject) {}
+	public function setSubject($subject) {}
 
-	public function textBody($text) {
+	public function setTextBody($text) {
 		$this->text = $text;
 	}
 
-	public function htmlBody($html) {
+	public function setHtmlBody($html) {
 		$this->html = $html;
 	}