Skip to content

Latest commit

 

History

History
83 lines (63 loc) · 3.13 KB

FormatterModifier.md

File metadata and controls

83 lines (63 loc) · 3.13 KB

FormatterModifier

The FormatterModifier enables using any formatter as a placeholder modifier. It parses the pipe syntax, dynamically instantiates the requested formatter, and applies it to the value.

Supported Formatters

Modifier Example Syntax Input Output
date {{val|date:d/m/Y}} 2024-01-15 15/01/2024
number {{val|number:2:,:.}} 1234.567 1.234,57
mask {{val|mask:1-4:X}} 1234567890 XXXX567890
pattern {{val|pattern:(###) ###-####}} 1234567890 (123) 456-7890
metric {{val|metric:m}} 1500 1.5km
mass {{val|mass:g}} 1000 1kg
area {{val|area:m^2}} 10000 1ha
time {{val|time:s}} 3600 1h
imperialLength {{val|imperialLength:in}} 36 1yd
imperialMass {{val|imperialMass:oz}} 16 1lb
imperialArea {{val|imperialArea:ft^2}} 43560 1ac

For detailed documentation on each formatter, see the README.

Syntax

{{placeholder|formatterName}}
{{placeholder|formatterName:arg1}}
{{placeholder|formatterName:arg1:arg2:arg3}}

The formatter name is converted to a class name by capitalizing the first letter and appending "Formatter" (e.g., date becomes DateFormatter).

Escaping Special Characters

If your formatter arguments contain : or |, escape them with a backslash:

{{placeholder|pattern:##\:##}}        // Pattern with colon: 12:34
{{placeholder|pattern:###\|###}}      // Pattern with pipe: 123|456

Example

use Respect\StringFormatter\PlaceholderFormatter;

$formatter = new PlaceholderFormatter([
    'date' => '2024-01-15',
    'amount' => '1234.56',
    'phone' => '1234567890',
]);

$template = <<<'TEMPLATE'
Date: {{date|date:d/m/Y}}
Amount: ${{amount|number:2}}
Phone: {{phone|pattern:(###) ###-####}}
TEMPLATE;

echo $formatter->format($template);
// Output:
// Date: 15/01/2024
// Amount: $1,234.56
// Phone: (123) 456-7890

Behavior

  • If the formatter class doesn't exist, it delegates to the next modifier in the chain
  • If construction fails (invalid arguments), it delegates to the next modifier
  • If formatting throws an exception, it delegates to the next modifier
  • Non-string values are converted to strings before formatting

Limitations

  • Formatter arguments must be strings (they're split by : from the pipe)
  • Complex objects or arrays cannot be passed as formatter arguments
  • Formatter names must match the class name pattern (capitalized name + "Formatter")