From d046f9dbbff6a27c5697d044c802ccba8ec2a64d Mon Sep 17 00:00:00 2001
From: Paul Klimov <klimov.paul@gmail.com>
Date: Thu, 9 May 2024 18:24:02 +0300
Subject: [PATCH] add docs

---
 src/Mailer.php         | 51 ++++++++++++++++++++++++++++++++++++++----
 src/TemplatedEmail.php | 15 +++++++++++++
 src/View.php           |  7 ++++--
 tests/MailerTest.php   |  1 -
 4 files changed, 67 insertions(+), 7 deletions(-)

diff --git a/src/Mailer.php b/src/Mailer.php
index 082a2be..727b1bf 100644
--- a/src/Mailer.php
+++ b/src/Mailer.php
@@ -12,6 +12,39 @@
 use yii1tech\mailer\transport\ArrayTransport;
 
 /**
+ * Mailer allows email sending.
+ *
+ * Application configuration example:
+ *
+ * ```
+ * return [
+ *     'components' => [
+ *         'mailer' => [
+ *             'class' => yii1tech\mailer\Mailer,
+ *             'dsn' => 'smtp://user:pass@smtp.example.com:25',
+ *             'view' => [
+ *                 'layout' => 'default-layout',
+ *             ],
+ *         ],
+ *     ],
+ *     // ...
+ * ];
+ * ```
+ *
+ * Usage example:
+ *
+ * ```
+ * use Symfony\Component\Mime\Email;
+ *
+ * $email = (new Email())
+ *     ->addFrom('noreply@example.com')
+ *     ->addTo('test@example.com')
+ *     ->subject('Test subject')
+ *     ->text('Test body');
+ *
+ * Yii::app()->mailer->send($email);
+ * ```
+ *
  * @see https://symfony.com/doc/current/mailer.html
  *
  * @author Paul Klimov <klimov.paul@gmail.com>
@@ -57,10 +90,15 @@ class Mailer extends CApplicationComponent
     /**
      * @var \yii1tech\mailer\View|array view instance or its array configuration.
      */
-    private $_view = [
-        'class' => View::class,
-    ];
+    private $_view = [];
 
+    /**
+     * Sends the given message.
+     *
+     * @param \Symfony\Component\Mime\RawMessage|\Symfony\Component\Mime\Email|\yii1tech\mailer\TemplatedEmailContract $message message to be sent.
+     * @param \Symfony\Component\Mailer\Envelope|null $envelope envelope instance.
+     * @return void
+     */
     public function send(RawMessage $message, ?Envelope $envelope = null): void
     {
         foreach ($this->defaultHeaders as $name => $value) {
@@ -160,7 +198,12 @@ protected function createTransport($config): TransportInterface
     public function getView()
     {
         if (!is_object($this->_view)) {
-            $this->_view = Yii::createComponent($this->_view);
+            $config = $this->_view;
+            if (is_array($config) && !isset($config['class'])) {
+                $config['class'] = View::class;
+            }
+
+            $this->_view = Yii::createComponent($config);
         }
 
         return $this->_view;
diff --git a/src/TemplatedEmail.php b/src/TemplatedEmail.php
index 85bd5ed..4675b79 100644
--- a/src/TemplatedEmail.php
+++ b/src/TemplatedEmail.php
@@ -7,6 +7,21 @@
 /**
  * TemplatedEmail allows specification of the email body parts as a rendering of the templates.
  *
+ * Usage example:
+ *
+ * ```
+ * $email = (new TemplatedEmail())
+ *     ->addTo('test@example.com')
+ *     ->subject('Greetings')
+ *     ->textTemplate('greetings-text')
+ *     ->htmlTemplate('greetings-html')
+ *     ->context([
+ *         'name' => 'John Doe',
+ *     ]);
+ *
+ * Yii::app()->mailer->send($email);
+ * ```
+ *
  * @see \yii1tech\mailer\View
  *
  * @author Paul Klimov <klimov.paul@gmail.com>
diff --git a/src/View.php b/src/View.php
index b5a8a67..74affd9 100644
--- a/src/View.php
+++ b/src/View.php
@@ -8,6 +8,10 @@
 /**
  * View is a email template view renderer.
  *
+ * Instance of this class will be available inside the view templates as `$this` variable.
+ *
+ * This class uses the custom view renderer, if it is set at the application level.
+ *
  * @property string $viewPath the root directory of view files. Defaults to 'views/mail' under the application base path.
  * @property \IViewRenderer|\CViewRenderer|array|string|null|false $viewRenderer view renderer or its array configuration.
  *
@@ -59,7 +63,7 @@ public function setViewPath(string $viewPath): self
 
     /**
      * Returns the view renderer - a component whose wants to replace the default view rendering logic.
-     * By default the application 'viewRenderer' component will be used, if it has been set.
+     * By default, the application 'viewRenderer' component will be used, if it has been set.
      *
      * @return \IViewRenderer|\CViewRenderer|null|false view renderer.
      */
@@ -205,7 +209,6 @@ public function render(string $view, ?array $data = null, ?string $locale = null
      * @param array|null $data data to be extracted into PHP variables and made available to the view script.
      * @param bool $return whether the rendering result should be returned instead of being sent to output.
      * @return string|null the rendering result. `Null` if the rendering result is not required.
-     * @throws \CException
      */
     public function renderPartial(string $view, ?array $data = null, bool $return = false)
     {
diff --git a/tests/MailerTest.php b/tests/MailerTest.php
index b091dc9..74db5ac 100644
--- a/tests/MailerTest.php
+++ b/tests/MailerTest.php
@@ -111,7 +111,6 @@ public function testSetupView(): void
         $mailer = Yii::createComponent([
             'class' => Mailer::class,
             'view' => [
-                'class' => View::class,
                 'layout' => 'test-layout',
             ],
         ]);