From edf14dcb0380a92a268f4869cb1acbb5e683abb3 Mon Sep 17 00:00:00 2001
From: Ben Ramsey <ben@benramsey.com>
Date: Mon, 13 Dec 2021 17:02:35 -0600
Subject: [PATCH] feat: improve tag support for parity with formatjs

---
 src/Config.php                                |  18 +++
 src/ConfigInterface.php                       |  21 +++
 src/FormatPHP.php                             |   5 +
 src/Icu/MessageFormat/Parser/Error.php        |   7 +-
 .../UnableToParseMessageException.php         |  62 +++++++
 src/Intl/MessageFormat.php                    | 152 +++++++++++++++++-
 src/Intl/MessageFormatInterface.php           |  30 +++-
 tests/ConfigTest.php                          |   8 +-
 tests/FormatPHPTest.php                       |  27 ++++
 tests/Intl/MessageFormatTest.php              | 127 +++++++++++++++
 10 files changed, 451 insertions(+), 6 deletions(-)
 create mode 100644 src/Icu/MessageFormat/Parser/Exception/UnableToParseMessageException.php

diff --git a/src/Config.php b/src/Config.php
index 4a988b3..812aed4 100644
--- a/src/Config.php
+++ b/src/Config.php
@@ -34,14 +34,24 @@ class Config implements ConfigInterface
     private ?LocaleInterface $defaultLocale;
     private string $idInterpolatorPattern;
 
+    /**
+     * @var array<string, callable(string):string>
+     */
+    private array $defaultRichTextElements;
+
+    /**
+     * @param array<string, callable(string):string> $defaultRichTextElements
+     */
     public function __construct(
         LocaleInterface $locale,
         ?LocaleInterface $defaultLocale = null,
+        array $defaultRichTextElements = [],
         string $idInterpolatorPattern = IdInterpolator::DEFAULT_ID_INTERPOLATION_PATTERN
     ) {
         $this->locale = $locale;
         $this->defaultLocale = $defaultLocale;
         $this->idInterpolatorPattern = $idInterpolatorPattern;
+        $this->defaultRichTextElements = $defaultRichTextElements;
     }
 
     public function getDefaultLocale(): ?LocaleInterface
@@ -58,4 +68,12 @@ public function getLocale(): LocaleInterface
     {
         return $this->locale;
     }
+
+    /**
+     * @return array<string, callable(string):string>
+     */
+    public function getDefaultRichTextElements(): array
+    {
+        return $this->defaultRichTextElements;
+    }
 }
diff --git a/src/ConfigInterface.php b/src/ConfigInterface.php
index aa9d6d2..17a2aa3 100644
--- a/src/ConfigInterface.php
+++ b/src/ConfigInterface.php
@@ -35,6 +35,27 @@ interface ConfigInterface
      */
     public function getDefaultLocale(): ?LocaleInterface;
 
