Introducing the Laravel Number Utility Class
Tags: php, laravel, news, opensource
Published: 2023-11-16 20:26:33

## Introduction

Hello everyone, Caen here! I'm excited to share with you a recent addition I made to the Laravel framework ([PR #48845](https://github.com/laravel/framework/pull/48845)) that I believe will simplify your number formatting needs. I've introduced a new `Number` utility class called that provides several new helpers to format numbers.

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 `Number` Class

### Introduction

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

```php
use Illuminate\Support\Number;
```

### General formatting

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

```php
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.

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

### Percentage formatting

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

```php
Number::toPercentage(25) // 25%
Number::toPercentage((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!

```php
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](https://github.com/laravel/framework/pull/48827)), which [Taylor then suggested](https://github.com/laravel/framework/pull/48827#issuecomment-1781232805) we add as part of a new `Number` class.

```php
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.

```php
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:

```php
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:

```php
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 update and incorporate this utility class into your projects. Happy coding!