Proposal for #31

.travis.yml

@@ -18,7 +18,7 @@ before_script:
   - tests/unit/data/travis/cubrid-setup.sh
 
 script:
-  - phpunit --coverage-clover tests/unit/runtime/coveralls/clover.xml --verbose --exclude-group mssql,oci,wincache,xcache,zenddata
+  - phpunit --coverage-clover tests/unit/runtime/coveralls/clover.xml --verbose --exclude-group mssql,oci,wincache,xcache,zenddata,swiftmailer
 
 after_script:
   - php vendor/bin/coveralls

framework/yii/email/BaseMailer.php

@@ -0,0 +1,81 @@
+<?php
+/**
+ * @link http://www.yiiframework.com/
+ * @copyright Copyright (c) 2008 Yii Software LLC
+ * @license http://www.yiiframework.com/license/
+ */
+
+namespace yii\email;
+
+use yii\base\Component;
+
+/**
+ * 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.
+ *
+ * @see BaseMessage
+ *
+ * @property array $defaultMessageConfig configuration, which should be applied by default to any
+ * new created email message instance.
+ *
+ * @author Paul Klimov <klimov.paul@gmail.com>
+ * @since 2.0
+ */
+abstract class BaseMailer extends Component
+{
+	/**
+	 * @var array configuration, which should be applied by default to any new created
+	 * email message instance.
+	 * For example:
+	 * ~~~
+	 * array(
+	 *     'encoding' => 'UTF-8',
+	 *     'from' => 'noreply@mydomain.com',
+	 *     'bcc' => 'email.test@mydomain.com',
+	 * )
+	 * ~~~
+	 */
+	private $_defaultMessageConfig = array();
+
+	/**
+	 * @param array $defaultMessageConfig default message config
+	 */
+	public function setDefaultMessageConfig(array $defaultMessageConfig)
+	{
+		$this->_defaultMessageConfig = $defaultMessageConfig;
+	}
+
+	/**
+	 * @return array default message config
+	 */
+	public function getDefaultMessageConfig()
+	{
+		return $this->_defaultMessageConfig;
+	}
+
+	/**
+	 * Sends the given email message.
+	 * @param object $message email message instance
+	 * @return boolean whether the message has been sent.
+	 */
+	abstract 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,
+	 * they may override this method to create their specific implementation.
+	 * @param array $messages list of email messages, which should be sent.
+	 * @return integer number of successfull sends
+	 */
+	public function sendMultiple(array $messages) {
+		$successCount = 0;
+		foreach ($messages as $message) {
+			if ($this->send($message)) {
+				$successCount++;
+			}
+		}
+		return $successCount;
+	}
+}

framework/yii/email/BaseMessage.php

@@ -0,0 +1,125 @@
+<?php
+/**
+ * @link http://www.yiiframework.com/
+ * @copyright Copyright (c) 2008 Yii Software LLC
+ * @license http://www.yiiframework.com/license/
+ */
+
+namespace yii\email;
+
+use yii\base\InvalidParamException;
+use yii\base\Object;
+use yii\helpers\FileHelper;
+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.
+ *
+ * @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 $subject message subject.
+ * @property string $text message plain text content.
+ * @property string $html message HTML content.
+ *
+ * @author Paul Klimov <klimov.paul@gmail.com>
+ * @since 2.0
+ */
+abstract class BaseMessage extends Object
+{
+	/**
+	 * @return \yii\email\BaseMailer
+	 */
+	public function getMailer()
+	{
+		return Yii::$app->getComponent('email');
+	}
+
+	/**
+	 * Initializes the object.
+	 * This method is invoked at the end of the constructor after the object is initialized with the
+	 * given configuration.
+	 */
+	public function init()
+	{
+		Yii::configure($this, $this->getMailer()->getDefaultMessageConfig());
+	}
+
+	/**
+	 * Sends this email message.
+	 * @return boolean success.
+	 */
+	public function send()
+	{
+		return $this->getMailer()->send($this);
+	}
+
+	/**
+	 * 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);
+
+	/**
+	 * 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.
+	 */
+	public function attachFile($fileName, $contentType = null, $attachFileName = null)
+	{
+		if (!file_exists($fileName)) {
+			throw new InvalidParamException('Unable to attach file "' . $fileName . '": file does not exists!');
+		}
+		if (empty($contentType)) {
+			$contentType = FileHelper::getMimeType($fileName);
+		}
+		if (empty($attachFileName)) {
+			$attachFileName = basename($fileName);
+		}
+		$content = file_get_contents($fileName);
+		$this->createAttachment($content, $attachFileName, $contentType);
+	}
+}

