Number

class Cake\View\Helper\NumberHelper(View $view, array $config = [])

The NumberHelper contains convenient methods that enable display numbers in common formats in your views. These methods include ways to format currency, percentages, data sizes, format numbers to specific precisions and also to give you more flexibility with formatting numbers.

}

}

<!-- start-cakenumber -->

All of these functions return the formatted number; they do not
automatically echo the output into the view.

## Formatting Currency Values

### Number::currency()

`method` Cake\\I18n\\Number::**currency**(mixed $value, string $currency = null, array $options = []): string

This method is used to display a number in common currency formats
(EUR, GBP, USD), based on the 3-letter ISO 4217 currency code. Usage in a view looks like:

```php
// Called as NumberHelper
echo $this->Number->currency($value, $currency);

// Called as Number
echo Number::currency($value, $currency);

The first parameter, $value, should be a floating point number that represents the amount of money you are expressing. The second parameter is a string used to choose a predefined currency formatting scheme:

$currency	1234.56, formatted by currency type
EUR	€1.234,56
GBP	£1,234.56
USD	$1,234.56

The third parameter is an array of options for further defining the output. The following options are available:

Option	Description
before	Text to display before the rendered number.
after	Text to display after the rendered number.
zero	The text to use for zero values; can be a string or a number. i.e. 0, 'Free!'.
places	Number of decimal places to use, i.e. 2
precision	Maximal number of decimal places to use, i.e. 2
locale	The locale name to use for formatting number, i.e. "fr_FR".
fractionSymbol	String to use for fraction numbers, i.e. ' cents'.
fractionPosition	Either 'before' or 'after' to place the fraction symbol.
pattern	An ICU number pattern to use for formatting the number i.e. #,###.00
useIntlCode	Set to true to replace the currency symbol with the international currency code.

If $currency value is null, the default currency will be retrieved from Cake\I18n\Number::defaultCurrency(). To format currencies in an accounting format you should set the currency format:

Number::setDefaultCurrencyFormat(Number::FORMAT_CURRENCY_ACCOUNTING);

Setting the Default Currency

Number::setDefaultCurrency()

static Cake\I18n\Number::setDefaultCurrency(?string $currency = null): void

Setter for the default currency. This removes the need to always pass the currency to Cake\I18n\Number::currency() and change all currency outputs by setting other default. If $currency is set to null, it will clear the currently stored value.

Getting the Default Currency

Number::getDefaultCurrency()

method Cake\I18n\Number::getDefaultCurrency(): string

Getter for the default currency. If default currency was set earlier using setDefaultCurrency(), then that value will be returned. By default, it will retrieve the intl.default_locale ini value if set and 'en_US' if not.

Formatting Floating Point Numbers

Number::precision()

method Cake\I18n\Number::precision(float $value, int $precision = 3, array $options = []): string

This method displays a number with the specified amount of precision (decimal places). It will round in order to maintain the level of precision defined.

// Called as NumberHelper
echo $this->Number->precision(456.91873645, 2);

// Outputs
456.92

// Called as Number
echo Number::precision(456.91873645, 2);

Formatting Percentages

Number::toPercentage()

method Cake\I18n\Number::toPercentage(mixed $value, int $precision = 2, array $options = []): string

Option	Description
multiply	Boolean to indicate whether the value has to be multiplied by 100. Useful for decimal percentages.

Like Cake\I18n\Number::precision(), this method formats a number according to the supplied precision (where numbers are rounded to meet the given precision). This method also expresses the number as a percentage and appends the output with a percent sign.

// Called as NumberHelper. Output: 45.69%
echo $this->Number->toPercentage(45.691873645);

// Called as Number. Output: 45.69%
echo Number::toPercentage(45.691873645);

// Called with multiply. Output: 45.7%
echo Number::toPercentage(0.45691, 1, [
    'multiply' => true,
]);

Interacting with Human Readable Values

Number::toReadableSize()

method Cake\I18n\Number::toReadableSize(mixed $size, ?bool $useIecUnits = null): string

This method formats data sizes in human-readable forms. By default, it converts bytes to KB, MB, GB, and TB. The parameter $useIecUnits and the global setter setUseIecUnits() can be used to switch to ISO/IEC 80000-13 units, which are KiB, MiB, GiB, and TiB. The size is displayed with a two-digit precision level, according to the amount of data supplied (i.e., higher sizes are expressed in larger terms):

// By default, decimal units are used
// Called as NumberHelper
echo $this->Number->toReadableSize(0); // 0 Bytes
echo $this->Number->toReadableSize(1024); // 1.02 KB
echo $this->Number->toReadableSize(1321205.76); // 1.32 MB
echo $this->Number->toReadableSize(5368709120); // 5.37 GB

// Called as Number
echo Number::toReadableSize(0); // 0 Bytes
echo Number::toReadableSize(1024); // 1.02 KB
echo Number::toReadableSize(1321205.76); // 1.32 MB
echo Number::toReadableSize(5368709120); // 5.37 GB

// Change default units to IEC units
$this->Number->setUseIecUnits(true);

// Bytes are now calculated with exponents of two using IEC units
echo $this->Number->toReadableSize(0); // 0 Bytes
echo $this->Number->toReadableSize(1024); // 1 KiB
echo $this->Number->toReadableSize(1321205.76); // 1.26 MiB
echo $this->Number->toReadableSize(5368709120); // 5 GiB

It should be noted that IEC units are exponents of two and decimal units of ten. This mean that:

• 1000 Bytes = 1 KB
• 1024 Bytes = 1 KiB

Modified in version 5.4.0

It is now possible to use the byte units defined by the ISO/IEC 80000-13 standard alongside more natural decimal units.

Setting the Default Byte Units

Number::setUseIecUnits()

static Cake\I18n\Number::setUseIecUnits(bool $useIec): void

This method acts as a setter for the default byte units. It eliminates the need to pass the boolean parameter to Cake\I18n\Number::toReadableSize() when switching between decimal units and IEC units. If $useIec is defined as true, IEC units will be employed; otherwise, decimal units will be used.

Added in version 5.4.0

This method has been added to remove the need to pass the optionnal boolean argument each time IEC units are needed.

Formatting Numbers

Number::format()

method Cake\I18n\Number::format(mixed $value, array $options = []): string

This method gives you much more control over the formatting of numbers for use in your views (and is used as the main method by most of the other NumberHelper methods). Using this method might looks like:

// Called as NumberHelper
$this->Number->format($value, $options);

// Called as Number
Number::format($value, $options);

The $value parameter is the number that you are planning on formatting for output. With no $options supplied, the number 1236.334 would output as 1,236. Note that the default precision is zero decimal places.

The $options parameter is where the real magic for this method resides.

• If you pass an integer then this becomes the amount of precision or places for the function.
• If you pass an associated array, you can use the following keys:

Option	Description
places	Number of decimal places to use, i.e. 2
precision	Maximum number of decimal places to use, i.e. 2
pattern	An ICU number pattern to use for formatting the number i.e. #,###.00
locale	The locale name to use for formatting number, i.e. "fr_FR".
before	Text to display before the rendered number.
after	Text to display after the rendered number.

Example:

// Called as NumberHelper
echo $this->Number->format('123456.7890', [
    'places' => 2,
    'before' => '¥ ',
    'after' => ' !',
]);
// Output '¥ 123,456.79 !'

echo $this->Number->format('123456.7890', [
    'locale' => 'fr_FR',
]);
// Output '123 456,79 !'

// Called as Number
echo Number::format('123456.7890', [
    'places' => 2,
    'before' => '¥ ',
    'after' => ' !',
]);
// Output '¥ 123,456.79 !'

echo Number::format('123456.7890', [
    'locale' => 'fr_FR',
]);
// Output '123 456,79 !'

Number::ordinal()

method Cake\I18n\Number::ordinal(mixed $value, array $options = []): string

This method will output an ordinal number.

Examples:

echo Number::ordinal(1);
// Output '1st'

echo Number::ordinal(2);
// Output '2nd'

> [!WARNING]
> All symbols are UTF-8.