README

Turn plain numbers, dates, and byte counts into friendly, human-oriented strings.
rhdevelopment/numbers-for-humans wraps a handful of common formatting tasks into a single, lightweight helper class.

Installation

composer require rhdevelopment/numbers-for-humans

The package requires PHP ^7.4 || ^8.0, the intl extension, and nesbot/carbon.

Quick start

<?php

require __DIR__ . '/vendor/autoload.php';

use RHDevelopment\Readable\Readable;

echo Readable::getHumanNumber(1524999); // 1.5M
echo Readable::getDateTime('2020-08-26 17:38:23'); // Wednesday, August 26, 2020 05:38 PM
echo Readable::getSize(1500); // 1.5 KB

All methods are static, so you can call them directly from anywhere in your project.

API overview

Detailed examples

Readable::getNumber(1234567890);                // "1,234,567,890"
Readable::getNumber(-1234567, ' ');             // "-1 234 567"

Readable::getHumanNumber(1524999);              // "1.5M"
Readable::getHumanNumber(1524999, true, 2);     // "1.52M"
Readable::getHumanNumber(-3400000, false);      // "-3M"

Readable::readableString(12345);                // "twelve thousand three hundred forty-five"
Readable::readableString(-42);                  // "minus forty-two"

Readable::getDecimal(1234.567, 2);              // "1,234.57"
Readable::getDecInt(200.0);                     // "200"

Readable::getDate('2020-08-26 17:38:23');       // "26 August 2020"
Readable::getTime('2020-08-26 17:38:23', true); // "17:38:23"
Readable::getDateTime('2020-08-26 17:38:23');   // "Wednesday, August 26, 2020 05:38 PM"

$old = '2020-01-22 05:58:00';
$new = '2020-01-23 05:58:00';
Readable::getDiffDateTime($old, $new);          // "1 day before"
Readable::getTimeLength(3661, ', ', true);      // "1h, 1m, 1s"
Readable::getDateTimeLength($new, $old);        // "1 day after"

Readable::getSize(1500);                        // "1.5 KB"
Readable::getSize(1024 ** 2, false);            // "1 MiB"

CLI demo

Install the package (or run composer install inside this repository) and execute:

vendor/bin/numbers-for-humans

You’ll see every helper in action with sample inputs and outputs. The CLI script automatically locates the Composer autoloader whether you’re working from this repository or using the package as a dependency.

Web demo

There’s also a small showcase page at examples/index.php.

composer install
php -S 127.0.0.1:8000 -t examples

Then browse to http://127.0.0.1:8000 to experiment interactively.

Testing

Run the full PHPUnit suite:

composer install
composer test

The test suite covers every helper, including edge cases for negative numbers, timezone conversions, and binary versus decimal file size calculations.

Releasing on Packagist

1. Ensure the repository is public on GitHub.
2. Tag a semantic version: git tag v1.0.0 && git push --tags.
3. Submit the repository URL (https://github.com/rhdevelopment/NumbersForHumans) to Packagist.org.
4. Configure the GitHub service hook or Packagist auto-update to keep releases in sync.

Once published, others can install the package with composer require rhdevelopment/numbers-for-humans.

License

Licensed under the MIT License.