diff --git a/README.md b/README.md index b18d047..5a51413 100644 --- a/README.md +++ b/README.md @@ -55,6 +55,9 @@ return [ ]; ``` +> Note: please refer to the [Symfony Mailer Manual](https://symfony.com/doc/current/mailer.html#transport-setup) for the instructions + regarding the transport DSN specification. + Usage example: ```php @@ -75,6 +78,8 @@ Yii::app()->mailer->send($email); ### Configuring Emails Globally +In order to simplify the code and avoid its duplication, you can set the default headers, which should be applied for +each sending email. Application configuration example: ```php @@ -99,6 +104,10 @@ return [ ### Template rendering +You may specify the content for the email body to be a result of rendering a particular view templates. +It works in the similar way as rendering the views in your Web controllers. +You'll need to use `\yii1tech\mailer\TemplatedEmail` in order to specify the templates. + ```php addFrom('noreply@example.com') ->addTo('johndoe@example.com') ->subject('Greetings') - ->textTemplate('greetings-text') - ->htmlTemplate('greetings-html') + ->textTemplate('greetings-text') // Text Body will be set as render of 'views/mail/greetings-text.php' + ->htmlTemplate('greetings-html') // HTML Body will be set as render of 'views/mail/greetings-html.php' ->context([ - 'name' => 'John Doe', + 'name' => 'John Doe', // variables, which will be available inside the templates ]); -Yii::app()->mailer->send($email); +Yii::app()->mailer->send($email); // actual rendering takes place just before the sending +``` + +By default, the view templates will be searched in the directory "views/mail" in the application base path. +But you may configure `\yii1tech\mailer\Mailer::$view` component to use a different folder. +You can also set a global layout for all template rendering. +Application configuration example: + +```php + [ + 'mailer' => [ + 'class' => yii1tech\mailer\Mailer, + 'view' => [ + 'viewPath' => dirname(__DIR__) . '/views/mail', + 'layout' => 'default-layout', + ], + // ... + ], + ], + // ... +]; ``` ### Writing unit tests +You can use `\yii1tech\mailer\transport\ArrayTransport` while writing unit tests for your application. +This transport will store all incoming email messages inside the internal field instead of actual sending them. +Application configuration example: + ```php mailer->getTransport(); - /** @var \Symfony\Component\Mime\Email $sentMessage */ - $sentMessage = Yii::app()->mailer->getTransport()->getLastSentMessage(); + // retrieve the last sent email message: + $sentMessage = $transport->getLastSentMessage(); $this->assetNotNull($sentMessage); $this->assertSame('johndoe@example.com', $sentMessage->getTo()[0]->getAddress()); // ... + + // retrieve the all sent email messages. matching the callback condition: + $messages = $transport->filterSentMessages(function (Email $message) { + return $message->getSubject() === 'Greetings'; + }); + $this->assertCount(1, $messages); + // ... } } ```