Introducing the Laravel Number Utility Class

Hello everyone, Caen here! I'm excited to share with you a recent addition I made to the Laravel framework (PR #48845) that I believe will simplify your number formatting needs. I've introduced a new Number utility class that provides several new helpers to format numbers, and it should be available in the next Laravel release this week.

As another bonus: the helpers are locale-aware, so you can format numbers according to the current locale, either globally, or on a per-method basis!

Background

In many applications, there's often a need to format numbers according to different requirements, such as displaying them as currency, percentages, or human-readable file sizes. Laravel didn't have a dedicated utility for this, so with the help of the community, I decided to create one. I've been working on this utility class for a a little while now, and am really excited that it was merged into the framework. Let's take a look at what it offers.

The Laravel Number Class

Introduction

All methods are part of the Illuminate\Support\Number class:

use Illuminate\Support\Number;

General number formatting

Using the format method, we can format a number according to the current locale.

Number::format(25) // 25
Number::format(100000) // 100,000
Number::format(123456789) // 123,456,789

We can also specify a custom locale to format the number according to that locale's rules.

Number::format(123456789, locale: 'en') // 123,456,789
Number::format(123456789, locale: 'de') // 123.456.789
Number::format(123456789, locale: 'sv') // 123 456 789

Percentage formatting

The formatPercentage method formats a number as a percentage according to the current locale.

Number::percentage(25) // 25%
Number::percentage((1/3) * 100, precision: 2) // 33.33%

Currency formatting

Here's another fun method used to format various currencies with locale support. Perfect for your webshops!

Number::toCurrency(10) // $10.00
Number::toCurrency(25, currency: 'EUR') // €25.00
Number::toCurrency(5.49, currency: 'EUR', locale: 'de') // 5.49 €

File size formatting

Here is the toFileSize method which actually is the whole reason behind this utility class. I first submitted a PR to add a File::bytesToHuman() helper (PR #48827), which Taylor then suggested we add as part of a new Number class.

Number::toFileSize(1024); // 1 KB
Number::toFileSize(1600, precision: 2); // 1.56 KB
Number::toFileSize(1024 * 1024 * 1024 * 5); // 5 GB

Human readable formatting

Next up is also a quite fun one for when you want something that's more readable than precise. It converts numbers to a human-readable string.

Number::forHumans(1000) // 1 thousand
Number::forHumans(12345) // 12 thousand
Number::forHumans(12345, precision: 3) // 12.345 thousand

Setting the locale

We can set the locale globally using the setLocale method, for example in a service provider:

Number::setLocale('sv');

You can also use the withLocale method which executes the given callback using the specified locale and then restores the original locale:

Number::withLocale('sv', function () {
    return Number::format(123456789);
});

Conclusion

I hope this new addition makes your life a bit easier when dealing with number formatting in Laravel. Please free to check out the next Laravel release and incorporate this utility class into your projects. Happy coding!

Update 11/21/2023: The Numbers helper is now documented in the official Laravel helpers documentation.