framework/yii/email/Message.php

@@ -0,0 +1,34 @@
+<?php
+/**
+ * @link http://www.yiiframework.com/
+ * @copyright Copyright (c) 2008 Yii Software LLC
+ * @license http://www.yiiframework.com/license/
+ */
+
+namespace yii\email;
+
+use yii\email\swift\Message as SwiftMessage;
+
+/**
+ * Message provides the email message sending functionality.
+ *
+ * Usage:
+ * ~~~
+ * $email = new Message();
+ * $email->from = 'sender@domain.com';
+ * $email->to = 'receiver@domain.com';
+ * $email->subject = 'Message Subject';
+ * $email->text = 'Message Content';
+ * $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]]:
+ * ~~~
+ * Yii::$classMap['yii\email\Message'] = '/path/to/my/email/Message.php'
+ * ~~~
+ *
+ * @author Paul Klimov <klimov.paul@gmail.com>
+ * @since 2.0
+ */
+class Message extends SwiftMessage {}

framework/yii/email/VendorMailer.php

@@ -0,0 +1,104 @@
+<?php
+/**
+ * @link http://www.yiiframework.com/
+ * @copyright Copyright (c) 2008 Yii Software LLC
+ * @license http://www.yiiframework.com/license/
+ */
+
+namespace yii\email;
+
+use yii\base\InvalidConfigException;
+
+/**
+ * VendorMailer is a base class for the mailers, which use external library (vendor)
+ * to perform their job.
+ * This class provides the ability to compose and wrap the actual email mailer
+ * and message under the basic interface.
+ *
+ * @see VendorMessage
+ *
+ * @property array|object $vendorMailer vendor mailer instance or its array configuration.
+ *
+ * @author Paul Klimov <klimov.paul@gmail.com>
+ * @since 2.0
+ */
+abstract class VendorMailer extends BaseMailer
+{
+	/**
+	 * @var string|callback vendor autoloader callback or path to autoloader file.
+	 * If the vendor classes autoloading is already managed in some other place,
+	 * for example via Composer, you should leave this field blank.
+	 */
+	public $autoload;
+	/**
+	 * @var array|object vendor mailer instance or its array configuration.
+	 * Note: different implementation of [[VendorMailer]] may process configuration
+	 * in the different way.
+	 */
+	private $_vendorMailer = array();
+
+	/**
+	 * Initializes the object.
+	 * Registers the vendor autoloader, if any.
+	 */
+	public function init()
+	{
+		$this->setupVendorAutoload();
+	}
+
+	/**
+	 * @param array|object $value mailer instance or configuration.
+	 * @throws \yii\base\InvalidConfigException on invalid argument.
+	 */
+	public function setVendorMailer($value)
+	{
+		if (!is_array($value) && !is_object($value)) {
+			throw new InvalidConfigException('"' . get_class($this) . '::vendorMailer" should be either object or array, "' . gettype($value) . '" given.');
+		}
+		$this->_vendorMailer = $value;
+	}
+
+	/**
+	 * @return object vendor mailer instance.
+	 */
+	public function getVendorMailer()
+	{
+		if (!is_object($this->_vendorMailer)) {
+			$this->_vendorMailer = $this->createVendorMailer($this->_vendorMailer);
+		}
+		return $this->_vendorMailer;
+	}
+
+	/**
+	 * Sets up the vendor autoloader, if any is specified.
+	 */
+	protected function setupVendorAutoload()
+	{
+		if (!empty($this->autoload)) {
+			if (is_string($this->autoload) && file_exists($this->autoload)) {
+				if (file_exists($this->autoload)) {
+					require_once($this->autoload);
+				} elseif (function_exists($this->autoload)) {
+					spl_autoload_register($this->autoload);
+				} else {
+					throw new InvalidConfigException('"' . get_class($this) . '::autoload" value "' . $this->autoload . '" is invalid: no such function or file exists.');
+				}
+			} else {
+				spl_autoload_register($this->autoload);
+			}
+		}
+	}
+
+	/**
+	 * Creates vendor mailer instance from given configuration.
+	 * @param array $config mailer configuration.
+	 * @return object mailer instance.
+	 */
+	abstract protected function createVendorMailer(array $config);
+
+	/**
+	 * Creates the vendor email message instance.
+	 * @return object email message instance.
+	 */
+	abstract public function createVendorMessage();
+}