Skip to content

Latest commit

 

History

History
145 lines (105 loc) · 7.13 KB

extend-rest-api-formatters.md

File metadata and controls

145 lines (105 loc) · 7.13 KB
Raw

Formatters

Table of Contents

Formatters 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 ExtendSchema 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 &#8220;coffee&#8221; is <strong>very strong</strong>.

We're hiring! Come work with us!

🐞 Found a mistake, or have a suggestion? Leave feedback about this document here.