Numeral.php is a number formatting library for PHP. It started off as a port of numerals-js
(a number formatting library for JavaScript). This is where Numeral.php gets it's name. The latest iteration of Numeral.php is based on numbro
, a maintained "version" of numerals-js. The API is very similar to numbro
, but there are some things that are different. Most of the documentation here is taken from the numbro.js website
, and adjusted where necessary, so be sure to give them some love.
Here is a quick example:
// +10,000
$formatter->format(1000.23, '+0,0');
// 233.43k
$formatter->format(233434, '0a.00');
Installation
This package can be installed using Composer by issuing this command in the root of your project:
composer require stillat/numeral.php
Getting Started
Working with Numeral.php is fairly straightforward. There are two things you have to do when first getting started. First, we need to create a language manager instance, and then a Numeral
(this class does all the formatting and unformatting) instance. The language manager handles loading culture information that the formatter will use.
Doing this might look like this:
<?php
use Stillat\Numeral\Languages\LanguageManager;
use Stillat\Numeral\Numeral;
// Create the language manager instance.
$languageManager = new LanguageManager;
// Create the Numeral instance.
$formatter = new Numeral;
// Now we need to tell our formatter about the language manager.
$formatter->setLanguageManager($languageManager);
At this point we can use our $formatter
and do all the cool and fun things with it.
Formatting
Numbers can be formatted to look like currency, percentages, times, or even plain old numbers with decimal places, thousands, and abbreviations.
// 1,000
$string = $formatter->format(1000, '0,0');
Numbers
Number | Format | String |
---|---|---|
10000 | '0,0.0000' | 10,000.0000 |
10000.23 | '0,0' | 10,000 |
10000.23 | '+0,0' | +10,000 |
-10000 | '0,0.0' | -10,000.0 |
10000.1234 | '0.000' | 10000.123 |
10000.1234 | '0[.]00000' | 10000.12340 |
-10000 | '(0,0.0000)' | (10,000.0000) |
-0.23 | '.00' | -.23 |
-0.23 | '(.00)' | (.23) |
0.23 | '0.00000' | 0.23000 |
0.23 | '0.0[0000]' | 0.23 |
1230974 | '0.0a' | 1.2m |
1460 | '0 a' | 1 k |
-104000 | '0a' | -104k |
233434 | '0a.00' | 233.43k |
233000 | '0a.00' | 233.00k |
1 | '0o' | 1st |
52 | '0o' | 52nd |
23 | '0o' | 23rd |
100 | '0o' | 100th |
Average
Numeral.php provides an easy mechanism to round up any number with the special formatting character a
. Note that the delimiters are per language.
Number | Format | String |
---|---|---|
123 | '0a' | 123 |
1234 | '0a' | 1k |
12345 | '0a' | 12k |
123456 | '0a' | 123k |
1234567 | '0a' | 1m |
12345678 | '0a' | 12m |
123456789 | '0a' | 123m |
Uppercase Variant: You can supply an uppercase variant of this by using the
A
special formatting character. This is not present innumbro.js
.
In addition to this, when numbers are rounded up, one can specify the precision wanted with a format like 3a
(for 3 numbers only). In this case, 0
is used for "automatic" mode.
Number | Format | String |
---|---|---|
1234567891 | '0a' | 1b |
1234567891 | '1a' | 1b |
1234567891 | '2a' | 1b |
1234567891 | '3a' | 1b |
1234567891 | '4a' | 1235m |
1234567891 | '5a' | 1234.6m |
1234567891 | '6a' | 1234.57m |
1234567891 | '7a' | 1234568k |
1234567891 | '8a' | 1234567.9k |
1234567891 | '9a' | 1234567.89k |
1234567891 | '10a' | 1234567891 |
Currency
Numeral.php supports cultural currency formatting via the function formatCurrency
.
// $1000
$formatter->formatCurrency(1000.234);
Number | Language | String |
---|---|---|
1000.234 | en-US | $0,001 k |
1000.234 | fr-FR | 1 000 € |
1000.234 | ja-JP | ¥1,000 |
1000.234 | ru-RU | 1 000 руб. |
You can provide a more specific format, as long as you do not use the $
character:
// $1000.23
$formatter->formatCurrency(1000.234, '0[.]00');
Number | Language | String |
---|---|---|
1000.234 | en-US | $1000.23 |
1000.234 | fr-FR | 1000,23€ |
1000.234 | ja-JP | ¥1000.23 |
1000.234 | ru-RU | 1000,23руб. |
But if you want to, you can always a provide a format by hand to override the languages defaults:
Number | Format | String |
---|---|---|
1000.234 | '$0,0.00' | $1,000.23 |
1000.2 | '0,0[.]00 $' | 1,000.20 $ |
1001 | '$ 0,0[.]00' | $ 1,001 |
-1000.234 | '($0,0)' | ($1,000) |
-1000.234 | '$0.00' | -$1000.23 |
1230974 | '($ 0.00 a)' | $ 1.23 m |
Bytes
Number | Format | String |
---|---|---|
100 | '0b' | 100B |
2048 | '0 b' | 2 KiB |
7884486213 | '0.0b' | 7.3GiB |
3467479682787 | '0.000 b' | 3.154 TiB |
Percentages
Number | Format | String |
---|---|---|
1 | '0%' | 100% |
0.974878234 | '0.000%' | 97.488% |
-0.43 | '0 %' | -43 % |
0.43 | '(0.000 %)' | 43.000 % |
Time
Number | Format | String |
---|---|---|
25 | '00:00:00' | 0:00:25 |
238 | '00:00:00' | 0:03:58 |
63846 | '00:00:00' | 17:44:06 |
If you want to format time more than that, you should check out the Carbon
library.
Unformat
You can unformat a string using the unformat
function.
// -10000
$number = $formatter->unformat('($10,000.00)');
String | Function | Number |
---|---|---|
'10,000.123' | unformat("10,000.123") |
10000.123 |
'0.12345' | unformat('0.12345') |
0.12345 |
'1.23m' | unformat('1.23m') |
1230000 |
'23rd' | unformat('23rd') |
23 |
'$10,000.00' | unformat('$10,000.00') |
10000 |
'100B' | unformat('100B') |
100 |
'3.154TB' | unformat('3.154TB') |
3154000000000 |
'-76%' | unformat('-76%') |
-0.76 |
'2:23:57' | unformat('2:23:57') |
8637 |
Default Zero
You can set a custom output when formatting numbers with a value of 0
:
$formatter->setZeroFormat('N/A');
// 'N/A'
$number = $formatter->format('0');
Acknowledgements
Numeral.php is based on numbro, which is itself a fork of Adam Draper's project Numerals.js (the name of Numeral.php was influenced by this project). Numbro made many improvements to numerals, so the codebase of Numeral.php is heavily influenced by it (Numbro formats should work without much, if any, modification in Numeral.php).
License
Copyright © 2014 Adam Draper
Copyright © 2015 Företagsplatsen AB
Copyright © 2016 Johnathon Koster
Distributed under the MIT license. If you want to know more, see the LICENSE.txt
file.
The original license for Numbro
can be found in the LICENSE-numbro
The original license file for Numeral.js
can be found in LICENSE-Numeraljs