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

114 lines
4.6 KiB
Markdown
Raw Normal View History

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