Replace AutoQuoteModifier with a different modifier strategy

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:

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

- `StringPassthroughModifier`: This now has a very narrow focus. It only
  stringifies non-string values, leaving existing strings untouched.

- `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, should not include
`StringPassthroughModifier` but instead use `RawModifier` in the chain, so users
can opt-out of stringification with 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

@@ -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
+- **[StringifyModifier](StringifyModifier.md)** - Always converts values to strings (default)
+- **[StringPassthroughModifier](StringPassthroughModifier.md)** - Returns strings unchanged, delegates non-strings to next modifier
 - **[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 only useful when [StringPassthroughModifier](StringPassthroughModifier.md) is **not** in the chain. When using `StringifyModifier` directly (without `StringPassthroughModifier`), strings get quoted by default and `RawModifier` provides the `|raw` pipe for unquoted output. The default chain includes `StringPassthroughModifier`, so strings are already unquoted.
+
+## 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

@@ -0,0 +1,55 @@
+# StringPassthroughModifier
+
+The `StringPassthroughModifier` returns string values unchanged and delegates non-string values to the next modifier in the chain.
+
+## Behavior
+
+| Pipe  | String             | Other Types                |
+| ----- | ------------------ | -------------------------- |
+| (any) | Returned unchanged | Delegates to next modifier |
+
+- Strings are returned as-is without any processing
+- Non-strings are passed to the next modifier along with the pipe
+- This modifier does not handle any pipes itself
+
+This modifier is useful when you want to preserve string values while allowing non-strings to be processed by another modifier (e.g., `StringifyModifier`).
+
+## Usage
+
+```php
+use Respect\StringFormatter\PlaceholderFormatter;
+use Respect\StringFormatter\Modifiers\StringPassthroughModifier;
+use Respect\StringFormatter\Modifiers\StringifyModifier;
+
+$formatter = new PlaceholderFormatter(
+    [
+        'name' => 'John',
+        'active' => true,
+        'data' => ['x' => 1],
+    ],
+    new StringPassthroughModifier(new StringifyModifier()),
+);
+
+echo $formatter->format('{{name}} is {{active}}');
+// Output: John is true
+
+echo $formatter->format('Data: {{data}}');
+// Output: Data: ["x":1]
+```
+
+## Examples
+
+When used with `StringifyModifier`:
+
+| 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]` |
+
+Note that string values like `John` are returned unchanged (not quoted), while non-string values are stringified by `StringifyModifier`.

docs/modifiers/StringPassthroughModifier.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:** When used directly (without [StringPassthroughModifier](StringPassthroughModifier.md)), this modifier quotes strings. In that case, [RawModifier](RawModifier.md) can provide a `|raw` pipe for unquoted output. The default chain includes `StringPassthroughModifier`, which bypasses stringification for strings.
 
 ## 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 `StringPassthroughModifier`, 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\StringPassthroughModifier;
 use Symfony\Component\Translation\Translator;
 use Symfony\Component\Translation\Loader\ArrayLoader;
 

docs/modifiers/TransModifier.md

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Respect\StringFormatter\Modifiers;
+
+use Respect\StringFormatter\Modifier;
+
+use function is_bool;
+use function is_scalar;
+
+final readonly class RawModifier implements Modifier
+{
+    public function __construct(
+        private Modifier $nextModifier,
+    ) {
+    }
+
+    public function modify(mixed $value, string|null $pipe): string
+    {
+        if ($pipe !== 'raw') {
+            return $this->nextModifier->modify($value, $pipe);
+        }
+
+        if (!is_scalar($value)) {
+            return $this->nextModifier->modify($value, null);
+        }
+
+        return is_bool($value) ? (string) (int) $value : (string) $value;
+    }
+}