+    /**
+     * Returns a map of tag names to rich text formatting functions
+     *
+     * This is meant to provide a centralized way to format common tags such as
+     * `<b>`, `<p>`, or enforcing a certain design system in the codebase
+     * (e.g., standardized `<a>`, `<button>`, etc.).
+     *
+     * The functions should be a callable that accepts a single string parameter
+     * and returns a string. For example:
+     *
+     * ```php
+     * [
+     *     'em' => fn (string $text): string => '<em class="bar">' . $text . '</em>',
+     *     'strong' => fn (string $text): string => '<strong class="foo">' . $text . '</strong>',
+     * ]
+     * ```
+     *
+     * @return array<string, callable(string):string>
+     */
+    public function getDefaultRichTextElements(): array;
+
     /**
      * Returns a pattern that defines how to generate missing message IDs
      *
diff --git a/src/FormatPHP.php b/src/FormatPHP.php
index aa003a3..8d45200 100644
--- a/src/FormatPHP.php
+++ b/src/FormatPHP.php
@@ -28,6 +28,7 @@
 use FormatPHP\Util\MessageCleaner;
 use FormatPHP\Util\MessageRetriever;
 
+use function array_merge;
 use function is_int;
 
 /**
@@ -62,6 +63,10 @@ public function __construct(
      */
     public function formatMessage(array $descriptor, array $values = []): string
     {
+        // Combine the global default rich text element callbacks with the values,
+        // giving preference to values provided with the same keys.
+        $values = array_merge($this->config->getDefaultRichTextElements(), $values);
+
         try {
             $messagePattern = $this->getMessageForDescriptor(
                 $this->messages,
diff --git a/src/Icu/MessageFormat/Parser/Error.php b/src/Icu/MessageFormat/Parser/Error.php
index f6857df..22becc7 100644
--- a/src/Icu/MessageFormat/Parser/Error.php
+++ b/src/Icu/MessageFormat/Parser/Error.php
@@ -24,6 +24,9 @@
 
 use FormatPHP\Icu\MessageFormat\Parser\Type\Location;
 
+/**
+ * @psalm-type ErrorKind = Error::*
+ */
 class Error
 {
     /**
@@ -166,7 +169,7 @@ class Error
     public const UNCLOSED_TAG = 27;
 
     /**
-     * @psalm-var Error::*
+     * @var ErrorKind
      */
     public int $kind;
 
@@ -174,7 +177,7 @@ class Error
     public Location $location;
 
     /**
-     * @psalm-param Error::* $kind
+     * @param ErrorKind $kind
      */
     public function __construct(int $kind, string $message, Location $location)
     {
diff --git a/src/Icu/MessageFormat/Parser/Exception/UnableToParseMessageException.php b/src/Icu/MessageFormat/Parser/Exception/UnableToParseMessageException.php
new file mode 100644
index 0000000..8ffe9eb
--- /dev/null
+++ b/src/Icu/MessageFormat/Parser/Exception/UnableToParseMessageException.php
@@ -0,0 +1,62 @@
+<?php
+
+/**
+ * This file is part of skillshare/formatphp
+ *
+ * skillshare/formatphp is open source software: you can distribute
+ * it and/or modify it under the terms of the MIT License
+ * (the "License"). You may not use this file except in
+ * compliance with the License.
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ * implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ *
+ * @copyright Copyright (c) Skillshare, Inc. <https://www.skillshare.com>
+ * @license https://opensource.org/licenses/MIT MIT License
+ */
+
+declare(strict_types=1);
+
+namespace FormatPHP\Icu\MessageFormat\Parser\Exception;
+
+use FormatPHP\Icu\MessageFormat\Parser\Error;
+use ReflectionObject;
+use RuntimeException as PhpRuntimeException;
+use Throwable;
+
+use function array_flip;
+use function sprintf;
+
+/**
+ * Thrown with a message format parser Error to indicate a syntax error
+ * encountered while parsing a message
+ */
+class UnableToParseMessageException extends PhpRuntimeException implements ParserExceptionInterface
+{
+    public function __construct(Error $error, ?Throwable $previous = null)
+    {
+        parent::__construct($this->createMessageForError($error), 0, $previous);
+    }
+
+    private function createMessageForError(Error $error): string
+    {
+        return sprintf(
+            'Syntax error %s found while parsing message "%s"',
+            $this->getErrorTypeName($error),
+            $error->message,
+        );
+    }
+
+    private function getErrorTypeName(Error $error): string
+    {
+        $reflection = new ReflectionObject($error);
+
+        // @phpstan-ignore-next-line
+        $constants = array_flip($reflection->getConstants());
+
+        return $constants[$error->kind] ?? '';
+    }
+}
diff --git a/src/Intl/MessageFormat.php b/src/Intl/MessageFormat.php
index 80517b3..7535fc1 100644
--- a/src/Intl/MessageFormat.php
+++ b/src/Intl/MessageFormat.php
@@ -24,11 +24,23 @@
 
 use FormatPHP\Exception\InvalidArgumentException;
 use FormatPHP\Exception\UnableToFormatMessageException;
-use IntlException as PhpIntlException;
+use FormatPHP\Icu\MessageFormat\Parser;
+use FormatPHP\Icu\MessageFormat\Parser\Type\PluralElement;
+use FormatPHP\Icu\MessageFormat\Parser\Type\SelectElement;
+use FormatPHP\Icu\MessageFormat\Printer;
 use Locale as PhpLocale;
 use MessageFormatter as PhpMessageFormatter;
+use Ramsey\Collection\Exception\CollectionMismatchException;
+use Throwable;
 
+use function array_filter;
+use function array_key_exists;
+use function array_keys;
+use function array_values;
+use function assert;
+use function is_callable;
 use function is_int;
+use function preg_match;
 use function sprintf;
 
 /**
@@ -36,6 +48,10 @@
  */
 class MessageFormat implements MessageFormatInterface
 {
+    private const CALLBACK_REPLACEMENT = '__FORMATPHP_CALLBACK_REPLACEMENT__';
+    private const CALLBACK_RESULT_PATTERN = '/(.*)' . self::CALLBACK_REPLACEMENT . '(.*)/su';
+    private const LITERAL_TAG_PATTERN = '/^<(.*)\/>$/su';
+
     private LocaleInterface $locale;
 
     /**
@@ -52,10 +68,11 @@ public function __construct(?LocaleInterface $locale = null)
     public function format(string $pattern, array $values = []): string
     {
         try {
+            $pattern = $this->applyCallbacks($pattern, $values);
             $formatter = new PhpMessageFormatter((string) $this->locale->baseName(), $pattern);
 
             return (string) $formatter->format($values);
-        } catch (PhpIntlException $exception) {
+        } catch (Throwable $exception) {
             throw new UnableToFormatMessageException(
                 sprintf(
                     'Unable to format message with pattern "%s" for locale "%s"',
@@ -67,4 +84,135 @@ public function format(string $pattern, array $values = []): string
             );
         }
     }
+
+    /**
+     * @param array<array-key, float | int | string | callable(string):string> $values
+     *
+     * @throws Parser\Exception\IllegalParserUsageException
+     * @throws Parser\Exception\InvalidArgumentException
+     * @throws Parser\Exception\InvalidOffsetException
+     * @throws Parser\Exception\InvalidSkeletonOption
+     * @throws Parser\Exception\InvalidUtf8CodeBoundaryException
+     * @throws Parser\Exception\InvalidUtf8CodePointException
+     * @throws Parser\Exception\UnableToParseMessageException
+     * @throws UnableToFormatMessageException
+     * @throws CollectionMismatchException
+     */
+    private function applyCallbacks(string $pattern, array &$values = []): string
+    {
+        $callbacks = array_filter($values, fn ($value): bool => is_callable($value));
+
+        // If $values doesn't contain any callables, go ahead and return.
+        if (!$callbacks) {
+            return $pattern;
+        }
+
+        // Remove the callbacks from the values, since we will use them below.
+        foreach (array_keys($callbacks) as $key) {
+            unset($values[$key]);
+        }
+
+        $parser = new Parser($pattern);
+        $parsed = $parser->parse();
+
+        if ($parsed->err !== null) {
+            throw new Parser\Exception\UnableToParseMessageException($parsed->err);
+        }
+
+        assert($parsed->val instanceof Parser\Type\ElementCollection);
+
+        return (new Printer())->printAst($this->processAstWithCallbacks($parsed->val, $callbacks));
+    }
+
+    /**
+     * @param array<array-key, callable(string):string> $callbacks
+     *
+     * @throws CollectionMismatchException
+     * @throws UnableToFormatMessageException
+     */
+    private function processAstWithCallbacks(
+        Parser\Type\ElementCollection $ast,
+        array $callbacks
+    ): Parser\Type\ElementCollection {
+        $processedAst = new Parser\Type\ElementCollection();
+
+        for ($i = 0; $i < $ast->count(); $i++) {
+            $element = $ast[$i];
+            assert($element instanceof Parser\Type\ElementInterface);
+            $clone = clone $element;
+
+            if ($clone instanceof PluralElement || $clone instanceof SelectElement) {
+                foreach ($clone->options as $option) {
+                    $option->value = $this->processAstWithCallbacks($option->value, $callbacks);
+                }
+            }
+
+            if ($clone instanceof Parser\Type\TagElement) {
+                $processedAst = $processedAst->merge($this->processTagElement($clone, $callbacks));
+
+                continue;
+            }
+
+            if ($clone instanceof Parser\Type\LiteralElement) {
+                $clone = $this->processLiteralElement($clone, $callbacks);
+            }
+
+            $processedAst[] = $clone;
+        }
+
+        return $processedAst;
+    }
+
+    /**
+     * @param array<array-key, callable(string):string> $callbacks
+     *
+     * @throws CollectionMismatchException
+     * @throws UnableToFormatMessageException
+     */
+    private function processTagElement(
+        Parser\Type\TagElement $tagElement,
+        array $callbacks
+    ): Parser\Type\ElementCollection {
+        if (!array_key_exists($tagElement->value, $callbacks)) {
+            // We don't have a callback for this tag.
+            return new Parser\Type\ElementCollection([$tagElement]);
+        }
+
+        $result = ($callbacks[$tagElement->value])(self::CALLBACK_REPLACEMENT);
+        if (preg_match(self::CALLBACK_RESULT_PATTERN, $result, $matches)) {
+            $start = new Parser\Type\LiteralElement($matches[1], $tagElement->location);
+            $middle = $this->processAstWithCallbacks($tagElement->children, $callbacks);
+            $end = new Parser\Type\LiteralElement($matches[2], $tagElement->location);
+
+            return new Parser\Type\ElementCollection([$start, ...array_values($middle->toArray()), $end]);
+        }
+
+        return new Parser\Type\ElementCollection([new Parser\Type\LiteralElement($result, $tagElement->location)]);
+    }
+
+    /**
+     * @param array<array-key, callable(string):string> $callbacks
+     *
+     * @throws CollectionMismatchException
+     * @throws UnableToFormatMessageException
+     */
+    private function processLiteralElement(
+        Parser\Type\LiteralElement $literalElement,
+        array $callbacks
+    ): Parser\Type\LiteralElement {
+        if (!preg_match(self::LITERAL_TAG_PATTERN, $literalElement->value, $matches)) {
+            // This isn't a literal tag, so there's nothing to process.
+            return $literalElement;
+        }
+
+        if (!array_key_exists($matches[1], $callbacks)) {
+            // We don't have a callback for this tag.
+            return $literalElement;
+        }
+
+        $result = ($callbacks[$matches[1]])('');
+        $literalElement->value = $result;
+
+        return $literalElement;
+    }
 }
diff --git a/src/Intl/MessageFormatInterface.php b/src/Intl/MessageFormatInterface.php
index 74bf7ad..ed0fa5e 100644
--- a/src/Intl/MessageFormatInterface.php
+++ b/src/Intl/MessageFormatInterface.php
@@ -42,7 +42,35 @@ interface MessageFormatInterface
      * message format instance and replacing any placeholders with the provided
      * values
      *
-     * @param array<array-key, float | int | string> $values
+     * In addition to string and number values, the `$values` parameter may have
+     * a callable that accepts a string and returns a string. For any callable,
+     * the array key should match a "tag" embedded in the message.
+     *
+     * For example, if you wish to produce the following HTML:
+     *
+     *     Hello, <a href="/profile/1234">Ben</a>!
+     *
+     * Format the message like this:
+     *
+     *     Hello, <profileLink>{name}</profileLink>!
+     *
+     * Then, pass a callable to `$values` with the key `profileLink`. It will
+     * look something like this:
+     *
+     * ```php
+     * $formatphp->formatMessage(
+     *     [
+     *         'id' => 'welcome',
+     *         'defaultMessage' => 'Hello, <profileLink>{name}</profileLink>!',
+     *     ],
+     *     [
+     *         'name' => 'Ben',
+     *         'profileLink' => fn (string $text): string => '<a href="/profile/1234">' . $text . '</a>',
+     *     ],
+     * );
+     * ```
+     *
+     * @param array<array-key, float | int | string | callable(string):string> $values
      *
      * @throws UnableToFormatMessageException
      */
diff --git a/tests/ConfigTest.php b/tests/ConfigTest.php
index ecb74d7..9a24842 100644
--- a/tests/ConfigTest.php
+++ b/tests/ConfigTest.php
@@ -14,10 +14,16 @@ public function testInstanceConstruction(): void
     {
         $locale = new Locale('en-US');
         $defaultLocale = new Locale('en');
-        $config = new Config($locale, $defaultLocale);
+        $defaultRichTextElements = [
+            'em' => fn (string $text): string => '<em class="bar">' . $text . '</em>',
+            'strong' => fn (string $text): string => '<strong class="foo">' . $text . '</strong>',
+        ];
+
+        $config = new Config($locale, $defaultLocale, $defaultRichTextElements);
 
         $this->assertSame($locale, $config->getLocale());
         $this->assertSame($defaultLocale, $config->getDefaultLocale());
+        $this->assertSame($defaultRichTextElements, $config->getDefaultRichTextElements());
         $this->assertSame(IdInterpolator::DEFAULT_ID_INTERPOLATION_PATTERN, $config->getIdInterpolatorPattern());
     }
 }
diff --git a/tests/FormatPHPTest.php b/tests/FormatPHPTest.php
index 4cae2af..5beb9eb 100644
--- a/tests/FormatPHPTest.php
+++ b/tests/FormatPHPTest.php
@@ -85,4 +85,31 @@ public function testFormatMessageThrowsExceptionWhenUnableToGenerateMessageId():
 
         $formatphp->formatMessage([]);
     }
+
+    public function testFormatMessageUsesDefaultRichTextElements(): void
+    {
+        $locale = new Locale('en-US');
+        $config = new Config($locale, null, [
+            'homeLink' => fn (string $text): string => '<a href="https://example.com>' . $text . '</a>',
+            'boldface' => fn ($text) => "<strong>$text</strong>",
+            'italicized' => fn ($text) => "<em>$text</em>",
+        ]);
+
+        $message = new Message('myMessage', '<homeLink>Go <boldface>home</boldface></homeLink>, {name}!');
+        $messageCollection = new MessageCollection([$message]);
+        $formatphp = new FormatPHP($config, $messageCollection);
+
+        $this->assertSame(
+            '<a href="https://example.com>Go <strong>home</strong></a>, Sam!',
+            $formatphp->formatMessage(
+                [
+                    'id' => 'myMessage',
+                    'defaultMessage' => '<homeLink>Go <boldface>home</boldface></homeLink>, {name}!',
+                ],
+                [
+                    'name' => 'Sam',
+                ],
+            ),
+        );
+    }
 }
diff --git a/tests/Intl/MessageFormatTest.php b/tests/Intl/MessageFormatTest.php
index de65e3a..9b853fe 100644
--- a/tests/Intl/MessageFormatTest.php
+++ b/tests/Intl/MessageFormatTest.php
@@ -9,6 +9,7 @@
 use FormatPHP\Descriptor;
 use FormatPHP\DescriptorInterface;
 use FormatPHP\Exception\UnableToFormatMessageException;
+use FormatPHP\Icu\MessageFormat\Parser\Exception\UnableToParseMessageException;
 use FormatPHP\Intl\Locale;
 use FormatPHP\Intl\MessageFormat;
 use FormatPHP\Message;
@@ -175,4 +176,130 @@ public function formatProvider(): array
             ],
         ];
     }
