Знакомство с утилитарным классом Laravel Number

Всем привет, это Каен! Я рад поделиться недавним дополнением к фреймворку Laravel ([10.x] Add a Number utility class #48845), которое, по моему мнению, упростит ваши потребности в форматировании чисел. Я представил новый утилитарный класс Number, предоставляющий несколько новых хелперов для форматирования чисел, и он должен появиться в следующем релизе Laravel на этой неделе (уже вышел).

Ещё один бонус: хелперы ориентированы на локаль, поэтому вы можете форматировать числа в соответствии с текущей локалью, как глобально, так и для каждого метода!

Предыстория

Во многих приложениях часто возникает необходимость форматировать числа в соответствии с различными требованиями, например, отображать их в виде валюты, процентов или человеко-понятных размеров файлов. В Laravel не было специализированной утилиты для этого, поэтому с помощью сообщества я решил создать её. Я работал над этим классом утилиты некоторое время и очень рад, что он был включён во фреймворк. Давайте посмотрим, что она предлагает.

Класс Laravel Number

Введение

Все методы являются частью класса Illuminate\Support\Number:

use Illuminate\Support\Number;

Общее форматирование чисел

Используя метод format, мы можем отформатировать число в соответствии с текущей локалью.

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

Мы также можем указать произвольную локаль, чтобы отформатировать число в соответствии с правилами этой локали.

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

Форматирование процентов

Метод formatPercentage форматирует число как проценты в соответствии с текущей локалью.

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

Форматирование валют

Вот ещё один забавный метод, используемый для форматирования различных валют с поддержкой локалей. Идеально подходит для ваших интернет-магазинов!

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

Форматирование размера файла

Это метод toFileSize, который, собственно, и является причиной создания этого класса. Сначала я подал PR на добавление хелпера File::bytesToHuman() ([10.x] Add a File::bytesToHuman() helper #48827), который Тейлор предложил добавить как часть нового класса Number.

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

Человеко-читаемое форматирование

Следующий вариант — тоже довольно забавный, для тех случаев, когда вам нужно не точное, а более читабельное число. Он преобразует числа в человеко-читаемую строку.

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

Установка локали

Мы можем установить локаль глобально с помощью метода setLocale, например, в сервис провайдере:

Number::setLocale('sv');

Вы также можете использовать метод withLocale, выполняющий заданный обратный вызов/callback с использованием указанной локали, а затем восстанавливающий исходную локаль:

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

Заключение

Надеюсь, это новое дополнение немного облегчит вам жизнь при работе с форматированием чисел в Laravel. Пожалуйста, проверьте следующий релиз Laravel и включите этот класс в свои проекты. Счастливого кодинга!

Обновление 11/21/2023: Хелперы Number теперь задокументирован в официальной документации по хелперам Laravel.