Add modifier support to PlaceholderFormatter

While basic template interpolation is useful, we know that a one-size-fits-all
stringification approach isn't always desirable. Sometimes you need to bypass the
standard formatting logic or transform a value before it hits the final string.
This commit introduces a flexible modifier system to solve that.

I’ve adopted the familiar `{{value|modifier}}` syntax found in many popular
template engines. To handle this transformation, I implemented a Chain of
Responsibility pattern. This allows us to pipe values through specific logic,
such as the new `|raw` modifier, which provides clean scalar output by
bypassing the default stringifier formatting.

The `StringifyModifier` remains the default fallback, ensuring that we don't
lose the robust type-handling we previously built. By separating these
transformations into an extensible modifier interface, we’ve made the system
future-proof—users can now plug in custom transformations without touching
the core formatting logic.

This change turns our simple placeholder replacement into a proper
interpolation engine, giving developers fine-grained control over how their
data is presented.

Assisted-by: OpenCode (GLM-4.6)

Author: henriquemoody

docs/PlaceholderFormatter.md

@@ -13,26 +13,48 @@ use Respect\Stringifier\HandlerStringifier;
 $formatter = new PlaceholderFormatter(['name' => 'John', 'age' => 30]);
 
 echo $formatter->format('Hello {{name}}, you are {{age}} years old.');
-// Outputs: "Hello John, you are 30 years old."
+// Outputs: "Hello "John", you are 30 years old."
 ```
 
-### With Custom Stringifier
+### With Custom Modifiers
 
 ```php
+use App\StringFormatter\Modifiers\MyModifier;
 use Respect\StringFormatter\PlaceholderFormatter;
-use Respect\Stringifier\HandlerStringifier;
 
-$stringifier = HandlerStringifier::create();
+$modifier = new MyModifier();
 
 $formatter = new PlaceholderFormatter(
-    ['name' => 'John', 'items' => ['a', 'b', 'c']],
-    $stringifier
+    ['count' => 42, 'name' => 'John'],
+    $modifier
 );
 
