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

AGENTS.md

@@ -33,6 +33,27 @@ When creating new formatters:
 
 All formatters must implement the `Respect\StringFormatter\Formatter` interface.
 
+## Modifier Development
+
+When creating new modifiers:
+
+1. **Follow Chain of Responsibility pattern**: Check pipe value and delegate to next modifier
+2. **Use template structure**: Similar to `src/Modifier/QuoteModifier.php` 
+3. **Test with TestingModifier**: Located in `tests/Helper/TestingModifier.php`
+4. **Handle type checking**: Always check input types before processing
+5. **Return string values**: Modifiers must return strings
+6. **Use Stringifier Quoter**: For string operations, inject `\Respect\Stringifier\Quoter` with CodeQuoter as default
+
+All modifiers must implement the `Respect\StringFormatter\Modifier` interface.
+
+## Testing Guidelines
+
+1. **Avoid PHPUnit mocks**: Create custom test implementations instead of using createMock()
+2. **Use custom test quoter**: Follow pattern in `tests/Helper/TestingQuoter.php`
+3. **Test contracts not implementations**: Verify interactions without depending on specific behavior
+4. **Make test properties public**: When using anonymous classes to access test state
+5. **Verify method calls**: Track whether methods were called and with what parameters
+
 ## Commit Guidelines
 
 Follow the detailed rules in `docs/contributing/commit-guidelines.md`:

docs/modifiers/Modifiers.md

@@ -33,12 +33,13 @@ Modifiers form a chain where each modifier can:
 The default modifier chain is:
 
 ```
-RawModifier -> ListModifier -> StringifyModifier
+RawModifier -> ListModifier -> QuoteModifier -> StringifyModifier
 ```
 
 - `StringifyModifier` is always the last modifier, using the stringifier to convert values to strings
 - `RawModifier` processes scalar values without stringifier formatting
 - `ListModifier` formats arrays as human-readable lists with "and" or "or" conjunctions
+- `QuoteModifier` quotes string values using the stringifier quoter
 
 ## Syntax Rules
 
@@ -72,6 +73,7 @@ For non-scalar values with `|raw`, the modifier falls back to the next modifier
 - **[RawModifier](RawModifier.md)** - Outputs scalar values directly without stringifier formatting
 - **[StringifyModifier](StringifyModifier.md)** - Default modifier that uses stringifier for all values
 - **[ListModifier](ListModifier.md)** - Formats arrays as human-readable lists with conjunctions
+- **[QuoteModifier](QuoteModifier.md)** - Quotes string values using a stringifier quoter
 
 ## Creating Custom Modifiers
 
