woocommerce/plugins/woocommerce-blocks/docs/extensibility/extend-rest-api-formatters.md

# 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.

- [MoneyFormatter](#MoneyFormatter)
- [CurrencyFormatter](#CurrencyFormatter)
- [HtmlFormatter](#HtmlFormatter)

## 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).

```php
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:
```php
format( $value, array $options = [] );
``` 
Only `MoneyFormatter`'s behaviour can be controlled by the `$options` parameter. 

## MoneyFormatter
The [`MoneyFormatter`](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/trunk/src/StoreApi/Formatters/MoneyFormatter.php)
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](https://www.php.net/manual/en/function.round.php). Defaults to `PHP_ROUND_HALF_UP`.
  
### Example use and returned value
```php
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
```php
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`](https://developer.wordpress.org/reference/functions/wptexturize/),
[`convert_chars`](https://developer.wordpress.org/reference/functions/convert_chars/),
[`trim`](https://www.php.net/manual/en/function.trim.php), and [`wp_kses_post`](https://developer.wordpress.org/reference/functions/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
```php
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>.`