PHP Humanize

A PHP library to convert machine data into human-readable strings.

Installation

Install from Packagist:

composer require rjds/php-humanize

If you use a private Composer mirror, add your repository configuration first and then run the same require command.

Overview

useDateTimeImmutable;
useRjds\PhpHumanize\Humanizer;
$humanizer = newHumanizer();
$fiveMinutesAgo = newDateTimeImmutable('-5 minutes');
$humanizer->fileSize(5452595); // "5.2 MB"$humanizer->dataRate(1536); // "1.5 KB/s"$humanizer->ordinal(21); // "21st"$humanizer->abbreviate(2300000); // "2.3M"$humanizer->number(1234567.89, 2, Humanizer::LOCALE_NL); // "1.234.567,89"$humanizer->percentage(0.153, 1); // "15.3%"$humanizer->toWords(42); // "forty-two"$humanizer->duration(3661); // "1 hour, 1 minute, 1 second"$humanizer->diffForHumans($fiveMinutesAgo); // "5 minutes ago"$humanizer->readableDate(newDateTimeImmutable('2026-03-30'), Humanizer::LOCALE_NL); // "Maandag 30 maart 2026"$humanizer->pluralize(3, 'child', 'children');// "3 children"$humanizer->joinList(['A', 'B', 'C']); // "A, B, and C"$humanizer->truncate('The quick brown fox jumps over the lazy dog', 20); // "The quick brown fox…"

For detailed usage and all available options, see the GitHub Wiki.

Quick Start

The overview above covers all built-in formatters. For more details on each one, visit the wiki pages for File Size, Numbers, Durations, Date Formatting, and more.

Configure defaults globally

Use HumanizerConfig to centralize locale, precision, conjunction, and truncation defaults across your entire application:

useRjds\PhpHumanize\Humanizer;
useRjds\PhpHumanize\HumanizerConfig;
$config = newHumanizerConfig(
locale: Humanizer::LOCALE_NL,
numberPrecision: 2,
listConjunction: 'or',
truncateSuffix: '...'
);
$humanizer = newHumanizer(config: $config);
echo$humanizer->number(1234.56); // 1.234,56echo$humanizer->percentage(0.125); // 12,50%echo$humanizer->joinList(['A', 'B']); // A or Becho$humanizer->truncate('long text', 5); // lo...

Intl-powered formatting

As of v3, ext-intl (ICU) is a hard dependency. Built-in number, percentage, and date formatters now rely on ICU locale rules instead of internal locale mapping tables.

useRjds\PhpHumanize\Formatter\DateTime\DateFormatter;
useRjds\PhpHumanize\Formatter\Number\NumberFormatter;
useRjds\PhpHumanize\Formatter\Number\PercentageFormatter;
$number = newNumberFormatter(); // ICU locale-aware formatting$percent = newPercentageFormatter(); // ICU locale-aware formatting$date = newDateFormatter(); // ICU locale-aware formatting// Force English-only fallback behavior:$stableNumber = newNumberFormatter(preferIntl: false);
$stablePercent = newPercentageFormatter(preferIntl: false);
$stableDate = newDateFormatter(preferIntl: false);

Extend with custom formatters

useRjds\PhpHumanize\Formatter\FormatterInterface;
useRjds\PhpHumanize\Humanizer;
class MyFormatter implements FormatterInterface {
publicfunctionformat(...$args): string {
return"custom: " . $args[0];
}
publicfunctiongetName(): string {
return'my';
}
}
$humanizer = newHumanizer();
$humanizer->register('my', newMyFormatter());
echo$humanizer->my('hello'); // custom: hello

See Custom Formatters in the wiki for patterns and best practices.

Development

composer install
php vendor/bin/grumphp run

Run mutation testing:

php vendor/bin/infection --threads=4

Contributing

Contributions are welcome. See CONTRIBUTING.md for contribution guidelines, local quality checks, and pull request workflow.

Migrations

See the migration guide: MIGRATION.md.

License

This project is released under the MIT License. See LICENSE for details and CHANGELOG.md for release history.