Add modifier support to PlaceholderFormatter

Although basic interpolation is useful, we often want to handle parameters
differently, not using the standard modification we apply to them. This commit
introduces modifiers, a concept already present in Respect\Validation.

We use a familiar `{{value|modifier}}` syntax found in many popular template
engines. To handle different types of modifiers, I implemented a Chain of
Responsibility, where each modifier delegates to the next one when it cannot
handle them. 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, but I’ve also made some
changes to it. I realise that for Respect. Validation, we have a strong need to
add "quotes" around strings because they represent values that were just
validated, but in the context of placeholder replacement, this behaviour is
undesirable.

I’ve created the `QuoteUnmodifiedModifier`, so we can keep the behaviour we have
in Validation when we use this library, but it won’t be added to the standard in
the default chain of responsibility I mentioned.

Assisted-by: OpenCode (GLM-4.6)
Assisted-by: Gemini 3 (Thinking)

Author: henriquemoody

docs/PlaceholderFormatter.md

@@ -0,0 +1,317 @@
+# Creating Custom Modifiers
+
+You can create custom modifiers by implementing the `Modifier` interface. This allows you to add custom transformations to placeholder values.
+
+## The Modifier Interface
+
+```php
+use Respect\StringFormatter\Modifier;
+
+interface Modifier
+{
+    public function modify(mixed $value, string|null $pipe): string;
+}
+```
+
+- `$value`: The placeholder value to transform
+- `$pipe`: The modifier name from the template (e.g., "upper" in `{{name|upper}}`)
+- Return: The transformed string value
+
+## Basic Custom Modifier
+
+Here's a simple uppercase modifier:
+
+```php
+use Respect\StringFormatter\Modifier;
+use Respect\StringFormatter\Modifier\StringifyModifier;
+
+final class UppercaseModifier implements Modifier
+{
+    public function __construct(
+        private Modifier $nextModifier,
+    ) {
+    }
+
+    public function modify(mixed $value, string|null $pipe): string
+    {
+        if ($pipe === 'upper') {
+            return strtoupper($this->nextModifier->modify($value, null));
+        }
+
+        return $this->nextModifier->modify($value, $pipe);
+    }
+}
+```
+
+## Usage Example
+
+```php
+use Respect\StringFormatter\PlaceholderFormatter;
+use Respect\StringFormatter\Modifier\RawModifier;
+use Respect\StringFormatter\Modifier\StringifyModifier;
+
+// Create the modifier chain
+$modifierChain = new UppercaseModifier(
+    new RawModifier(
+        new StringifyModifier()
+    )
+);
+
+$formatter = new PlaceholderFormatter(
+    ['message' => 'hello world', 'name' => 'John'],
+    $modifierChain
+);
+
+echo $formatter->format('{{message|upper}} says: {{name|upper}}');
+// Outputs: "HELLO WORLD says: JOHN"
+```
+
+## Modifiers with Parameters
+
+Some modifiers may need to handle parameters:
+
+```php
+use Respect\StringFormatter\Modifier;
+
+final class TruncateModifier implements Modifier
+{
+    public function __construct(
+        private Modifier $nextModifier,
+    ) {
+    }
+
+    public function modify(mixed $value, string|null $pipe): string
+    {
+        if ($pipe && str_starts_with($pipe, 'truncate:')) {
+            $length = (int) substr($pipe, 10); // Remove 'truncate:' prefix
+            $strValue = $this->nextModifier->modify($value, null);
+            return strlen($strValue) > $length
+                ? substr($strValue, 0, $length) . '...'
+                : $strValue;
+        }
+
+        return $this->nextModifier->modify($value, $pipe);
+    }
+}
+```
+
+```php
+// Usage with parameter
+$formatter = new PlaceholderFormatter(
+    ['longText' => 'This is a very long piece of text'],
+    new TruncateModifier(new StringifyModifier())
+);
+
+echo $formatter->format('{{longText|truncate:10}}');
+// Outputs: "This is a..."
+```
+
+## Best Practices
+
+### 1. Always Chain to Next Modifier
+
+Your modifier should always call `$this->nextModifier->modify()` for fallback behavior:
+
+```php
+public function modify(mixed $value, string|null $pipe): string
+{
+    // Handle your specific modifier
+    if ($pipe === 'my_modifier') {
+        return $this->processValue($value);
+    }
+
+    // Pass through to next modifier
+    return $this->nextModifier->modify($value, $pipe);
+}
+```
+
+### 2. Handle Null Pipes
+
+The `$pipe` parameter can be `null` when no modifier is specified:
+
+```php
+public function modify(mixed $value, string|null $pipe): string
+{
+    if ($pipe === null) {
+        // No modifier specified - pass through
+        return $this->nextModifier->modify($value, $pipe);
+    }
+
+    // Handle specific modifiers
+    // ...
+}
+```
+
+### 3. Type Safety
+
+Ensure your modifier handles various input types gracefully:
+
+```php
+public function modify(mixed $value, string|null $pipe): string
+{
+    if ($pipe === 'length') {
+        if (is_string($value) || is_array($value)) {
+            return (string) count($value);
+        }
+
+        // Handle non-iterable types
+        return $this->nextModifier->modify($value, $pipe);
+    }
+
+    return $this->nextModifier->modify($value, $pipe);
+}
+```
+
+### 4. Performance Considerations
+
+For high-performance modifiers, consider:
+
+- Caching expensive computations
+- Avoiding unnecessary stringifier calls
+- Using type checking for early returns
+
+```php
+final class JsonEncodeModifier implements Modifier
+{
+    private array $cache = [];
+
+    public function __construct(
+        private Modifier $nextModifier,
+    ) {
+    }
+
+    public function modify(mixed $value, string|null $pipe): string
+    {
+        if ($pipe === 'json') {
+            $cacheKey = serialize($value);
+            return $this->cache[$cacheKey] ??= json_encode($value, JSON_THROW_ON_ERROR);
+        }
+
+        return $this->nextModifier->modify($value, $pipe);
+    }
+}
+```
+
+## Advanced Examples
+
+### Currency Modifier
+
+```php
+final class CurrencyModifier implements Modifier
+{
+    public function __construct(
+        private Modifier $nextModifier,
+    ) {
+    }
+
+    public function modify(mixed $value, string|null $pipe): string
+    {
+        if ($pipe === 'currency') {
+            if (!is_numeric($value)) {
+                return $this->nextModifier->modify($value, $pipe);
+            }
+
+            return '$' . number_format((float) $value, 2);
+        }
+
+        return $this->nextModifier->modify($value, $pipe);
+    }
+}
+```
+
+### Date Format Modifier
+
+```php
+final class DateFormatModifier implements Modifier
+{
+    public function __construct(
+        private Modifier $nextModifier,
+    ) {
+    }
+
+    public function modify(mixed $value, string|null $pipe): string
+    {
+        if ($pipe && str_starts_with($pipe, 'date:')) {
+            $format = substr($pipe, 5); // Remove 'date:' prefix
+
+            if ($value instanceof DateTimeInterface) {
+                return $value->format($format);
+            }
+
+            if (is_string($value)) {
+                try {
+                    $date = new DateTime($value);
+                    return $date->format($format);
+                } catch (Exception) {
+                    // Invalid date format
+                }
+            }
+
+            return $this->nextModifier->modify($value, $pipe);
+        }
+
+        return $this->nextModifier->modify($value, $pipe);
+    }
+}
+```
+
+## Testing Custom Modifiers
+
+Unit test your modifiers thoroughly:
+
+```php
+use PHPUnit\Framework\TestCase;
+
+class UppercaseModifierTest extends TestCase
+{
+    public function testUppercase(): void
+    {
+        $nextModified = $this->createMock(Modifier::class);
+        $nextModified->method('modify')->willReturn('test');
+
+        $modifier = new UppercaseModifier($nextModified);
+
+        $result = $modifier->modify('hello', 'upper');
+
+        $this->assertEquals('TEST', $result);
+    }
+
+    public function testPassThrough(): void
+    {
+        $nextModified = $this->createMock(Modifier::class);
+        $nextModified->expects($this->once())
+            ->method('modify')
+            ->with('value', 'other_modifier')
+            ->willReturn('output');
+
+        $modifier = new UppercaseModifier($nextModified);
+
+        $result = $modifier->modify('value', 'other_modifier');
+
+        $this->assertEquals('output', $result);
+    }
+}
+```
+
+## Integration with PlaceholderFormatter
+
+When using custom modifiers, you need to construct the full chain:
+
+```php
+// Example: CustomModifier -> RawModifier -> StringifyModifier
+$modifier = new MyCustomModifier(
+    new RawModifier(
+        new StringifyModifier()
+    )
+);
+
+$formatter = new PlaceholderFormatter($data, $modifier);
+```
+
+Or use the existing default chain and prepend:
+
+```php
+$defaultChain = new RawModifier(new StringifyModifier());
+$modifier = new MyCustomModifier($defaultChain);
+$formatter = new PlaceholderFormatter($data, $modifier);
+```