feat: markdown in email body for mailing and transactional

src/Email/EmailTextRenderer.php

@@ -8,12 +8,12 @@ use App\Model\RenderedEmailTextDto;
 use App\Repository\EmailTextRepository;
 
 /**
- * Turns the plain text an admin wrote into the HTML of a transactional mail.
+ * Turns the text an admin wrote into the HTML of a transactional mail.
  *
- * Admins write plain text with {placeholder} tokens and *bold* markers - never markup,
- * never Twig. Everything an admin or a teamer typed is escaped here before any tag is
- * introduced, which is the only reason email/generic.html.twig may print the result with
- * |raw. The order of operations below is load-bearing; see the comments on each step.
+ * Admins write Markdown with {placeholder} tokens - never markup, never Twig. The body is
+ * handed to App\Email\MailBodyRenderer, which is where the escaping that makes
+ * email/generic.html.twig's |raw safe happens; subject and headline are plain text and
+ * are dealt with here.
  */
 class EmailTextRenderer
 {
@@ -32,6 +32,7 @@ class EmailTextRenderer
     public function __construct(
         private readonly EmailTextCatalog $catalog,
         private readonly EmailTextRepository $emailTextRepository,
+        private readonly MailBodyRenderer $mailBodyRenderer,
     ) {
     }
 
@@ -68,103 +69,39 @@ class EmailTextRenderer
     ): RenderedEmailTextDto {
         $definition = $this->catalog->get($key);
 
-        // Two token maps from the same values: the subject of a mail is plain text, the
-        // body is HTML. Escaping happens here, before substitution, so that neither the
-        // admin's copy nor a teamer's own words (reason, comment, specialAgreements) can
-        // introduce a tag.
-        $plainTokens = [];
+        // Three token maps from the same values, because the three parts of a mail are not
+        // the same kind of text: the subject is a plain header, the headline is escaped
+        // plain text, and the body is Markdown the renderer escapes for us.
+        $rawTokens = [];
         $htmlTokens = [];
 
         foreach ($definition->getPlaceholderNames() as $name) {
             $value = (string) ($placeholders[$name] ?? '');
             $value = '' === trim($value) ? self::EMPTY_VALUE : $value;
 
-            $plainTokens['{'.$name.'}'] = $value;
+            $rawTokens['{'.$name.'}'] = $value;
             $htmlTokens['{'.$name.'}'] = htmlspecialchars($value, self::ESCAPE_FLAGS, 'UTF-8');
         }
 
         return new RenderedEmailTextDto(
-            strtr($subject ?? '', $plainTokens),
-            $this->prepare($headline ?? '', $htmlTokens),
-            $this->renderBody($body ?? '', $htmlTokens),
+            strtr($subject ?? '', $rawTokens),
+            $this->renderHeadline($headline ?? '', $htmlTokens),
+            $this->mailBodyRenderer->render($body ?? '', $rawTokens),
         );
     }
 
     /**
+     * The headline is set as the mail's own <h1>, so it deliberately takes no Markdown:
+     * emphasis inside an already bold heading says nothing, and a stray "-" or "#" at the
+     * start of one should stay the character it is.
+     *
      * @param array<string, string> $tokens
      */
-    private function renderBody(string $body, array $tokens): string
+    private function renderHeadline(string $headline, array $tokens): string
     {
-        $body = $this->prepare($body, $tokens);
-
-        // Blank lines separate paragraphs, single newlines are soft breaks. The mail
-        // layout styles <p> with its own margins, so keeping real paragraphs preserves
-        // the spacing the hand-written templates had - a single <p> full of <br> would
-        // collapse it. nl2br then handles the breaks inside a block, which is what
-        // multi-line values such as a rejection comment need.
-        $paragraphs = [];
-
-        foreach (preg_split('/\R{2,}/', $body) as $block) {
-            $block = trim($block);
-
-            if ('' === $block) {
-                continue;
-            }
-
-            $paragraphs[] = '<p>'.nl2br($block).'</p>';
-        }
-
-        return $this->linkify(implode("\n", $paragraphs));
-    }
-
-    /**
-     * @param array<string, string> $tokens
-     */
-    private function prepare(string $text, array $tokens): string
-    {
-        $text = $this->emphasise(htmlspecialchars(trim($text), self::ESCAPE_FLAGS, 'UTF-8'));
-
-        // Substituting last means asterisks and URLs inside a value stay literal: only
-        // what an admin wrote can turn into a tag.
-        return strtr($text, $tokens);
-    }
-
-    /**
-     * Markdown-style *bold*. Runs on the already escaped string, so the only tag it can
-     * ever produce is <strong>. A literal asterisk is written \*.
-     */
-    private function emphasise(string $text): string
-    {
-        $text = preg_replace(
-            '/(?<!\\\\)\*([^*\n]+)(?<!\\\\)\*/',
-            '<strong>$1</strong>',
-            $text
-        );
-
-        return str_replace('\*', '*', $text);
-    }
-
-    /**
-     * Makes bare URLs and mail addresses clickable, so dropping the inline links the
-     * hand-written templates had does not cost the reader anything. One pass over an
-     * alternation, so a match is never linked twice.
-     */
-    private function linkify(string $html): string
-    {
-        return preg_replace_callback(
-            '~(?<url>https?://[^\s<]+)|(?<email>[\w.+-]+@[\w-]+(?:\.[\w-]+)+)~',
-            static function (array $match): string {
-                if ('' !== ($match['url'] ?? '')) {
-                    // Sentence punctuation is not part of the address.
-                    $url = rtrim($match['url'], '.,;:!?)');
-                    $trailing = substr($match['url'], strlen($url));
-
-                    return sprintf('<a href="%s">%s</a>%s', $url, $url, $trailing);
-                }
-
-                return sprintf('<a href="mailto:%1$s">%1$s</a>', $match['email']);
-            },
-            $html
+        return strtr(
+            htmlspecialchars(trim($headline), self::ESCAPE_FLAGS, 'UTF-8'),
+            $tokens
         );
     }
 }