numbers.md

Numbers

Format setting and use across the project. The class provide many options, all options has default value. The class is immutable, the property are read only. If you want any to change setup, let's use method modify(). Both classes IntlNumberFormatter and NumberFormatter has implemented interface Formatter.

NumberFormatter by h4kuna

The class wraps a php function number_format and extends the behavior.

Parameters

The parameters are same for methods __construct() and modify().

The class NumberFormatter is Immutable when you use modify().

NumberFormatter

• decimals [2]: Sets the number of decimal digits.
• decimalPoint [',']: Sets the separator for the decimal point.
• thousandsSeparator [' ']: Sets the thousands separator.
• nbsp [true]: Replace space by   like utf-8 char.
• zeroClear [ZeroClear::NO]: Clear zero from right after decimal point.
  • ZeroClear::NO: disabled 1.0 -> 1,00
  • ZeroClear::DECIMALS_EMPTY: 1.0 -> 1, 1.50 -> 1,50
  • ZeroClear::DECIMALS: 1.0 -> 1, 1.50 -> 1,5
• emptyValue [\x00]: By default is disabled, if value is empty (by default null or empty string '') will display some wildcard
• zeroIsEmpty [false]: By default is disabled, only null and empty string '' are replaced by emptyValue, but by this option is zero empty value too.
• unit ['']: Disabled, define unit for formatted number, $, €, kg etc...
• showUnitIfEmpty [false]: Unit must be defined, show unit if is empty value.
• mask [1 ⎵]: If you want to define 1 € or $ 1.
• round [null]: Change round function, let's use Round::BY_CEIL or Round::BY_FLOOR.

Examples

Basic usage:

use h4kuna\Format\Number\Formatters\NumberFormatter;
$number = 1234.456;

$format = new NumberFormatter();
echo $format->format($number); // 1⎵234,46 // in this example char ⎵ represent &nbsp
echo $format->modify(unit: 'Kg')->format($number); // 1⎵234,46⎵Kg

nbsp

disable nbsp for all examples

$format = $format->modify(nbsp: false);
echo $format->format($number); // 1 234,46

decimals

echo $format->modify(decimals: 1)->format($number); // 1 234,5
echo $format->modify(decimals: 0)->format($number); // 1 234
echo $format->modify(decimals: -1)->format($number); // 1 230

decimalPoint

echo $format->modify(decimalPoint: '.')->format($number); // 1 234.46

thousandsSeparator

echo $format->modify(decimalPoint: '.', thousandsSeparator: ',')->format($number); // 1,234.46

zeroClear

use h4kuna\Format\Number\Parameters\ZeroClear;

echo $format->modify(decimals: 4, zeroClear: ZeroClear::NO)->format($number); // 1 234,4560

echo $format->modify(decimals: 4, zeroClear: ZeroClear::DECIMALS_EMPTY)->format($number); // 1 234,4560
echo $format->modify(decimals: 4, zeroClear: ZeroClear::DECIMALS_EMPTY)->format('1234.000'); // 1 234

echo $format->modify(decimals: 4, zeroClear: ZeroClear::DECIMALS)->format($number); // 1 234,456
echo $format->modify(decimals: 4, zeroClear: ZeroClear::DECIMALS)->format('1234.000'); // 1 234

emptyValue

echo $format->modify(emptyValue: '-')->format(null); // -
echo $format->modify(emptyValue: '-')->format(''); // -
echo $format->modify(emptyValue: '-')->format(0); // 0,00 if you want zero replace by empty value set zeroIsEmpty

zeroIsEmpty

echo $format->modify(emptyValue: '-', zeroIsEmpty: true)->format(0); // -

unit

echo $format->modify(unit: 'Kg')->format($number); // 1 234,46 Kg
echo $format->modify(unit: '%')->format($number); // 1 234,46 %
echo $format->modify(unit: '€')->format($number); // 1 234,46 €

showUnitIfEmpty

echo $format->modify(unit: 'Kg')->format(0); // 0,00 Kg
echo $format->modify(unit: 'Kg', showUnitIfEmpty: false)->format(0); // 0,00

mask

echo $format->modify(unit: '€', mask: '⎵1')->format($number); // €1 234,46

round

echo $format->modify(decimals: 0)->format($number); // 1 234
echo $format->modify(decimals: 0, round: Round::BY_CEIL)->format($number); // 1 235
echo $format->modify(decimals: 0, round: Round::BY_FLOOR)->format($number); // 1 234

IntlNumberFormatter

Support php native NumberFormatter and extends by two parameters $emptyValue and $zeroIsEmpty.

use NumberFormatter;
use h4kuna\Format\Number\NativePhp\NumberFormatterFactory;

$numberFormatter = new NumberFormatter('cs_CZ', NumberFormatter::CURRENCY);
// or use prepared factory
$numberFormatterFactory = new NumberFormatterFactory('cs_CZ');
$numberFormatter = $numberFormatterFactory->currency();

$format = new IntlNumberFormatter($numberFormatter);
echo $format->format($number); // 1 234,46 Kč

$numberFormatter = $numberFormatterFactory->currency('en_GB');
$format = new IntlNumberFormatter($numberFormatter);
echo $format->format($number); // £1,234.46

Collection of NumberFormat

Keep all defined formatters on one place.

use h4kuna\Format\Number\Formats;
use h4kuna\Format\Number\Formatters\NumberFormatter;

$formats = new Formats([
	'EUR' => static fn (Formats $formats) => new NumberFormatter(decimals: 0, nbsp: false, unit: '€'), // callback like factory if is needed
	'GBP' => new NumberFormatter(nbsp: false, unit: '£', mask: '⎵ 1'),
]);

$formats->get('EUR')->format(5); // 5€
$formats->get('GBP')->format(5); // £ 5,00

Integration to Nette framework

In your neon file, define service for keep formatting and register to latte

services:
	number: h4kuna\Format\Number\Formatters\NumberFormatter(decimalPoint: '.', decimals: 4) # support named parameters by nette
	percent: h4kuna\Format\Number\Formatters\NumberFormatter(decimalPoint: '.', decimals: 2, unit: '%')
	currency.czk: h4kuna\Format\Number\Formatters\NumberFormatter(decimalPoint: ',', decimals: 2, unit: 'Kč')
	currency.eur: h4kuna\Format\Number\Formatters\NumberFormatter(decimalPoint: '.', decimals: 2, unit: '€', mask: '⎵ 1')
	
	currencies:
		implement: h4kuna\Format\Number\FormatsAccessor(
			czk: @currency.czk
			eur: @currency.eur
		)
		
	latte.latteFactory:
		setup:
			- addFilter('number', @number)
			- addFilter('percent', @percent)
			- addFilter('czk', @currency.czk)
			- addFilter('eur', @currency.eur)

Latte template

{=10000|number} // this render "1 000.0000" with &nbps; like white space
{=10000|percent}
{=10000|czk}