Add QuoteModifier to support flexible string quoting

I’ve ported the `QuoteModifier` from Respect\Validation, but I’ve taken a
different approach for this implementation. While the original version relied on
and implementation of `Quoter` (from Respect\Stringifier) dependency, I decided
to remove it for this context.

The `Quoter` interface system was designed to handle complex stringification
levels and deep nesting—functionality that is simply overkill for this modifier.
By stripping that dependency away, we’ve eliminated unnecessary complexity.

A major benefit of this simplification is increased flexibility. Instead of
being locked into a predefined quoting strategy, users can now define their
preferred quoting character (such as ', ", or backticks) directly in the
constructor.

Assisted-by: OpenCode (GLM-4.6)
Assisted-by: Gemini 3 (Thinking)

Author: henriquemoody

docs/modifiers/Modifiers.md

@@ -50,6 +50,7 @@ If no modifier is provided, the formatter uses `StringifyModifier` by default.
 
 - **[AutoQuoteModifier](AutoQuoteModifier.md)** - Quotes string values by default, `|raw` bypasses quoting
 - **[ListModifier](ListModifier.md)** - Formats arrays as human-readable lists with conjunctions
+- **[QuoteModifier](QuoteModifier.md)** - Quotes string values using a stringifier quoter
 - **[StringifyModifier](StringifyModifier.md)** - Converts values to strings (default)
 
 ## Creating Custom Modifiers

docs/modifiers/QuoteModifier.md

@@ -0,0 +1,53 @@
+# QuoteModifier
+
+The `|quote` modifier wraps string values with a configurable quote character (default: backtick `` ` ``).
+
+## Behavior
+
+- Strings are wrapped with the quote character and internal occurrences are escaped
+- Non-string values delegate to the next modifier
+
+## Usage
+
+```php
+use Respect\StringFormatter\PlaceholderFormatter;
+
+$formatter = new PlaceholderFormatter([
+    'name' => 'John',
+    'text' => 'Say `hello`',
+    'count' => 42,
+]);
+
+echo $formatter->format('User: {{name|quote}}');
+// Output: User: `John`
+
+echo $formatter->format('{{text|quote}}');
+// Output: `Say \`hello\``
+
+echo $formatter->format('{{count|quote}}');
+// Output: 42 (delegated to next modifier)
+```
+
+## Custom Quote Character
+
+```php
+use Respect\StringFormatter\PlaceholderFormatter;
+use Respect\StringFormatter\Modifiers\QuoteModifier;
+use Respect\StringFormatter\Modifiers\StringifyModifier;
+
+$formatter = new PlaceholderFormatter(
+    ['name' => 'John'],
+    new QuoteModifier(new StringifyModifier(), "'"),
+);
+
+echo $formatter->format('{{name|quote}}');
+// Output: 'John'
+```
+
+## Examples
+
+| Parameters           | Template          | Output       |
+| -------------------- | ----------------- | ------------ |
+| `['name' => 'John']` | `{{name\|quote}}` | `` `John` `` |
+| `['t' => 'a`b']`     | `{{t\|quote}}`    | `` `a\`b` `` |
+| `['n' => 42]`        | `{{n\|quote}}`    | `42`         |

src/Modifiers/QuoteModifier.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Respect\StringFormatter\Modifiers;
+
+use Respect\StringFormatter\Modifier;
+
+use function addcslashes;
+use function is_scalar;
+use function sprintf;
+
+final readonly class QuoteModifier implements Modifier
+{
+    public function __construct(
+        private Modifier $nextModifier,
+        private string $quote = '`',
+    ) {
+    }
+
+    public function modify(mixed $value, string|null $pipe): string
+    {
+        if ($pipe !== 'quote') {
+            return $this->nextModifier->modify($value, $pipe);
+        }
+
+        if (!is_scalar($value)) {
+            return $this->nextModifier->modify($value, null);
+        }
+
+        return sprintf('%s%s%s', $this->quote, addcslashes((string) $value, $this->quote), $this->quote);
+    }
+}

src/PlaceholderFormatter.php

@@ -5,6 +5,7 @@
 namespace Respect\StringFormatter;
 
 use Respect\StringFormatter\Modifiers\ListModifier;
+use Respect\StringFormatter\Modifiers\QuoteModifier;
 use Respect\StringFormatter\Modifiers\StringifyModifier;
 
 use function array_key_exists;
@@ -16,7 +17,7 @@
     /** @param array<string, mixed> $parameters */
     public function __construct(
         private array $parameters,
-        private Modifier $modifier = new ListModifier(new StringifyModifier()),
+        private Modifier $modifier = new QuoteModifier(new ListModifier(new StringifyModifier())),
     ) {
     }
 

tests/Helper/TestingQuoter.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Respect\StringFormatter\Test\Helper;
+
+use Respect\Stringifier\Quoter;
+
+use function uniqid;
+
+final class TestingQuoter implements Quoter
+{
+    private string $result;
+
+    public function __construct(string|null $result = null)
+    {
+        $this->result = $result ?? uniqid();
+    }
+
+    public function quote(string $string, int $depth): string
+    {
+        return $this->result;
+    }
+}

tests/Unit/Modifiers/QuoteModifierTest.php

@@ -0,0 +1,122 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Respect\StringFormatter\Test\Unit\Modifiers;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+use Respect\StringFormatter\Modifiers\QuoteModifier;
+use Respect\StringFormatter\Test\Helper\TestingModifier;
+
+#[CoversClass(QuoteModifier::class)]
+final class QuoteModifierTest extends TestCase
+{
+    #[Test]
+    #[DataProvider('providerForPipeNotQuoteCases')]
+    public function itShouldDelegateToNextModifierWhenPipeIsNotQuote(mixed $value, string|null $pipe): void
+    {
+        $nextModifier = new TestingModifier();
+        $modifier = new QuoteModifier($nextModifier);
+        $expected = $nextModifier->modify($value, $pipe);
+
+        $actual = $modifier->modify($value, $pipe);
+
+        self::assertSame($expected, $actual);
+    }
+
+    /** @return array<string, array{0: mixed, 1: string|null}> */
+    public static function providerForPipeNotQuoteCases(): array
+    {
+        return [
+            'non-string pipe value' => ['some string', 'notQuote'],
+            'null pipe value' => ['some string', null],
+        ];
+    }
+
+    #[Test]
+    #[DataProvider('providerForNonScalarWithQuotePipe')]
+    public function itShouldDelegateToNextModifierWhenValueIsNotScalarAndPipeIsQuote(mixed $value): void
+    {
+        $nextModifier = new TestingModifier();
+        $modifier = new QuoteModifier($nextModifier);
+        // Non-scalar values with 'quote' pipe should delegate with null pipe
+        $expected = $nextModifier->modify($value, null);
+
+        $actual = $modifier->modify($value, 'quote');
+
+        self::assertSame($expected, $actual);
+    }
+
+    /** @return array<string, array{0: mixed}> */
+    public static function providerForNonScalarWithQuotePipe(): array
+    {
+        return [
+            'array value with quote pipe' => [['not', 'a', 'string']],
+            'null value with quote pipe' => [null],
+            'object value with quote pipe' => [(object) ['key' => 'value']],
+        ];
+    }
+
+    #[Test]
+    #[DataProvider('providerForScalarQuotingCases')]
+    public function itShouldQuoteScalarValuesWithQuotePipe(
+        mixed $value,
+        string $expected,
+    ): void {
+        $modifier = new QuoteModifier(new TestingModifier());
+
+        $actual = $modifier->modify($value, 'quote');
+
+        self::assertSame($expected, $actual);
+    }
+
+    /** @return array<string, array{0: mixed, 1: string}> */
+    public static function providerForScalarQuotingCases(): array
+    {
+        return [
+            'integer value' => [42, '`42`'],
+            'float value' => [3.14, '`3.14`'],
+            'boolean true value' => [true, '`1`'],
+            'boolean false value' => [false, '``'],
+        ];
+    }
+
+    #[Test]
+    #[DataProvider('providerForStringQuoting')]
+    public function itShouldQuoteStringsWithVariousContent(string $input, string $expected, string $quote = '`'): void
+    {
+        $modifier = new QuoteModifier(new TestingModifier(), $quote);
+
+        $actual = $modifier->modify($input, 'quote');
+
+        self::assertSame($expected, $actual);
+    }
+
+    /** @return array<string, array{0: string, 1: string, 2: string}> */
+    public static function providerForStringQuoting(): array
+    {
+        return [
+            'simple string' => ['hello', '`hello`', '`'],
+            'empty string' => ['', '``', '`'],
+            'string with backticks' => ['he `hello` there', '`he \\`hello\\` there`', '`'],
+            'string with backslashes' => ['path\\to\\file', '`path\\to\\file`', '`'],
+            'string with special characters' => ['!@#$%^&*()', '`!@#$%^&*()`', '`'],
+            'string with newlines' => ["line1\nline2", "`line1\nline2`", '`'],
+            'unicode characters' => ['héllo 🌍', '`héllo 🌍`', '`'],
+            'emoji string' => ['😀🎉', '`😀🎉`', '`'],
+            'mixed language string' => ['Hello 世界', '`Hello 世界`', '`'],
+            'html entities' => ['&lt;div&gt;', '`&lt;div&gt;`', '`'],
+            'url string' => ['https://example.com', '`https://example.com`', '`'],
+            'email string' => ['user@example.com', '`user@example.com`', '`'],
+            'single quote string' => ["don't", "`don't`", '`'],
+            'string with single quotes' => ["he's 'great'", "`he's 'great'`", '`'],
+            'string with mixed quotes' => ['say "hello" and \'goodbye\'', "`say \"hello\" and 'goodbye'`", '`'],
+            'test with single quotes' => ["can't stop", '"can\'t stop"', '"'],
+            'test with double quotes' => ['hello "world"', '"hello \"world\""', '"'],
+            'test with both quotes' => ['hello "world" and \'test\'', '"hello \"world\" and \'test\'"', '"'],
+        ];
+    }
+}