+
+    public function testTags(): void
+    {
+        $locale = new Locale('en-US');
+        $formatter = new MessageFormat($locale);
+
+        $formatted = $formatter->format(
+            'Hi, <profileLink><boldface>{name}</boldface>, our <italicized>great friend</italicized></profileLink>!',
+            [
+                'name' => 'Samwise',
+                'profileLink' => fn ($text) => '<a href="https://example.com">' . $text . '</a>',
+                'boldface' => fn ($text) => "<strong>$text</strong>",
+                'italicized' => fn ($text) => "<em>$text</em>",
+            ],
+        );
+
+        $this->assertSame(
+            'Hi, <a href="https://example.com"><strong>Samwise</strong>, our <em>great friend</em></a>!',
+            $formatted,
+        );
+    }
+
+    public function testMixedTags(): void
+    {
+        $locale = new Locale('en-US');
+        $formatter = new MessageFormat($locale);
+
+        $formatted = $formatter->format(
+            'Hi, <profileLink><boldface>{name}</boldface>, <foo /> our '
+                . '<italicized>great friend</italicized></profileLink>!',
+            [
+                'name' => 'Pippin',
+                'profileLink' => fn ($text) => '<a href="https://example.com">' . $text . '</a>',
+            ],
+        );
+
+        $this->assertSame(
+            'Hi, <a href="https://example.com"><boldface>Pippin</boldface>, '
+                . '<foo/> our <italicized>great friend</italicized></a>!',
+            $formatted,
+        );
+    }
+
+    public function testSelectAndPluralOptionsWithTags(): void
+    {
+        $message = <<<'EOD'
+            Last time I checked, {gender, select,
+                male {<italicized>he</italicized> had}
+                female {<italicized>she</italicized> had}
+                other {<italicized>they</italicized> had}
+            } {petCount, plural,
+                =0 {<bold>no</bold> pets}
+                =1 {<bold>a</bold> pet}
+                other {<bold>#</bold> pets}
+            }.
+            EOD;
+
+        $expected = 'Last time I checked, <em>she</em> had <strong>4</strong> pets.';
+
+        $locale = new Locale('en-US');
+        $formatter = new MessageFormat($locale);
+
+        $formatted = $formatter->format($message, [
+            'gender' => 'female',
+            'petCount' => 4,
+            'italicized' => fn ($text) => "<em>$text</em>",
+            'bold' => fn ($text) => "<strong>$text</strong>",
+        ]);
+
+        $this->assertSame($expected, $formatted);
+    }
+
+    public function testThrowsExceptionWhenUnableToParseMessage(): void
+    {
+        $message = 'Hello, <link>{name}';
+
+        $locale = new Locale('en-US');
+        $formatter = new MessageFormat($locale);
+
+        // We're not using expectException() because we want to actually
+        // inspect the exception object as part of this test.
+        try {
+            $formatter->format($message, [
+                'name' => 'Bilbo',
+                'link' => fn ($text) => "<a>$text</a>",
+            ]);
+        } catch (UnableToFormatMessageException $exception) {
+            $this->assertSame(
+                'Unable to format message with pattern "Hello, <link>{name}" for locale "en-US"',
+                $exception->getMessage(),
+            );
+            $this->assertInstanceOf(UnableToParseMessageException::class, $exception->getPrevious());
+            $this->assertSame(
+                'Syntax error UNCLOSED_TAG found while parsing message "Hello, <link>{name}"',
+                $exception->getPrevious()->getMessage(),
+            );
+        }
+    }
+
+    public function testReplacesEmptyTagWithCallbackResultValue(): void
+    {
+        $message = 'Sometimes a <foobar></foobar> might not have a body';
+
+        $locale = new Locale('en-US');
+        $formatter = new MessageFormat($locale);
+
+        $formatted = $formatter->format($message, [
+            'foobar' => fn () => '<em>tag</em>',
+        ]);
+
+        $this->assertSame('Sometimes a <em>tag</em> might not have a body', $formatted);
+    }
+
+    public function testReplacesSelfClosingTagWithCallbackResultValue(): void
+    {
+        $message = 'Sometimes a <foobar /> might be self-closing';
+
+        $locale = new Locale('en-US');
+        $formatter = new MessageFormat($locale);
+
+        $formatted = $formatter->format($message, [
+            'foobar' => fn () => '<strong>tag</strong>',
+        ]);
+
+        $this->assertSame('Sometimes a <strong>tag</strong> might be self-closing', $formatted);
+    }
 }