Skip to content

Y
yii2
Commit 90a5bcc6 by Qiang Xue
Options

Refactored mail.

parent ed0e44d2
Showing with 338 additions and 199 deletions
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;
......@@ -234,4 +298,4 @@ class Message extends BaseMessage
{
return new \Swift_Message();
}
}
\ No newline at end of file
}
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!');
......@@ -308,4 +308,4 @@ class MessageTest extends VendorTestCase
$unserializedMessaage = unserialize($serializedMessage);
$this->assertEquals($message, $unserializedMessaage, 'Unable to unserialize message!');
}
}
\ No newline at end of file
}
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;
......@@ -300,4 +300,4 @@ class Message extends BaseMessage
{
return get_class($this);
}
}
\ No newline at end of file
}
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;
}
......@@ -117,4 +117,4 @@ class TestMessage extends BaseMessage
{
return get_class($this);
}
}
\ No newline at end of file
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment