Skip to content
Permalink
Browse files

feature #33605 [Twig] Add NotificationEmail (fabpot)

This PR was merged into the 4.4 branch.

Discussion
----------

[Twig] Add NotificationEmail

| Q             | A
| ------------- | ---
| Branch?       | 4.4
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Tickets       | n/a
| License       | MIT
| Doc PR        | -

This PR is an extract of the new Notifier component. It's a default template to send standardized emails with the Mailer component, which can be used independently of the Notifier component.

Such emails look like the following:

<img width="618" alt="image" src="https://user-images.githubusercontent.com/47313/65018883-694cb780-d92a-11e9-940a-875ea68f9e5d.png">

More info on SpeakerDeck (be warned that names have change since my presentation): https://speakerdeck.com/fabpot/symfony-notifier?slide=7

It requires Twig 1.12 which should be released later this week.

Usage example:

```php
$email = (new NotificationEmail())
    ->from('fabien@example.com')
    ->to('fabien@example.org')
    ->subject('My first notification email via Symfony')
    ->markdown(<<<EOF
There is a **problem** on your website, you should investigate it right now.
Or just wait, the problem might solves itself automatically, we never know.
EOF
    )
    ->action('More info?', 'https://example.com/')
    ->importance('high')
    //->exception(new \LogicException('That does not work at all...'))
;
```

Instead of `markdown()`, you can also use `content()` for simple emails.

Note that you can use Inky tags in the content:

```php
$email = (new NotificationEmail())
    ->from('fabien@example.com')
    ->to('fabien@example.org')
    ->subject('My first notification email via Symfony')
    ->markdown(<<<EOF
There is a **problem** on your website, you should investigate it right now.
Or just wait, the problem might solves itself automatically, we never know.

Some Title
==========

<center>
    <button href="https://example.com/">Go?</button>
</center>

EOF
);
```

There is also the concept of a theme. By default, it uses the `default` theme,  which is an alias for the `zurb_2` theme.

You can use `setTheme()` to override the theme for a given instance, or override the themes globally via the following config in `twig.yaml`:

```yaml
twig:
    paths:
        templates/email: email
```

Then, create `templates/email/default/notification/body.html.twig` and `templates/email/default/notification/body.txt.twig`. Extends the existing template via `{% extends "@!email/default/notification/body.html.twig" %}` (note  the `!`).

Commits
-------

f6c6cf7 [Twig] Add NotificationEmail
  • Loading branch information...
fabpot committed Sep 18, 2019
2 parents 41a450b + f6c6cf7 commit 62304658384964781f02726af7998dc4b98ced06
@@ -29,6 +29,7 @@ install:
- echo max_execution_time=1200 >> php.ini-min
- echo date.timezone="America/Los_Angeles" >> php.ini-min
- echo extension_dir=ext >> php.ini-min
- echo extension=php_xsl.dll >> php.ini-min
- copy /Y php.ini-min php.ini-max
- echo zend_extension=php_opcache.dll >> php.ini-max
- echo opcache.enable_cli=1 >> php.ini-max
@@ -119,7 +119,10 @@
"egulias/email-validator": "~1.2,>=1.2.8|~2.0",
"symfony/phpunit-bridge": "^3.4.31|^4.3.4|~5.0",
"symfony/security-acl": "~2.8|~3.0",
"phpdocumentor/reflection-docblock": "^3.0|^4.0"
"phpdocumentor/reflection-docblock": "^3.0|^4.0",
"twig/cssinliner-extra": "^2.12",
"twig/inky-extra": "^2.12",
"twig/markdown-extra": "^2.12"
},
"conflict": {
"masterminds/html5": "<2.6",
@@ -47,7 +47,7 @@ public function render(Message $message): void
$messageContext = $message->getContext();
if (isset($messageContext['email'])) {
throw new InvalidArgumentException(sprintf('A "%s" context cannot have an "email" entry as this is a reserved variable.', TemplatedEmail::class));
throw new InvalidArgumentException(sprintf('A "%s" context cannot have an "email" entry as this is a reserved variable.', \get_class($message)));
}
$vars = array_merge($this->context, $messageContext, [
@@ -0,0 +1,216 @@
<?php
/*
* This file is part of the Symfony package.
*
* (c) Fabien Potencier <fabien@symfony.com>
*
* For the full copyright and license information, please view the LICENSE
* file that was distributed with this source code.
*/
namespace Symfony\Bridge\Twig\Mime;
use Symfony\Component\ErrorRenderer\Exception\FlattenException;
use Symfony\Component\Mime\Header\Headers;
use Symfony\Component\Mime\Part\AbstractPart;
use Twig\Extra\CssInliner\CssInlinerExtension;
use Twig\Extra\Inky\InkyExtension;
use Twig\Extra\Markdown\MarkdownExtension;
/**
* @author Fabien Potencier <fabien@symfony.com>
*/
class NotificationEmail extends TemplatedEmail
{
public const IMPORTANCE_URGENT = 'urgent';
public const IMPORTANCE_HIGH = 'high';
public const IMPORTANCE_MEDIUM = 'medium';
public const IMPORTANCE_LOW = 'low';
private $theme = 'default';
private $context = [
'importance' => self::IMPORTANCE_LOW,
'content' => '',
'exception' => false,
'action_text' => null,
'action_url' => null,
'markdown' => false,
'raw' => false,
];
public function __construct(Headers $headers = null, AbstractPart $body = null)
{
if (!class_exists(CssInlinerExtension::class)) {
throw new \LogicException(sprintf('You cannot use "%s" if the CSS Inliner Twig extension is not available; try running "composer require twig/cssinliner-extra".', static::class));
}
if (!class_exists(InkyExtension::class)) {
throw new \LogicException(sprintf('You cannot use "%s" if the Inky Twig extension is not available; try running "composer require twig/inky-extra".', static::class));
}
parent::__construct($headers, $body);
}
/**
* @return $this
*/
public function markdown(string $content)
{
if (!class_exists(MarkdownExtension::class)) {
throw new \LogicException(sprintf('You cannot use "%s" if the Markdown Twig extension is not available; try running "composer require twig/markdown-extra".', __METHOD__));
}
$this->context['markdown'] = true;
return $this->content($content);
}
/**
* @return $this
*/
public function content(string $content, bool $raw = false)
{
$this->context['content'] = $content;
$this->context['raw'] = $raw;
return $this;
}
/**
* @return $this
*/
public function action(string $text, string $url)
{
$this->context['action_text'] = $text;
$this->context['action_url'] = $url;
return $this;
}
/**
* @return self
*/
public function importance(string $importance)
{
$this->context['importance'] = $importance;
return $this;
}
/**
* @param \Throwable|FlattenException
*
* @return $this
*/
public function exception($exception)
{
$exceptionAsString = $this->getExceptionAsString($exception);
$this->context['exception'] = true;
$this->attach($exceptionAsString, 'exception.txt', 'text/plain');
$this->importance(self::IMPORTANCE_URGENT);
if (!$this->getSubject()) {
$this->subject($exception->getMessage());
}
return $this;
}
/**
* @return $this
*/
public function theme(string $theme)
{
$this->theme = $theme;
return $this;
}
public function getTextTemplate(): ?string
{
if ($template = parent::getTextTemplate()) {
return $template;
}
return '@email/'.$this->theme.'/notification/body.txt.twig';
}
public function getHtmlTemplate(): ?string
{
if ($template = parent::getHtmlTemplate()) {
return $template;
}
return '@email/'.$this->theme.'/notification/body.html.twig';
}
public function getContext(): array
{
return array_merge($this->context, parent::getContext());
}
public function getPreparedHeaders(): Headers
{
$headers = parent::getPreparedHeaders();
$importance = $this->context['importance'] ?? IMPORTANCE_LOW;
$this->priority($this->determinePriority($importance));
$headers->setHeaderBody('Text', 'Subject', sprintf('[%s] %s', strtoupper($importance), $this->getSubject()));
return $headers;
}
private function determinePriority(string $importance): int
{
switch ($importance) {
case self::IMPORTANCE_URGENT:
return self::PRIORITY_HIGHEST;
case self::IMPORTANCE_HIGH:
return self::PRIORITY_HIGH;
case self::IMPORTANCE_MEDIUM:
return self::PRIORITY_NORMAL;
case self::IMPORTANCE_LOW:
default:
return self::PRIORITY_LOW;
}
}
private function getExceptionAsString($exception): string
{
if (class_exists(FlattenException::class)) {
$exception = $exception instanceof FlattenException ? $exception : FlattenException::createFromThrowable($exception);
return $exception->getAsString();
}
$message = \get_class($exception);
if ('' != $exception->getMessage()) {
$message .= ': '.$exception->getMessage();
}
$message .= ' in '.$exception->getFile().':'.$exception->getLine()."\n";
$message .= "Stack trace:\n".$exception->getTraceAsString()."\n\n";
return rtrim($message);
}
/**
* @internal
*/
public function __serialize(): array
{
return [$this->context, parent::__serialize()];
}
/**
* @internal
*/
public function __unserialize(array $data): void
{
[$this->context, $parentData] = $data;
parent::__unserialize($parentData);
}
}
@@ -0,0 +1 @@
{% extends "@email/zurb_2/notification/body.html.twig" %}
@@ -0,0 +1 @@
{% extends "@email/zurb_2/notification/body.txt.twig" %}

0 comments on commit 6230465

Please sign in to comment.
You can’t perform that action at this time.