Replace AutoQuoteModifier with focused Stringify and Raw modifiers

The `AutoQuoteModifier` was an attempt to handle both quoting and raw output in
a single place, but in practice, it felt confused and didn’t solve the problem
as intended. It tried to do too much, resulting in unwanted outcomes. This
refactor breaks those responsibilities into single-purpose modifiers, which are
much easier to reason about.

The New Modifier Strategy:

- `EnsureStringModifier` (formerly `StringifyModifier`): This now has a very
   narrow focus. It only stringifies non-string values, leaving existing strings
   untouched.

- `StringifyModifier`: I’ve introduced a new version of this that always
  stringifies every value it receives, regardless of type.

- `RawModifier`: This handles the `|raw` pipe specifically, providing a clean
   escape for unquoted scalar output.

These modifiers are designed to complement one another. In Respect\Validation,
where we want strings to be quoted by default, the `StringifyModifier` handles
the all parameters, while the `RawModifier` provides the necessary "opt-out" via
the `|raw` pipe.

Assisted-by: OpenCode (GLM-4.6)
Assisted-by: Gemini 3 (Thinking)
Assisted-by: Claude Code (Opus 4.5)

Author: henriquemoody

composer.json

@@ -5,7 +5,6 @@
     "require": {
         "php": "^8.5",
         "respect/stringifier": "^3.0",
-        "symfony/polyfill-ctype": "^1.33",
         "symfony/polyfill-mbstring": "^1.33",
         "symfony/translation-contracts": "^3.6"
     },

docs/modifiers/AutoQuoteModifier.md

