9.7 KiB
Formatters
Table of Contents
Formatters are utility classes that allow you to format values to so that they are compatible with the StoreAPI. Default formatters handle values such as monetary amounts, currency information, or HTML.
It is recommended that you use these formatters when you are extending the StoreAPI.
Why are formatters useful?
Using the formatter utilities when returning certain types of data will ensure that your custom data is consistent and compatible with other endpoints. They also take care of any store specific settings that may affect the formatting of the data, such as currency settings.
Store API includes formatters for:
How to use formatters
To get a formatter, you can use the get_formatter method of the ExtendSchema class. This method accepts a string, which is the name of the formatter you want to use.
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 behavior can be controlled by the $options parameter. This parameter is optional.
Real world example
Let's say we're going to be returning some extra price data via the API. We want to return the price in cents, and also the currency data for the store. We can use the MoneyFormatter and CurrencyFormatter to do this.
First we need to ensure we can access the formatter classes. We can do this by using the use keyword:
use Automattic\WooCommerce\StoreApi\StoreApi;
use Automattic\WooCommerce\StoreApi\Utilities\ExtendSchema;
$extend = StoreApi::container()->get( ExtendSchema::class );
$my_custom_price = $extend->get_formatter( 'money' )->format( '10.00', [
'rounding_mode' => PHP_ROUND_HALF_DOWN,
'decimals' => 2
] );
$price_response = $extend->get_formatter( 'currency' )->format( [
'price' => $my_custom_price,
] );
The above code would result in $price_response being set to:
[
'price' => '1000'
'currency_code' => 'GBP'
'currency_symbol' => '£'
'currency_minor_unit' => 2
'currency_decimal_separator' => '.'
'currency_thousand_separator' => ','
'currency_prefix' => '£'
'currency_suffix' => ''
]
MoneyFormatter
The MoneyFormatter class can be used to format a monetary value using the store settings. The store settings may be overridden by passing options to this formatter's format method.
Values are returned in cents to avoid floating point rounding errors, so when using this formatter you'll most likely also be returning the currency data using the CurrencyFormatter alongside it. This will allow the consumer of the API to display the value in the intended format.
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 appended to it. 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. |
This data can then be used by the client/consumer to format prices correctly according to store settings. Important: the array of prices passed to this formatted should already be in monetary format so you should use the MoneyFormatter first.
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>.
This formatter should be used when returning HTML from the StoreAPI regardless of whether the HTML is user generated or not. This will ensure the consumer/client can display the HTML safely and without encoding issues.
We're hiring! Come work with us!
🐞 Found a mistake, or have a suggestion? Leave feedback about this document here.