@@ -93,4 +95,4 @@ $formatter = new PlaceholderFormatter(
 );
 ```
 
-If no modifier is provided, the formatter uses a default `RawModifier` with `ListModifier` and `StringifyModifier`.
+If no modifier is provided, the formatter uses a default `RawModifier` with `ListModifier`, `QuoteModifier` and `StringifyModifier`.

docs/modifiers/QuoteModifier.md

@@ -0,0 +1,112 @@
+# QuoteModifier
+
+The `QuoteModifier` adds simple quoting to string values using a configurable quote character.
+
+## Purpose
+
+The `|quote` modifier applies string quoting to values, handling escape sequences by escaping the quote character within the string.
+
+## Behavior
+
+The modifier only processes string values. For non-string values, it passes them to the next modifier in the chain.
+
+### Quoting Behavior
+
+- Strings are quoted using the configured quote character (default: `` ` ``)
+- Only the configured quote character is escaped within the string using `addcslashes()`
+- Non-string values are passed to the next modifier unchanged
+- Other quote types (like " or ') are not escaped unless they are the configured quote character
+
+## Usage
+
+```php
+use Respect\StringFormatter\PlaceholderFormatter;
+use Respect\StringFormatter\Modifier\QuoteModifier;
+use Respect\StringFormatter\Modifier\StringifyModifier;
+
+$formatter = new PlaceholderFormatter([
+    'name' => 'John "Johnny" Doe',
+    'path' => 'C:\Users\Files\My Document.txt',
+    'status' => 'It\'s working',
+    'age' => 30,
+    'data' => ['x' => 1]
+]);
+
+echo $formatter->format('{{name|quote}}');
+// Outputs: '`John "Johnny" Doe`'
+
+echo $formatter->format('{{status|quote}}');
+// Outputs: '`It's working`'
+
+echo $formatter->format('{{age|quote}}');
+// Outputs: "30" (passed to StringifyModifier, no quoting applied)
+```
+
+## Examples
+
+### Basic Quoting
+
+| Parameters                    | Template                | Output              |
+| ----------------------------- | ----------------------- | ------------------- |
+| `['name' => 'John']`          | `"{{name|quote}}"` | "`John`"            |
+| `['text' => 'Hello "World"']` | `"{{text|quote}}"` | "`Hello \"World\"`" |
+| `['path' => 'C:\temp']`       | `"{{path|quote}}"` | "`C:\temp`"         |
+
+### Escape Sequences
+
+| Parameters                     | Template                | Output             |
+| ------------------------------ | ----------------------- | ------------------ |
+| `['text' => "Line1\nLine2"]`   | `"{{text|quote}}"` | "`Line1\nLine2`"   |
+| `['text' => "Tab\tSeparated"]` | `"{{text|quote}}"` | "`Tab\tSeparated`" |
+| `['text' => "Back\\Slash"]`    | `"{{text|quote}}"` | "`Back\Slash`"     |
+
+### Non-string Values
+
+| Parameters                | Template                  | Output      |
+| ------------------------- | ------------------------- | ----------- |
+| `['age' => 30]`           | `"{{age|quote}}"`    | "`30`"      |
+| `['active' => true]`      | `"{{active|quote}}"` | "`true`"    |
+| `['items' => ['a', 'b']]` | `"{{items|quote}}"`  | `["a","b"]` |
+
+## Custom Quote Character
+
+You can create a `QuoteModifier` with a custom quote character:
+
+```php
+use Respect\StringFormatter\PlaceholderFormatter;
+use Respect\StringFormatter\Modifier\QuoteModifier;
+use Respect\StringFormatter\Modifier\RawModifier;
+use Respect\StringFormatter\Modifier\StringifyModifier;
+
+// Custom quote character
+$quoteModifier = new QuoteModifier($nextModifier, "'");
+
+$formatter = new PlaceholderFormatter(['text' => $value], $quoteModifier);
+```
+
+## Implementation Notes
+
+The `QuoteModifier`:
+
+1. Checks if the pipe value is `"quote"` and the input value is a string
+2. If both conditions are met, wraps the string with the configured quote character
+3. Escapes any occurrences of the quote character within the string using `addcslashes()`
+4. Otherwise, passes the value to the next modifier in the chain
+5. Uses backticks (`` ` ``) as the default quote character
+
+## Common Use Cases
+
+1. **CSV output** - Properly quote fields containing special characters
+2. **Code generation** - Quote string literals in generated code
+3. **Configuration files** - Ensure string values are properly escaped
+4. **Logging** - Prepare string values for logging with proper escaping
+
+## Integration
+
+`QuoteModifier` is typically positioned early in the chain:
+
+```php
+CustomModifier -> QuoteModifier -> RawModifier -> StringifyModifier
+```
+
+This ensures string quoting is applied before other processing, while still allowing raw output and stringification fallbacks.

src/Modifier/QuoteModifier.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Respect\StringFormatter\Modifier;
+
+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);
+    }
+}

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/Modifier/QuoteModifierTest.php

@@ -0,0 +1,122 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Respect\StringFormatter\Test\Unit\Modifier;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+use Respect\StringFormatter\Modifier\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\'"', '"'],
+        ];
+    }
+}