README

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

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.

Uppercase Variant: You can supply an uppercase variant of this by using the A special formatting character. This is not present in numbro.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.

Currency

Numeral.php supports cultural currency formatting via the function formatCurrency.

// $1000
$formatter->formatCurrency(1000.234);

You can provide a more specific format, as long as you do not use the $ character:

// $1000.23
$formatter->formatCurrency(1000.234, '0[.]00');

But if you want to, you can always a provide a format by hand to override the languages defaults:

Bytes

Percentages

Time

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)');

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

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

stillat / numeral.php

Maintainers

Details