Skip to content
Edit this page

Number Helper

The Number Helper file contains functions that help you work with numeric data in a locale-aware manner.

Loading this Helper

This helper is loaded using the following code:

<?php

helper('number');

When Things Go Wrong

If PHP's internationalization and localization logic cannot handle a value provided, for the given locale and options, then a BadFunctionCallException() will be thrown.

Available Functions

The following functions are available:

number_to_size($num[, $precision = 1[, $locale = null]])

  • Parameters

    • $num mixed Number of bytes
    • $precision int Floating point precision
    • $locale string|null The locale to use for formatting

  • Returns: Formatted data size string, or false if the provided value is not numeric

  • Return type: string|false

Formats numbers as bytes, based on size, and adds the appropriate suffix. Examples:

<?php

echo number_to_size(456); // Returns 456 Bytes
echo number_to_size(4567); // Returns 4.5 KB
echo number_to_size(45678); // Returns 44.6 KB
echo number_to_size(456789); // Returns 447.8 KB
echo number_to_size(3456789); // Returns 3.3 MB
echo number_to_size(12345678912345); // Returns 1.8 GB
echo number_to_size(123456789123456789); // Returns 11,228.3 TB

An optional second parameter allows you to set the precision of the result:

<?php

echo number_to_size(45678, 2); // Returns 44.61 KB

An optional third parameter allows you to specify the locale that should be used when generating the number, and can affect the formatting. If no locale is specified, the Request will be analyzed and an appropriate locale taken from the headers, or the app-default:

<?php

// Generates 11.2 TB
echo number_to_size(12345678912345, 1, 'en_US');
// Generates 11,2 TB
echo number_to_size(12345678912345, 1, 'fr_FR');

Note

The text generated by this function is found in the following language file: language/<your_lang>/Number.php

number_to_amount($num[, $precision = 0[, $locale = null]])

  • Parameters

    • $num mixed Number to format
    • $precision int Floating point precision
    • $locale string|null The locale to use for formatting

  • Returns: A human-readable version of the string, or false if the provided value is not numeric

  • Return type: string|false

Converts a number into a human-readable version, like 123.4 trillion for numbers up to the quadrillions. Examples:

<?php

echo number_to_amount(123456); // Returns 123 thousand
echo number_to_amount(123456789); // Returns 123 million
echo number_to_amount(1234567890123, 2); // Returns 1.23 trillion
echo number_to_amount('123,456,789,012', 2); // Returns 123.46 billion

An optional second parameter allows you to set the precision of the result:

<?php

echo number_to_amount(45678, 2); // Returns 45.68 thousand

An optional third parameter allows the locale to be specified:

<?php

echo number_to_amount('123,456,789,012', 2, 'de_DE'); // Returns 123,46 billion

number_to_currency($num, $currency[, $locale = null[, $fraction = 0]])

  • Parameters

    • $num float Number to format
    • $currency string The currency type, e.g., USD, EUR, etc.
    • $locale string|null The locale to use for formatting
    • $fraction integer Number of fraction digits after the decimal point

  • Returns: The number as the appropriate currency for the locale

  • Return type: string

Converts a number to common currency formats, like USD, EUR, GBP, etc:

<?php

echo number_to_currency(1234.56, 'USD', 'en_US', 2);  // Returns $1,234.56
echo number_to_currency(1234.56, 'EUR', 'de_DE', 2);  // Returns 1.234,56 €
echo number_to_currency(1234.56, 'GBP', 'en_GB', 2);  // Returns £1,234.56
echo number_to_currency(1234.56, 'YEN', 'ja_JP', 2);  // Returns YEN 1,234.56

If you don't specify a locale, the Request locale is used.

number_to_roman($num)

  • Parameters

    • $num int|string The number to convert

  • Returns: The Roman numeral converted from the given parameter

  • Return type: string|null

Converts a number into a Roman numeral:

<?php

echo number_to_roman(23);    // Returns XXIII
echo number_to_roman(324);   // Returns CCCXXIV
echo number_to_roman(2534);  // Returns MMDXXXIV

This function only handles numbers in the range 1 through 3999. It will return null for any value outside that range.