Add QuoteModifier ported from Respect\Validation

Port QuoteModifier from Validation project to StringFormatter following
the modifier pattern. Adapts validation logic to transformation logic
using Stringifier Quoter instead of Quoted placeholder.

- Implements Chain of Responsibility pattern with proper delegation
- Uses CodeQuoter for consistent string escaping behavior
- Includes comprehensive test suite with TestingQuoter helper
- Updates AGENTS.md with modifier development guidelines

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 proper quoting to string values using a configurable quoter.
+
+## Purpose
+
+The `|quote` modifier applies string quoting to values, handling escape sequences and special characters according to the configured quoter implementation.
+
+## 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 `Quoter` instance (default: `CodeQuoter` with 256 character limit)
+- Non-string values are passed to the next modifier unchanged
+- Handles escape sequences and special characters according to the quoter implementation
+
+## 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 Quoter
+
+You can create a `QuoteModifier` with a custom quoter:
+
+```php
+use Respect\StringFormatter\PlaceholderFormatter;
+use Respect\StringFormatter\Modifier\QuoteModifier;
+use Respect\StringFormatter\Modifier\RawModifier;
+use Respect\StringFormatter\Modifier\StringifyModifier;
+use Respect\Stringifier\Quoters\CodeQuoter;
+
+// Custom quoter with different character limit
+$customQuoter = new CodeQuoter(512);
+$quoteModifier = new QuoteModifier($rawModifier, $customQuoter);
+
+$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, applies the configured quoter to the string
+3. Otherwise, passes the value to the next modifier in the chain
+4. Uses `CodeQuoter` by default with a 256 character limit
+
+## 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
+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,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Respect\StringFormatter\Modifier;
+
+use Respect\StringFormatter\Modifier;
+use Respect\Stringifier\Quoter;
+use Respect\Stringifier\Quoters\CodeQuoter;
+
+use function is_string;
+
+final readonly class QuoteModifier implements Modifier
+{
+    public function __construct(
+        private Modifier $nextModifier,
+        private Quoter $quoter = new CodeQuoter(256),
+    ) {
+    }
+
+    public function modify(mixed $value, string|null $pipe): string
+    {
+        if ($pipe !== 'quote' || !is_string($value)) {
+            return $this->nextModifier->modify($value, $pipe);
+        }
+
+        return $this->quoter->quote($value, 0);
+    }
+}

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,87 @@
+<?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;
+use Respect\StringFormatter\Test\Helper\TestingQuoter;
+
+use function str_repeat;
+use function uniqid;
+
+#[CoversClass(QuoteModifier::class)]
+final class QuoteModifierTest extends TestCase
+{
+    #[Test]
+    #[DataProvider('providerForDelegationToNextModifier')]
+    public function itShouldDelegateToNextModifierWhenConditionsAreNotMet(
+        mixed $value,
+        string|null $pipe,
+    ): void {
+        $nextModifier = new TestingModifier();
+        $modifier = new QuoteModifier($nextModifier, new TestingQuoter());
+        $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 providerForDelegationToNextModifier(): array
+    {
+        return [
+            'non-string pipe value' => ['some string', 'notQuote'],
+            'null pipe value' => ['some string', null],
+            'array value with quote pipe' => [['not', 'a', 'string'], 'quote'],
+            'integer value with quote pipe' => [42, 'quote'],
+            'float value with quote pipe' => [3.14, 'quote'],
+            'boolean true value with quote pipe' => [true, 'quote'],
+            'boolean false value with quote pipe' => [false, 'quote'],
+            'null value with quote pipe' => [null, 'quote'],
+            'object value with quote pipe' => [(object) ['key' => 'value'], 'quote'],
+        ];
+    }
+
+    #[Test]
+    #[DataProvider('providerForStringQuoting')]
+    public function itShouldQuoteStringsWithVariousContent(string $input): void
+    {
+        $expected = uniqid();
+        $quoter = new TestingQuoter($expected);
+        $modifier = new QuoteModifier(new TestingModifier(), $quoter);
+
+        $actual = $modifier->modify($input, 'quote');
+
+        self::assertSame($expected, $actual);
+    }
+
+    /** @return array<string, array{0: string}> */
+    public static function providerForStringQuoting(): array
+    {
+        return [
+            'simple string' => ['hello'],
+            'empty string' => [''],
+            'string with spaces' => ['hello world'],
+            'string with quotes' => ['he said "hello"'],
+            'string with backslashes' => ['path\\to\\file'],
+            'string with special characters' => ['!@#$%^&*()'],
+            'string with newlines' => ["line1\nline2"],
+            'string with tabs' => ["col1\tcol2"],
+            'unicode characters' => ['héllo 🌍'],
+            'emoji string' => ['😀🎉'],
+            'mixed language string' => ['Hello 世界'],
+            'string with escaped quotes' => ['he said \"hello\"'],
+            'html entities' => ['&lt;div&gt;'],
+            'url string' => ['https://example.com/path?param=value'],
+            'email string' => ['user@example.com'],
+            'very long string' => [str_repeat('a', 1000)],
+        ];
+    }
+}