php/yii2
1
0
Fork 0
mirror of https://github.com/yiisoft/yii2.git synced 2025-11-10 02:13:17 +08:00
Code Issues Packages Projects Releases Wiki Activity

Refactored mail.

Browse Source
This commit is contained in:
Qiang Xue
2013-11-07 22:33:57 -05:00
parent ed0e44d23b
commit 90a5bcc611
9 changed files with 338 additions and 195 deletions
Download Patch File Download Diff File Expand all files Collapse all files

138
framework/yii/mail/BaseMailer.php
View File

@ -11,15 +11,16 @@ use Yii;
use yii\base\Component;
use yii\base\InvalidConfigException;
use yii\base\ViewContextInterface;
use yii\web\View;
/**
* BaseMailer provides the basic interface for the email mailer application component.
* It provides the default configuration for the email messages.
* Particular implementation of mailer should provide implementation for the [[send()]] method.
* BaseMailer serves as a base class that implements the basic functions required by [[MailerInterface]].
*
* Concrete child classes should may focus on implementing the [[send()]] method.
*
* @see BaseMessage
*
* @property \yii\base\View|array $view view instance or its array configuration.
* @property View|array $view view instance or its array configuration.
*
* @author Paul Klimov <klimov.paul@gmail.com>
* @since 2.0
@ -32,60 +33,59 @@ abstract class BaseMailer extends Component implements MailerInterface, ViewCont
private $_view = [];
/**
* @var string directory containing view files for this email messages.
* This can be specified as an absolute path or path alias.
*/
public $viewPath = '@app/mails';
/**
* @var string HTML layout view name.
* @var string|boolean HTML layout view name. This is the layout used to render HTML mail body.
* The property can take the following values:
*
* - a relative view name: a view file relative to [[viewPath]], e.g., 'layouts/html'.
* - a path alias: an absolute view file path specified as a path alias, e.g., '@app/mails/html'.
* - a boolean false: the layout is disabled.
*/
public $htmlLayout = 'layouts/html';
/**
* @var string text layout view name.
* @var string|boolean text layout view name. This is the layout used to render TEXT mail body.
* Please refer to [[htmlLayout]] for possible values that this property can take.
*/
public $textLayout = 'layouts/text';
/**
* @var array configuration, which should be applied by default to any new created
* email message instance.
* In addition to normal [[Yii::createObject()]] behavior extra config keys are available:
*
* - 'charset' argument for [[MessageInterface::charset()]]
* - 'from' argument for [[MessageInterface::from()]]
* - 'to' argument for [[MessageInterface::to()]]
* - 'cc' argument for [[MessageInterface::cc()]]
* - 'bcc' argument for [[MessageInterface::bcc()]]
* - 'subject' argument for [[MessageInterface::subject()]]
* - 'textBody' argument for [[MessageInterface::textBody()]]
* - 'htmlBody' argument for [[MessageInterface::htmlBody()]]
* @var array the configuration that should be applied to any newly created
* email message instance by [[createMessage()]] or [[compose()]]. Any valid property defined
* by [[MessageInterface]] can be configured, such as `from`, `to`, `subject`, `textBody`, `htmlBody`, etc.
*
* For example:
*
* ~~~
* array(
* [
* 'charset' => 'UTF-8',
* 'from' => 'noreply@mydomain.com',
* 'bcc' => 'developer@mydomain.com',
* )
* ]
* ~~~
*/
public $messageConfig = [];
/**
* @var string message default class name.
* @var string the default class name of the new message instances created by [[createMessage()]]
*/
public $messageClass = 'yii\mail\BaseMessage';
/**
* @param array|\yii\base\View $view view instance or its array configuration.
* @throws \yii\base\InvalidConfigException on invalid argument.
* @param array|View $view view instance or its array configuration that will be used to
* render message bodies.
* @throws InvalidConfigException on invalid argument.
*/
public function setView($view)
{
if (!is_array($view) && !is_object($view)) {
throw new InvalidConfigException('"' . get_class($this) . '::view" should be either object or array, "' . gettype($view) . '" given.');
throw new InvalidConfigException('"' . get_class($this) . '::view" should be either object or configuration array, "' . gettype($view) . '" given.');
}
$this->_view = $view;
}
/**
* @return \yii\base\View view instance.
* @return View view instance.
*/
public function getView()
{
@ -98,18 +98,35 @@ abstract class BaseMailer extends Component implements MailerInterface, ViewCont
/**
* Creates view instance from given configuration.
* @param array $config view configuration.
* @return \yii\base\View view instance.
* @return View view instance.
*/
protected function createView(array $config)
{
if (!array_key_exists('class', $config)) {
$config['class'] = 'yii\web\View';
$config['class'] = View::className();
}
return Yii::createObject($config);
}
/**
* @inheritdoc
* Creates a new message instance and optionally composes its body content via view rendering.
*
* @param string|array $view the view to be used for rendering the message body. This can be:
*
* - 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.
*
* The view to be rendered can be specified in one of the following formats:
*
* - path alias (e.g. "@app/mails/contact");
* - a relative view name (e.g. "contact"): the actual view file will be resolved by [[findViewFile()]]
*
* @param array $params the parameters (name-value pairs) that will be extracted and made available in the view file.
* @return MessageInterface message instance.
*/
public function compose($view = null, array $params = [])
{
@ -117,24 +134,32 @@ abstract class BaseMailer extends Component implements MailerInterface, ViewCont
if ($view !== null) {
$params['message'] = $message;
if (is_array($view)) {
if (array_key_exists('html', $view)) {
$message->htmlBody($this->render($view['html'], $params, $this->htmlLayout));
if (isset($view['html'])) {
$html = $this->render($view['html'], $params, $this->htmlLayout);
}
if (array_key_exists('text', $view)) {
$message->textBody($this->render($view['text'], $params, $this->textLayout));
if (isset($view['text'])) {
$text = $this->render($view['text'], $params, $this->textLayout);
}
} else {
$html = $this->render($view, $params, $this->htmlLayout);
$message->htmlBody($html);
$message->textBody(strip_tags($html));
}
if (isset($html)) {
$message->setHtmlBody($html);
}
if (isset($text)) {
$message->setTextBody($text);
} elseif (isset($html)) {
$message->setTextBody(strip_tags($html));
}
}
return $message;
}
/**
* Creates mew message instance using configuration from [[messageConfig]].
* If 'class' parameter is omitted, [[messageClass]] will be used.
* Creates a new message instance.
* The newly created instance will be initialized with the configuration specified by [[messageConfig]].
* If the configuration does not specify a 'class', the [[messageClass]] will be used as the class
* of the new message instance.
* @return MessageInterface message instance.
*/
protected function createMessage()
@ -143,37 +168,18 @@ abstract class BaseMailer extends Component implements MailerInterface, ViewCont
if (!array_key_exists('class', $config)) {
$config['class'] = $this->messageClass;
}
$directSetterNames = [
'charset',
'from',
'to',
'cc',
'bcc',
'subject',
'textBody',
'htmlBody',
];
$directSetterConfig = [];
foreach ($config as $name => $value) {
if (in_array($name, $directSetterNames, true)) {
$directSetterConfig[$name] = $value;
unset($config[$name]);
}
}
$message = Yii::createObject($config);
foreach ($directSetterConfig as $name => $value) {
$message->$name($value);
}
return $message;
return Yii::createObject($config);
}
/**
* 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,
* they may override this method to create their specific implementation.
* Sends multiple messages at once.
*
* The default implementation simply calls [[send()]] multiple times.
* Child classes may override this method to implement more efficient way of
* sending multiple messages.
*
* @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)
{
@ -187,10 +193,11 @@ abstract class BaseMailer extends Component implements MailerInterface, ViewCont
}
/**
* Renders a view.
* Renders the specified view with optional parameters and layout.
* The view will be rendered using the [[view]] component.
* @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.
* @param string|boolean $layout layout view name, if false given no layout will be applied.
* @param string|boolean $layout layout view name or path alias. If false, no layout will be applied.
* @return string the rendering result.
*/
public function render($view, $params = [], $layout = false)
@ -205,6 +212,7 @@ abstract class BaseMailer extends Component implements MailerInterface, ViewCont
/**
* Finds the view file corresponding to the specified relative view name.
* This method will return the view file by prefixing the view name with [[viewPath]].
* @param string $view a relative view name. The name does NOT start with a slash.
* @return string the view file path. Note that the file may not exist.
*/

12
framework/yii/mail/BaseMessage.php
View File

@ -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()
{

45
framework/yii/mail/MailerInterface.php
View File

@ -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);
}

111
framework/yii/mail/MessageInterface.php
View File

@ -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();