@@ -0,0 +1,66 @@
+# EnsureStringModifier
+
+The `EnsureStringModifier` converts non-string values to strings using a `Stringifier` instance. It serves as the terminal modifier in the default `PlaceholderFormatter` chain.
+
+## Behavior
+
+| Pipe   | String             | Other Types               |
+| ------ | ------------------ | ------------------------- |
+| (none) | Returned unchanged | Converted via stringifier |
+| `\|*`  | Throws exception   | Throws exception          |
+
+- Uses `HandlerStringifier` by default for type conversion
+- Throws `InvalidModifierPipeException` if any pipe is used (e.g., `{{value|something}}`)
+
+This modifier is typically used at the end of a modifier chain to ensure all values become strings.
+
+## Usage
+
+```php
+use Respect\StringFormatter\PlaceholderFormatter;
+use Respect\StringFormatter\Modifiers\EnsureStringModifier;
+
+$formatter = new PlaceholderFormatter(
+    [
+        'name' => 'John',
+        'active' => true,
+        'data' => ['x' => 1],
+    ],
+    new EnsureStringModifier(),
+);
+
+echo $formatter->format('{{name}} is {{active}}');
+// Output: John is true
+
+echo $formatter->format('Data: {{data}}');
+// Output: Data: ["x":1]
+```
+
+## Examples
+
+| Parameters               | Template     | Output    |
+| ------------------------ | ------------ | --------- |
+| `['name' => 'John']`     | `{{name}}`   | `John`    |
+| `['count' => 42]`        | `{{count}}`  | `42`      |
+| `['price' => 19.99]`     | `{{price}}`  | `19.99`   |
+| `['active' => true]`     | `{{active}}` | `true`    |
+| `['active' => false]`    | `{{active}}` | `false`   |
+| `['value' => null]`      | `{{value}}`  | `null`    |
+| `['items' => [1, 2, 3]]` | `{{items}}`  | `[1,2,3]` |
+| `['data' => ['a' => 1]]` | `{{data}}`   | `["a":1]` |
+
+## Custom Stringifier
+
+You can provide a custom `Stringifier` to control how non-string values are converted:
+
+```php
+use Respect\StringFormatter\PlaceholderFormatter;
+use Respect\StringFormatter\Modifiers\EnsureStringModifier;
+
+$formatter = new PlaceholderFormatter(
+    ['data' => $value],
+    new EnsureStringModifier($customStringifier),
+);
+```
+
+See the [Respect\Stringifier documentation](https://github.com/Respect/Stringifier) for details on creating custom stringifiers.

docs/modifiers/EnsureStringModifier.md

@@ -32,26 +32,30 @@ You can specify a custom modifier chain when creating a `PlaceholderFormatter`:
 
 ```php
 use Respect\StringFormatter\PlaceholderFormatter;
-use Respect\StringFormatter\Modifiers\AutoQuoteModifier;
+use Respect\StringFormatter\Modifiers\RawModifier;
 use Respect\StringFormatter\Modifiers\StringifyModifier;
 
 $formatter = new PlaceholderFormatter(
-    ['name' => 'John'],
-    new AutoQuoteModifier(new StringifyModifier()),
+    ['name' => 'John', 'active' => true],
+    new RawModifier(new StringifyModifier()),
 );
 
 echo $formatter->format('Hello {{name}}');
 // Output: Hello "John"
+
+echo $formatter->format('Hello {{name|raw}}');
+// Output: Hello John
 ```
 
 If no modifier is provided, the formatter uses `StringifyModifier` by default.
 
 ## Available Modifiers
 
-- **[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)
+- **[RawModifier](RawModifier.md)** - Returns scalar values as raw strings with `|raw` pipe
+- **[EnsureStringModifier](EnsureStringModifier.md)** - Converts non-string values to strings (bypasses strings)
+- **[StringifyModifier](StringifyModifier.md)** - Always converts values to strings (default)
 - **[TransModifier](TransModifier.md)** - Translates string values using a Symfony translator
 
 ## Creating Custom Modifiers

docs/modifiers/Modifiers.md

@@ -0,0 +1,51 @@
+# RawModifier
+
+The `|raw` modifier returns scalar values as raw strings, converting booleans to `1`/`0`. Non-scalar values delegate to the next modifier.
+
+> **Note:** This modifier is designed to be used with [StringifyModifier](StringifyModifier.md). When `StringifyModifier` quotes strings by default, `RawModifier` provides a way to output unquoted values using the `|raw` pipe.
+
+## Behavior
+
+| Pipe    | String          | Other Scalars       | Non-Scalar                 |
+| ------- | --------------- | ------------------- | -------------------------- |
+| (none)  | Delegates       | Delegates           | Delegates                  |
+| `\|raw` | Unquoted string | Converted to string | Delegates to next modifier |
+
+With `|raw`, booleans are converted to `1`/`0`. All other values are delegated to the next modifier.
+
+## Usage
+
+The `RawModifier` is typically used with `StringifyModifier` to create a modifier chain that handles raw output:
+
+```php
+use Respect\StringFormatter\PlaceholderFormatter;
+use Respect\StringFormatter\Modifiers\RawModifier;
+use Respect\StringFormatter\Modifiers\StringifyModifier;
+
+$formatter = new PlaceholderFormatter(
+    ['firstname' => 'John', 'lastname' => 'Doe', 'active' => true],
+    new RawModifier(new StringifyModifier()),
+);
+
+echo $formatter->format('Hi {{firstname}}');
+// Output: Hi John
+
+echo $formatter->format('Active flag: {{active|raw}}');
+// Output: Active flag: 1
+```
+
+## Examples
+
+Here are some examples demonstrating the behavior of `RawModifier` when used with `StringifyModifier`:
+
+| Parameters                                  | Template         | Output                                        |
+| ------------------------------------------- | ---------------- | --------------------------------------------- |
+| `['name' => 'John']`                        | `{{name}}`       | `"John"`                                      |
+| `['name' => 'John']`                        | `{{name\|raw}}`  | `John`                                        |
+| `['count' => 42]`                           | `{{count}}`      | `42`                                          |
+| `['count' => 42]`                           | `{{count\|raw}}` | `42`                                          |
+| `['on' => true]`                            | `{{on}}`         | `true`                                        |
+| `['on' => true]`                            | `{{on\|raw}}`    | `1`                                           |
+| `['off' => false]`                          | `{{off}}`        | `false`                                       |
+| `['off' => false]`                          | `{{off\|raw}}`   | `0`                                           |
+| `['items' => [1, 2], 'list' => ['a', 'b']]` | `{{items\|raw}}` | `["a", "b"]` (delegated to StringifyModifier) |

docs/modifiers/RawModifier.md

@@ -1,42 +1,83 @@
 # StringifyModifier
 
-The `StringifyModifier` converts values to strings using a `Stringifier` instance. This is the default modifier used by `PlaceholderFormatter`.
+The `StringifyModifier` always converts values to strings, regardless of their type.
+
+> **Note:** This modifier pairs well with [RawModifier](RawModifier.md). Since `StringifyModifier` may quote strings, you can use `RawModifier` to provide a `|raw` pipe for unquoted output when needed.
 
 ## Behavior
 
-- Strings pass through unchanged
-- Other types are converted using the configured stringifier
-- Throws `InvalidModifierPipeException` if an unrecognized pipe is passed
+| Pipe   | Any Value        |
+| ------ | ---------------- |
+| (none) | Stringified      |
+| Other  | Throws exception |
+
+All values are converted to strings using the stringifier. Unlike `EnsureStringModifier`, even strings are passed through the stringifier, which may or may not modify them.
 
 ## Usage
 
+The `StringifyModifier` is the default modifier in `PlaceholderFormatter`. You can also create instances with custom stringifiers:
+
 ```php
 use Respect\StringFormatter\PlaceholderFormatter;
+use Respect\StringFormatter\Modifiers\StringifyModifier;
+use Respect\Stringifier\HandlerStringifier;
+
+$stringifier = HandlerStringifier::create();
+$formatter = new PlaceholderFormatter(
+    ['name' => 'John', 'active' => true, 'items' => [1, 2]],
+    new StringifyModifier($stringifier),
+);
 
-$formatter = new PlaceholderFormatter([
-    'name' => 'John',
-    'active' => true,
-    'data' => ['x' => 1],
-]);
+echo $formatter->format('User: {{name}}');
+// Output: User: "John"
 
-echo $formatter->format('{{name}} is {{active}}');
-// Output: John is true
+echo $formatter->format('Active: {{active}}');
+// Output: Active: `true`
 
-echo $formatter->format('Data: {{data}}');
-// Output: Data: ["x":1]
+echo $formatter->format('Items: {{items}}');
+// Output: Items: `[1, 2]`
 ```
 
+## Examples
+
+| Parameters               | Template     | Output    |
+| ------------------------ | ------------ | --------- |
+| `['name' => 'John']`     | `{{name}}`   | `"John"`  |
+| `['count' => 42]`        | `{{count}}`  | `42`      |
+| `['price' => 19.99]`     | `{{price}}`  | `19.99`   |
+| `['active' => true]`     | `{{active}}` | `true`    |
+| `['active' => false]`    | `{{active}}` | `false`   |
+| `['value' => null]`      | `{{value}}`  | `null`    |
+| `['items' => [1, 2, 3]]` | `{{items}}`  | `[1,2,3]` |
+| `['data' => ['a' => 1]]` | `{{data}}`   | `["a":1]` |
+
 ## Custom Stringifier
 
 ```php
-use Respect\StringFormatter\PlaceholderFormatter;
 use Respect\StringFormatter\Modifiers\StringifyModifier;
 use Respect\Stringifier\Stringifier;
 
-$formatter = new PlaceholderFormatter(
-    ['data' => $value],
-    new StringifyModifier($customStringifier),
-);
+final readonly class CustomStringifier implements Stringifier
+{
+    public function stringify(mixed $raw): string|null
+    {
+        return is_bool($raw) ? ($raw ? 'YES' : 'NO') : json_encode($raw);
+    }
+}
+
+$modifier = new StringifyModifier(new CustomStringifier());
+echo $modifier->modify(true, null);
+// Output: YES
 ```
 
-See the [Respect\Stringifier documentation](https://github.com/Respect/Stringifier) for details on stringifiers.
+## Examples
+
+| Parameters                    | Template    | Output              |
+| ----------------------------- | ----------- | ------------------- |
+| `['name' => 'John']`          | `{{name}}`  | `"John"`            |
+| `['count' => 42]`             | `{{count}}` | `"42"`              |
+| `['on' => true]`              | `{{on}}`    | `` `true` ``        |
+| `['off' => false]`            | `{{off}}`   | `` `false` ``       |
+| `['items' => [1, 2]]`         | `{{items}}` | `` `[1, 2]` ``      |
+| `['obj' => (object)['a'=>1]]` | `{{obj}}`   | `` `stdClass {}` `` |
+| `['val' => null]`             | `{{val}}`   | `` `null` ``        |

docs/modifiers/StringifyModifier.md

@@ -28,7 +28,7 @@ Install `symfony/translation` and inject a real translator:
 ```php
 use Respect\StringFormatter\PlaceholderFormatter;
 use Respect\StringFormatter\Modifiers\TransModifier;
-use Respect\StringFormatter\Modifiers\StringifyModifier;
+use Respect\StringFormatter\Modifiers\EnsureStringModifier;
 use Symfony\Component\Translation\Translator;
 use Symfony\Component\Translation\Loader\ArrayLoader;
 

docs/modifiers/TransModifier.md

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Respect\StringFormatter\Modifiers;
+
+use Respect\StringFormatter\Modifier;
+use Respect\Stringifier\HandlerStringifier;
+use Respect\Stringifier\Stringifier;
+
+use function is_string;
+use function sprintf;
+
+final readonly class EnsureStringModifier implements Modifier
+{
+    private Stringifier $stringifier;
+
+    public function __construct(
+        Stringifier|null $stringifier = null,
+    ) {
+        $this->stringifier = $stringifier ?? HandlerStringifier::create();
+    }
+
+    public function modify(mixed $value, string|null $pipe): string
+    {
+        if ($pipe !== null) {
+            throw new InvalidModifierPipeException(sprintf('"%s" is not recognized as a valid pipe', $pipe));
+        }
+
+        if (is_string($value)) {
+            return $value;
+        }
+
+        return $this->stringifier->stringify($value);
+    }
+}