-echo $formatter->format('Hello {{name}}, items: {{items}}');
-// Outputs: "Hello John, items: [a, b, c]"
+echo $formatter->format('Hello {{name}}, you are {{age}} years old.');
+// Outputs: "Hello --John--, you are --30-- years old."
+```
+
+### Modifiers
+
+Placeholders can include modifiers that transform values before final stringification. See the [Modifiers](modifiers/Modifiers.md) documentation for complete details.
+
+```php
+use Respect\StringFormatter\PlaceholderFormatter;
+use Respect\StringFormatter\Modifier\RawModifier;
+use Respect\StringFormatter\Modifier\StringifyModifier;
+
+$formatter = new PlaceholderFormatter(['name' => 'John', 'age' => 30]);
+
+echo $formatter->format('Hello {{name|raw}}, you are {{age}} years old.');
+// Outputs: "Hello John, you are 30 years old."
 ```
 
+**Available Topics:**
+
+- [Modifiers Overview](modifiers/Modifiers.md) - How modifiers work and basic usage
+- [RawModifier](modifiers/RawModifier.md) - Outputs scalar values without stringifier formatting
+- [StringifyModifier](modifiers/StringifyModifier.md) - Default modifier using stringifier
+- [Creating Custom Modifiers](modifiers/CreatingCustomModifiers.md) - Build your own modifiers
+
 ### Using Additional Parameters
 
 The `formatWith` method allows passing additional parameters at format time. Constructor parameters take precedence and won't be overwritten.
@@ -55,14 +77,16 @@ echo $formatter->formatWith(
 
 ### `PlaceholderFormatter::__construct`
 
-- `__construct(array $parameters, Stringifier|null $stringifier = null)`
+- `__construct(array $parameters, Modifier|null $modifier = null)`
 
-Creates a new formatter instance with the specified parameters and stringifier.
+Creates a new formatter instance with the specified parameters and optional modifier chain.
 
 **Parameters:**
 
 - `$parameters`: Associative array of placeholder names to values
-- `$stringifier`: Stringifier instance for converting all non-string values to strings. If `null`, it creates its own stringifier.
+- `$modifier`: Optional modifier chain for processing values before final stringification. If `null`, uses a default `RawModifier` with `StringifyModifier`. See [Modifiers](modifiers/Modifiers.md) for details.
+
+The formatter internally uses `HandlerStringifier::create()` for stringifying non-string values.
 
 ### `format`
 
@@ -99,57 +123,48 @@ Formats the template string with additional parameters merged with constructor p
 
 ### Placeholder Format
 
-Placeholders follow the format `{{name}}` where `name` is a valid parameter key.
+Placeholders follow the format `{{name}}` where `name` is a valid parameter key. Modifiers can be added after a pipe: `{{name|modifier}}`. See [Modifiers](modifiers/Modifiers.md) for complete modifier documentation.
 
 **Rules:**
 
 - Placeholder names must match the regex pattern `\w+` (word characters: letters, digits, underscore)
 - Names are case-sensitive: `{{Name}}` and `{{name}}` are different placeholders
 - Placeholders can appear multiple times in the template
 - Whitespace inside braces is not allowed: `{{ name }}` will not match
+- No whitespace is allowed between the pipe and modifier name: `{{name| raw}}` will not work
 
 **Valid placeholders:**
 
 - `{{name}}`
 - `{{firstName}}`
 - `{{value123}}`
 - `{{user_id}}`
+- `{{name|raw}}`
+- `{{count|raw}}`
 
 **Invalid placeholders (treated as literals):**
 
 - `{name}` (single braces)
 - `{{ name }}` (contains spaces)
 - `{{first-name}}` (contains hyphen)
 - `{{}}` (empty)
+- `{{name| raw}}` (space after pipe)
 
 ## Type Handling
 
-The formatter uses the injected `Stringifier` to convert all parameter values to strings:
-
-| Type       | Behavior                                                       | Example                                               |
-| ---------- | -------------------------------------------------------------- | ----------------------------------------------------- |
-| `string`   | Used as-is                                                     | `"hello"` → `"hello"`                                 |
-| `int`      | Converted using stringifier                                    | `42` → `"42"`                                         |
-| `float`    | Converted using stringifier                                    | `19.99` → `"19.99"`                                   |
-| `bool`     | Converted using stringifier with backticks                     | `true` → `` `true` ``, `false` → `` `false` ``        |
-| `null`     | Converted using stringifier with backticks                     | `null` → `` `null` ``                                 |
-| `array`    | Converted using stringifier (or `print_r` as fallback)         | `[1, 2]` → `"[1, 2]"` (varies)                        |
-| `object`   | Converted using stringifier (or `print_r` as fallback)         | Varies by object type                                 |
-| Stringable | Converted using stringifier (includes metadata with backticks) | `__toString()` → `` `Stringable@anonymous { ... }` `` |
-| Resource   | Converted using stringifier (or `print_r` as fallback)         | Resource representation                               |
-| Missing    | Keeps placeholder unchanged (parameter key doesn't exist)      | N/A → `"{{name}}"`                                    |
+The formatter uses the injected `Stringifier` to convert all parameter values to strings. See the [Respect\Stringifier](https://github.com/Respect/Stringifier) documentation for details on type conversions.
 
 ## Behavior
 
 ### Successful Replacement
 
 When a placeholder name exists as a parameter key:
 
-- The placeholder is replaced with the stringified value (using the injected `Stringifier`)
-- String values are used as-is without stringification
-- All non-string values (including `null`) are converted using the stringifier
+- The placeholder is replaced with the value processed through the modifier pipe
+- All values (including `null`) are converted using the default `HandlerStringifier` unless a modifier handles them differently
 - Empty strings are valid replacements: `""` replaces the placeholder with nothing
 - Zero values are valid: `0` and `0.0` are replaced with their string representations
+- Modifiers can transform values: `{{count|raw}}` outputs the raw scalar value without stringifier formatting (see [Modifiers](modifiers/Modifiers.md))
 
 ### Placeholder Preservation
 
@@ -366,15 +381,3 @@ echo $formatter->format('{{greeting}} {{name}}');
 - **No expressions**: `{{x + y}}` is not evaluated; only simple value replacement
 - **No conditional logic**: No if/else or ternary operations
 - **No default values**: Use null checks in PHP before passing parameters
-
-## Future Extensions
-
-The implementation is designed to support modifiers in a future phase:
-
-```php
-// Future syntax (not yet implemented)
-$formatter->format('Hello {{name|upper}}!');
-// Would output: "Hello JOHN!"
-```
-
-The regex pattern and internal structure are prepared for this extension without breaking changes.