4.6 KiB
Formatters
As part of ExtendRestAPI, we introduced Formatters, these are utility classes that allow you to format values to
so that they are compatible with the StoreAPI, values such as money, currency, or HTML.
How to use them
To get a formatter, you can use the get_formatter method of the ExtendRestApi class. This method accepts a string,
which is the name of the formatter you want to use, e.g. (money, html, currency).
get_formatter('money'); // For the MoneyFormatter
get_formatter('html'); // For the HtmlFormatter
get_formatter('currency'); // CurrencyFormatter
This returns a FormatterInterface which has the format method.
The format method signature is:
format( $value, array $options = [] );
Only MoneyFormatter's behaviour can be controlled by the $options parameter.
MoneyFormatter
The MoneyFormatter
class can be used to format a monetary value using the store settings. The store settings may be overriden by passing
options to this formatter's format method.
Arguments
| Argument | Type | Description |
|---|---|---|
$value |
number |
The number you want to format into a monetary value |
$options |
array |
Should contain two keys, decimals which should be an integer, |
$options['decimals'] |
number |
Used to control how many decimal places should be displayed in the monetary value. Defaults to the store setting. |
$options['rounding_mode'] |
number |
Used to determine how to round the monetary value. This should be one of the PHP rounding modes described in the PHP round() documentation. Defaults to PHP_ROUND_HALF_UP. |
Example use and returned value
get_formatter( 'money' )->format( 10.443, [
'rounding_mode' => PHP_ROUND_HALF_DOWN,
'decimals' => 2
] );
returns 1044
CurrencyFormatter
This formatter takes an array of prices, and returns the same array but with currency data added. The currency data added is:
| Key | Type | Description |
|---|---|---|
currency_code |
string |
The string representation of the currency, e.g. GPB or USD |
currency_symbol |
string |
The symbol of the currency, e.g. £ or $ |
currency_minor_unit |
number |
How many decimal places will be shown in the currency |
currency_decimal_separator |
string |
The string used to separate the whole value and the decimal value in the currency. |
currency_thousand_separator |
string |
The string used to separate thousands in the currency, for example: £10,000 or €10.000 |
currency_prefix |
string |
A string that should appear before the currency value. |
currency_suffix |
string |
A string that should appear after the currency value. |
Arguments
| Argument | Type | Description |
|---|---|---|
$value |
number[] |
An array of prices that you want to merge with the store's currency settings |
Example use and returned value
get_formatter( 'currency' )->format( [
'price' => 1800,
'regular_price' => 1800,
'sale_price' => 1800,
] );
returns
'price' => '1800'
'regular_price' => '1800'
'sale_price' => '1800'
'price_range' => null
'currency_code' => 'GBP'
'currency_symbol' => '£'
'currency_minor_unit' => 2
'currency_decimal_separator' => '.'
'currency_thousand_separator' => ','
'currency_prefix' => '£'
'currency_suffix' => ''
HtmlFormatter
This formatter will take an HTML value, run it through: wptexturize,
convert_chars,
trim, and wp_kses_post
before returning it. The purpose of this formatter is to make HTML "safe" (in terms of correctly formatted characters).
wp_kses_post will ensure only HTML tags allowed in the context of a post are present in the string.
Arguments
| Argument | Type | Description |
|---|---|---|
$value |
string |
The string you want to format into "safe" HTML. |
Example use and returned value
get_formatter( 'html' )->format(
"<script>alert('bad script!')</script> This \"coffee\" is <strong>very strong</strong>."
);
returns
alert('bad script!') This “coffee” is <strong>very strong</strong>.