Number.php
TLDR
This file contains the Number class with various methods for formatting numbers. The class provides methods for formatting numbers, spell out numbers, converting numbers to ordinal form, converting numbers to percentage and currency, and converting numbers to file size. It also includes methods for abbreviating and summarizing numbers for human readability. The class ensures that the intl PHP extension is installed before performing any formatting operations.
Methods
format
This method formats the given number according to the current locale. It accepts the number to be formatted as the first parameter and optional parameters for precision, maximum precision, and locale. It returns the formatted number as a string or false if formatting fails.
spell
This method spells out the given number in the specified locale. It accepts the number to be spelled out as the first parameter and an optional locale. It returns the spelled out number as a string.
ordinal
This method converts the given number to its ordinal form in the specified locale. It accepts the number to be converted as the first parameter and an optional locale. It returns the ordinal form of the number as a string.
percentage
This method converts the given number to its percentage equivalent in the specified locale. It accepts the number to be converted, precision, maximum precision, and an optional locale. It returns the percentage value as a string or false if formatting fails.
currency
This method converts the given number to its currency equivalent in the specified locale. It accepts the number to be converted, the currency code, and an optional locale. It returns the currency value as a string or false if formatting fails.
fileSize
This method converts the given number to its file size equivalent. It accepts the number in bytes, precision, and optional maximum precision. It returns the formatted file size as a string.
abbreviate
This method converts the given number to its human-readable equivalent using abbreviated suffixes. It accepts the number to be converted, precision, and optional maximum precision. It returns the abbreviated number as a string.
forHumans
This method converts the given number to its human-readable equivalent. It accepts the number to be converted, precision, optional maximum precision, and a flag to indicate whether to abbreviate the number. It returns the human-readable number as a string.
withLocale
This method executes the given callback using the specified locale. It accepts the locale and a callback function. It returns the result of the callback function.
useLocale
This method sets the default locale to be used for number formatting. It accepts the locale as a parameter.
ensureIntlExtensionIsInstalled
This method ensures that the "intl" PHP extension is installed. If the extension is not loaded, it throws a RuntimeException indicating that the extension is required to use the formatting methods.
Note: The Number class also includes a trait Macroable, which is used to add additional methods dynamically to the class at runtime. However, the specific methods added by this trait are not defined in this file.
Classes
None
<?php
namespace Illuminate\Support;
use Illuminate\Support\Traits\Macroable;
use NumberFormatter;
use RuntimeException;
class Number
{
use Macroable;
/**
* The current default locale.
*
* @var string
*/
protected static $locale = 'en';
/**
* Format the given number according to the current locale.
*
* @param int|float $number
* @param int|null $precision
* @param int|null $maxPrecision
* @param string|null $locale
* @return string|false
*/
public static function format(int|float $number, ?int $precision = null, ?int $maxPrecision = null, ?string $locale = null)
{
static::ensureIntlExtensionIsInstalled();
$formatter = new NumberFormatter($locale ?? static::$locale, NumberFormatter::DECIMAL);
if (! is_null($maxPrecision)) {
$formatter->setAttribute(NumberFormatter::MAX_FRACTION_DIGITS, $maxPrecision);
} elseif (! is_null($precision)) {
$formatter->setAttribute(NumberFormatter::FRACTION_DIGITS, $precision);
}
return $formatter->format($number);
}
/**
* Spell out the given number in the given locale.
*
* @param int|float $number
* @param string|null $locale
* @return string
*/
public static function spell(int|float $number, ?string $locale = null)
{
static::ensureIntlExtensionIsInstalled();
$formatter = new NumberFormatter($locale ?? static::$locale, NumberFormatter::SPELLOUT);
return $formatter->format($number);
}
/**
* Convert the given number to ordinal form.
*
* @param int|float $number
* @param string|null $locale
* @return string
*/
public static function ordinal(int|float $number, ?string $locale = null)
{
static::ensureIntlExtensionIsInstalled();
$formatter = new NumberFormatter($locale ?? static::$locale, NumberFormatter::ORDINAL);
return $formatter->format($number);
}
/**
* Convert the given number to its percentage equivalent.
*
* @param int|float $number
* @param int $precision
* @param int|null $maxPrecision
* @param string|null $locale
* @return string|false
*/
public static function percentage(int|float $number, int $precision = 0, ?int $maxPrecision = null, ?string $locale = null)
{
static::ensureIntlExtensionIsInstalled();
$formatter = new NumberFormatter($locale ?? static::$locale, NumberFormatter::PERCENT);
if (! is_null($maxPrecision)) {
$formatter->setAttribute(NumberFormatter::MAX_FRACTION_DIGITS, $maxPrecision);
} else {
$formatter->setAttribute(NumberFormatter::FRACTION_DIGITS, $precision);
}
return $formatter->format($number / 100);
}
/**
* Convert the given number to its currency equivalent.
*
* @param int|float $number
* @param string $in
* @param string|null $locale
* @return string|false
*/
public static function currency(int|float $number, string $in = 'USD', ?string $locale = null)
{
static::ensureIntlExtensionIsInstalled();
$formatter = new NumberFormatter($locale ?? static::$locale, NumberFormatter::CURRENCY);
return $formatter->formatCurrency($number, $in);
}
/**
* Convert the given number to its file size equivalent.
*
* @param int|float $bytes
* @param int $precision
* @param int|null $maxPrecision
* @return string
*/
public static function fileSize(int|float $bytes, int $precision = 0, ?int $maxPrecision = null)
{
$units = ['B', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'];
for ($i = 0; ($bytes / 1024) > 0.9 && ($i < count($units) - 1); $i++) {
$bytes /= 1024;
}
return sprintf('%s %s', static::format($bytes, $precision, $maxPrecision), $units[$i]);
}
/**
* Convert the number to its human readable equivalent.
*
* @param int $number
* @param int $precision
* @param int|null $maxPrecision
* @return string
*/
public static function abbreviate(int|float $number, int $precision = 0, ?int $maxPrecision = null)
{
return static::forHumans($number, $precision, $maxPrecision, abbreviate: true);
}
/**
* Convert the number to its human readable equivalent.
*
* @param int $number
* @param int $precision
* @param int|null $maxPrecision
* @return string
*/
public static function forHumans(int|float $number, int $precision = 0, ?int $maxPrecision = null, bool $abbreviate = false)
{
return static::summarize($number, $precision, $maxPrecision, $abbreviate ? [
3 => 'K',
6 => 'M',
9 => 'B',
12 => 'T',
15 => 'Q',
] : [
3 => ' thousand',
6 => ' million',
9 => ' billion',
12 => ' trillion',
15 => ' quadrillion',
]);
}
/**
* Convert the number to its human readable equivalent.
*
* @param int $number
* @param int $precision
* @param int|null $maxPrecision
* @param array $units
* @return string
*/
protected static function summarize(int|float $number, int $precision = 0, ?int $maxPrecision = null, array $units = [])
{
if (empty($units)) {
$units = [
3 => 'K',
6 => 'M',
9 => 'B',
12 => 'T',
15 => 'Q',
];
}
switch (true) {
case floatval($number) === 0.0:
return $precision > 0 ? static::format(0, $precision, $maxPrecision) : '0';
case $number < 0:
return sprintf('-%s', static::summarize(abs($number), $precision, $maxPrecision, $units));
case $number >= 1e15:
return sprintf('%s'.end($units), static::summarize($number / 1e15, $precision, $maxPrecision, $units));
}
$numberExponent = floor(log10($number));
$displayExponent = $numberExponent - ($numberExponent % 3);
$number /= pow(10, $displayExponent);
return trim(sprintf('%s%s', static::format($number, $precision, $maxPrecision), $units[$displayExponent] ?? ''));
}
/**
* Execute the given callback using the given locale.
*
* @param string $locale
* @param callable $callback
* @return mixed
*/
public static function withLocale(string $locale, callable $callback)
{
$previousLocale = static::$locale;
static::useLocale($locale);
return tap($callback(), fn () => static::useLocale($previousLocale));
}
/**
* Set the default locale.
*
* @param string $locale
* @return void
*/
public static function useLocale(string $locale)
{
static::$locale = $locale;
}
/**
* Ensure the "intl" PHP extension is installed.
*
* @return void
*/
protected static function ensureIntlExtensionIsInstalled()
{
if (! extension_loaded('intl')) {
throw new RuntimeException('The "intl" PHP extension is required to use this method.');
}
}
}