README

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

use DateTimeImmutable;
use Rjds\PhpHumanize\Humanizer;

$humanizer = new Humanizer();
$fiveMinutesAgo = new DateTimeImmutable('-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(new DateTimeImmutable('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:

use Rjds\PhpHumanize\Humanizer;
use Rjds\PhpHumanize\HumanizerConfig;

$config = new HumanizerConfig(
    locale: Humanizer::LOCALE_NL,
    numberPrecision: 2,
    listConjunction: 'or',
    truncateSuffix: '...'
);

$humanizer = new Humanizer(config: $config);

echo $humanizer->number(1234.56);           // 1.234,56
echo $humanizer->percentage(0.125);         // 12,50%
echo $humanizer->joinList(['A', 'B']);      // A or B
echo $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.

use Rjds\PhpHumanize\Formatter\DateTime\DateFormatter;
use Rjds\PhpHumanize\Formatter\Number\NumberFormatter;
use Rjds\PhpHumanize\Formatter\Number\PercentageFormatter;

$number = new NumberFormatter();        // ICU locale-aware formatting
$percent = new PercentageFormatter();   // ICU locale-aware formatting
$date = new DateFormatter();            // ICU locale-aware formatting

// Force English-only fallback behavior:
$stableNumber = new NumberFormatter(preferIntl: false);
$stablePercent = new PercentageFormatter(preferIntl: false);
$stableDate = new DateFormatter(preferIntl: false);

Extend with custom formatters

use Rjds\PhpHumanize\Formatter\FormatterInterface;
use Rjds\PhpHumanize\Humanizer;

class MyFormatter implements FormatterInterface {
    public function format(...$args): string {
        return "custom: " . $args[0];
    }

    public function getName(): string {
        return 'my';
    }
}

$humanizer = new Humanizer();
$humanizer->register('my', new MyFormatter());
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.