Readable

Human-friendly formatting for plain PHP. Readable turns raw values into text people can read at a glance: 1250000 becomes 1.3M, 1536 bytes become 1.5 KiB, 3661 seconds become 1 hour 1 minute 1 second. Each kind of value has its own small class of static methods, the output is the same on every machine, and Intl locales are there when you need them.

Installation

Install the package with Composer. There is nothing to register, publish or configure.

Requirements

• PHP 8.3.x (each 8.x release line targets the matching PHP version)
• ext-mbstring
• ext-intl (optional): only needed when you pass a $locale

Composer Installation

composer require pharaonic/php-readable

Composer autoloads the Pharaonic\Readable namespace. The package ships no global functions.

Basic Usage

Import the class for the kind of value you have and call a static method. Every formatter returns a string.

1use Pharaonic\Readable\{Arr, Bytes, Duration, Money, Number, Str};
2 
3Number::format(1234567.891, 2);   // "1,234,567.89"
4Number::compact(1250000);         // "1.3M"
5Bytes::format(1500);              // "1.5 KB"
6Money::format(1234.5, 'USD');     // "USD 1,234.50"
7Duration::format(3661);           // "1 hour 1 minute 1 second"
8Str::initials('Moamen Eltouny');  // "ME"
9Arr::isList([10, 20, 30]);        // true

Named arguments

Optional arguments come after the value, so named arguments keep calls readable when you skip some of them:

1Number::format(70.50, 2, trimZeros: true);  // "70.5"
2Bytes::format(1536, binary: true);          // "1.5 KiB"
3Duration::format(90061, parts: 2);          // "1 day 1 hour"
4Money::format(1234.5, 'USD', decimals: 0);  // "USD 1,235"

Rules shared by every formatter

• Rounding is half away from zero, like number_format(): Number::format(2.5) is "3" and Number::format(-2.5) is "-3".
• No negative zero. A negative value that rounds to zero prints as zero: Number::format(-0.001, 2) is "0.00".
• Invalid input throws InvalidArgumentException: INF, NAN, negative decimals, a malformed currency code, an unparsable size, or a date string PHP cannot read.
• No state. There is no global configuration; everything a call needs is in its arguments.

Locales & Intl

Number::format(), percentage(), ordinal(), spell(), Bytes::format() and Money::format() accept an optional ?string $locale as their last argument.

Without a locale (default)

Readable uses its own English formatter: , for thousands, . for decimals, English suffixes and words. The output is identical on every machine, with or without the intl extension.

1Number::format(1234567.891, 2);  // "1,234,567.89"
2Number::ordinal(22);             // "22nd"
3Number::spell(7721);             // "seven thousand seven hundred twenty-one"

With a locale

Readable formats through Intl's NumberFormatter, still rounding half away from zero:

1Number::format(1234567.891, 2, locale: 'de_DE');   // "1.234.567,89"
2Number::percentage(0.756, 1, 'de_DE');             // "75,6 %"
3Number::ordinal(21, 'fr');                         // "21e"
4Number::spell(21, 'fr');                           // "vingt-et-un"
5Money::format(1234.5, 'USD', locale: 'en_US');     // "$1,234.50"
6Bytes::format(1500, locale: 'de_DE');              // "1,5 KB"

For Arabic locales, Number::spell() attaches the conjunction "و" to the following word: Number::spell(21, 'ar') returns "واحد وعشرون".

Number::compact(), Money::compact(), Duration and Str have no locale argument: their output is always English.

Numbers

Pharaonic\Readable\Number formats integers and floats.

Grouped numbers

Number::format() groups thousands and fixes the number of decimals (0 by default):

1Number::format(1234567);           // "1,234,567"
2Number::format(60708.547, 2);      // "60,708.55"
3Number::format(70, 2);             // "70.00"
4Number::format(-1234567);          // "-1,234,567"
5Number::format(PHP_INT_MAX);       // "9,223,372,036,854,775,807"

With trimZeros: true, trailing fraction zeros are dropped:

1Number::format(70.50, 2, trimZeros: true);  // "70.5"
2Number::format(70.00, 2, trimZeros: true);  // "70"
3Number::format(70.07, 2, trimZeros: true);  // "70.07"

Compact numbers

Number::compact() shortens a number with a K, M, B or T suffix, keeping at most $decimals fraction digits (1 by default) and dropping trailing zeros:

1Number::compact(999);         // "999"
2Number::compact(77700);       // "77.7K"
3Number::compact(77700, 0);    // "78K"
4Number::compact(77370, 2);    // "77.37K"
5Number::compact(1000000);     // "1M"
6Number::compact(3400000000);  // "3.4B"
7Number::compact(-1500);       // "-1.5K"

When rounding reaches the next unit, the next unit is used: Number::compact(999950) is "1M", not "1,000K". Values past 999 trillion keep the T suffix: Number::compact(1.5e15) is "1,500T".

Percentages

Number::percentage() takes a ratio, where 1 is 100%:

1Number::percentage(0.75);        // "75%"
2Number::percentage(1);           // "100%"
3Number::percentage(0.1234, 1);   // "12.3%"
4Number::percentage(-0.1);        // "-10%"

Ordinals

1Number::ordinal(1);     // "1st"
2Number::ordinal(22);    // "22nd"
3Number::ordinal(113);   // "113th"
4Number::ordinal(1001);  // "1,001st"
5Number::ordinal(-11);   // "-11th"

Numbers in words

Number::spell() follows ICU's English rules: no "and", hyphenated tens, and fraction digits read one by one. It covers every int and floats up to the decillions.

1Number::spell(21);       // "twenty-one"
2Number::spell(101);      // "one hundred one"
3Number::spell(7721);     // "seven thousand seven hundred twenty-one"
4Number::spell(-5);       // "minus five"
5Number::spell(3.14);     // "three point one four"
6Number::spell(1000001);  // "one million one"

Floats are read from their shortest exact representation, so Number::spell(0.1) is "zero point one".

Byte Sizes

Pharaonic\Readable\Bytes formats and parses byte counts.

Units

Two conventions, never mixed:

Formatting

Bytes::format() keeps at most $decimals fraction digits (2 by default) and drops trailing zeros:

1Bytes::format(0);                    // "0 B"
2Bytes::format(1000);                 // "1 KB"
3Bytes::format(1024);                 // "1.02 KB"
4Bytes::format(1500);                 // "1.5 KB"
5Bytes::format(1536, binary: true);   // "1.5 KiB"
6Bytes::format(1073741824, binary: true); // "1 GiB"
7Bytes::format(1234, 1);              // "1.2 KB"
8Bytes::format(-2048, binary: true);  // "-2 KiB"

Rounding can move a value to the next unit: Bytes::format(999999) is "1 MB", not "1000 KB".

Parsing

Bytes::parse() turns a readable size back into an int. Units are case-insensitive, KB is decimal and KiB is binary, the same as format():

1Bytes::parse('512');        // 512
2Bytes::parse('512 bytes');  // 512
3Bytes::parse('10 MB');      // 10000000
4Bytes::parse('10mb');       // 10000000
5Bytes::parse('1.5 KiB');    // 1536
6Bytes::parse('2 GiB');      // 2147483648

Whole numbers are multiplied exactly; fractional bytes are rounded half away from zero.

Money

Pharaonic\Readable\Money formats amounts for display. It does no arithmetic and no exchange rates.

Formatting

Without a locale, the ISO 4217 code comes first and the currency's minor units decide the decimals:

1Money::format(100, 'USD');      // "USD 100.00"
2Money::format(1234.5, 'USD');   // "USD 1,234.50"
3Money::format(1234.5, 'JPY');   // "JPY 1,235"
4Money::format(1.5, 'KWD');      // "KWD 1.500"
5Money::format(-20, 'EGP');      // "-EGP 20.00"
6Money::format(1, 'usd');        // "USD 1.00"

Override the decimals with $decimals:

1Money::format(1234.5, 'USD', decimals: 0);  // "USD 1,235"
2Money::format(1234.5, 'JPY', decimals: 2);  // "JPY 1,234.50"

With a locale

Intl picks the symbol, its position and the separators:

1Money::format(1234.5, 'USD', locale: 'en_US');   // "$1,234.50"
2Money::format(-1234.5, 'USD', locale: 'en_US');  // "-$1,234.50"
3Money::format(1234.5, 'JPY', locale: 'en_US');   // "¥1,235"
4Money::format(1234.5, 'EUR', locale: 'de_DE');   // "1.234,50 €"

Compact amounts

1Money::compact(1500000, 'USD');  // "USD 1.5M"
2Money::compact(-2500, 'EUR');    // "-EUR 2.5K"
3Money::compact(999, 'EGP');      // "EGP 999"

Minor units

Money::fractionDigits() returns the ISO 4217 number of decimals for a currency:

1Money::fractionDigits('USD');  // 2
2Money::fractionDigits('JPY');  // 0
3Money::fractionDigits('KWD');  // 3
4Money::fractionDigits('CLF');  // 4

Currencies with 0 decimals: BIF, CLP, DJF, GNF, ISK, JPY, KMF, KRW, PYG, RWF, UGX, UYI, VND, VUV, XAF, XOF, XPF. With 3: BHD, IQD, JOD, KWD, LYD, OMR, TND. With 4: CLF, UYW. Every other code uses 2.

Durations

Pharaonic\Readable\Duration writes lengths of time in English.

From seconds

1Duration::format(0);         // "0 seconds"
2Duration::format(59);        // "59 seconds"
3Duration::format(3661);      // "1 hour 1 minute 1 second"
4Duration::format(187200);    // "2 days 4 hours"
5Duration::format(604800);    // "1 week"
6Duration::format(31536000);  // "1 year"
7Duration::format(-3661);     // "1 hour 1 minute 1 second"

format() uses fixed-length units only: a year is 365 days, then weeks, days, hours, minutes and seconds. It never uses months, because a month has no fixed length: 29 days is "4 weeks 1 day". The sign is ignored.

Between two moments

Duration::between() uses the real calendar through PHP's DateTimeInterface::diff(), so it does report months. It accepts DateTimeInterface objects, Unix timestamps and any string DateTimeImmutable understands, in any order:

1Duration::between('2024-01-01', '2025-03-15');  // "1 year 2 months 2 weeks"
2Duration::between('2024-02-01', '2024-03-01');  // "1 month"
3Duration::between(0, 3661);                     // "1 hour 1 minute 1 second"
4Duration::between($order->created_at, new DateTimeImmutable());

Moments in different time zones are compared as instants.

Options

Both methods take the same three options after their main arguments:

1Duration::format(90061, parts: 2);         // "1 day 1 hour"
2Duration::format(7199, parts: 2);          // "1 hour 59 minutes"
3Duration::format(3661, short: true);       // "1h 1m 1s"
4Duration::format(3661, separator: ', ');   // "1 hour, 1 minute, 1 second"
5Duration::between('2024-01-01', '2025-03-15', parts: 2, short: true); // "1y 2mo"

parts must be 1 or greater; 0 throws InvalidArgumentException.

Strings

Pharaonic\Readable\Str has one helper, for the initials you show on avatars and badges.

Initials

Str::initials() takes the first letter or digit of each whitespace-separated word and uppercases it:

1Str::initials('Moamen Eltouny');   // "ME"
2Str::initials('moamen eltouny');   // "ME"
3Str::initials('Raggi');            // "R"
4Str::initials('élise ößler');      // "ÉÖ"
5Str::initials('3M Company');       // "3C"

With more words than $limit (2 by default), it keeps the first $limit - 1 words and the last one:

1Str::initials('John Ronald Reuel Tolkien');     // "JT"
2Str::initials('John Ronald Reuel Tolkien', 3);  // "JRT"
3Str::initials('John Ronald Reuel Tolkien', 1);  // "J"

Leading punctuation is skipped ('(Ada) "Lovelace"' → "AL"), words with no letters or digits are ignored ('Ada & Lovelace' → "AL"), a hyphenated word counts as one word, and combining marks stay with their letter. An empty or whitespace-only name returns "".

Arrays

Pharaonic\Readable\Arr answers three common questions about an array's shape.

Only nulls?

Arr::isNull() is true when every value is null. The check is strict: false, 0 and '' are not null.

1Arr::isNull([null, null]);  // true
2Arr::isNull([null, 0]);     // false
3Arr::isNull([false]);       // false
4Arr::isNull([]);            // true

An empty array has no non-null value, so it returns true.

Nested arrays?

Arr::isMultidimensional() is true when at least one value is an array, including an empty one:

1Arr::isMultidimensional([1, 2]);              // false
2Arr::isMultidimensional([1, [2]]);            // true
3Arr::isMultidimensional(['x' => ['y' => 1]]); // true
4Arr::isMultidimensional(['a' => []]);         // true
5Arr::isMultidimensional([]);                  // false

A list?

Arr::isList() is true when the keys are 0, 1, 2, … in order:

1Arr::isList([10, 20, 30]);           // true
2Arr::isList([]);                     // true
3Arr::isList([1 => 'a']);             // false
4Arr::isList([1 => 'b', 0 => 'a']);   // false
5Arr::isList(['a' => 1]);             // false

API Reference

Every method is public static. Methods marked throws raise InvalidArgumentException for invalid input; any method with a $locale raises Pharaonic\Readable\Exceptions\MissingIntlExtension when a locale is passed without ext-intl.

Pharaonic\Readable\Number

Pharaonic\Readable\Bytes

Pharaonic\Readable\Money

Pharaonic\Readable\Duration

Pharaonic\Readable\Str

Pharaonic\Readable\Arr

Exceptions

Examples

1. A file list

Show each upload's size and age next to its name.

 1use Pharaonic\Readable\{Bytes, Duration};
 2 
 3function fileRow(string $path): string
 4{
 5    $size = Bytes::format(filesize($path), 1, binary: true);
 6    $age = Duration::between(filemtime($path), time(), parts: 1);
 7 
 8    return sprintf('%s · %s · %s ago', basename($path), $size, $age);
 9}
10 
11// "report.pdf · 2.4 MiB · 3 days ago"

2. Dashboard stat cards

Big numbers stay short and percentages stay honest about rounding.

1use Pharaonic\Readable\Number;
2 
3$cards = [
4    'Visitors'   => Number::compact(1284503),           // "1.3M"
5    'Signups'    => Number::format(48210),              // "48,210"
6    'Conversion' => Number::percentage(48210 / 1284503, 2), // "3.75%"
7    'Rank'       => Number::ordinal(3),                 // "3rd"
8];

3. Invoices in the customer's locale

The same amount, formatted for each customer, with a deterministic fallback when you don't know their locale.

 1use Pharaonic\Readable\Money;
 2 
 3final class InvoiceLine
 4{
 5    public function __construct(
 6        public float $amount,
 7        public string $currency,
 8    ) {}
 9 
10    public function total(?string $locale = null): string
11    {
12        return Money::format($this->amount, $this->currency, locale: $locale);
13    }
14}

1$line = new InvoiceLine(1234.5, 'EUR');
2 
3$line->total();          // "EUR 1,234.50"
4$line->total('de_DE');   // "1.234,50 €"
5$line->total('en_US');   // "€1,234.50"
6 
7(new InvoiceLine(1234.5, 'JPY'))->total(); // "JPY 1,235"

4. Avatar placeholders

Users without a photo get their initials.

1use Pharaonic\Readable\Str;
2 
3function avatarLabel(string $displayName): string
4{
5    return Str::initials($displayName) ?: '?';
6}
7 
8avatarLabel('Moamen Eltouny');  // "ME"
9avatarLabel('   ');             // "?"

5. Upload limits from configuration

Keep limits human-readable in configuration, parse them once, and show them back to the user.

 1use Pharaonic\Readable\Bytes;
 2 
 3$limit = Bytes::parse(getenv('UPLOAD_LIMIT') ?: '25 MB');   // 25000000
 4 
 5if ($file['size'] > $limit) {
 6    throw new RuntimeException(sprintf(
 7        'The file is %s; the limit is %s.',
 8        Bytes::format($file['size']),   // "31.46 MB"
 9        Bytes::format($limit),          // "25 MB"
10    ));
11}

Troubleshooting

MissingIntlExtension is thrown

You passed a $locale but the intl extension isn't loaded. Install and enable ext-intl, or drop the locale argument to use the built-in English formatter. Check with php -m | grep intl.

A string comparison with Intl output fails

Intl puts a no-break space (U+00A0) or a narrow no-break space (U+202F) in some formats, such as "1.234,50 €" or "75,6 %". Compare against the same characters, or replace them with a normal space before comparing. The exact space can change between ICU versions.

Bytes::format(1024) returns "1.02 KB"

KB is 1000 bytes. For 1024-based units pass binary: true: Bytes::format(1024, binary: true) returns "1 KiB".

Number::percentage(75) returns "7,500%"

percentage() expects a ratio where 1 is 100%. Pass 0.75, or divide your percent value by 100.

Duration::format() never shows months

Months have no fixed length, so a bare number of seconds can't be split into them correctly. Use Duration::between() with two dates when you need calendar months.

Bytes::parse() throws for "10K" or "10 Mbit"

A unit prefix needs a B (10 KB, 10 KiB), and bits aren't bytes. Parsing also rejects thousands separators, exponents and sizes that don't fit in an int.

Money::format() throws for "$" or "dollars"

The currency must be a three-letter ISO 4217 code such as USD. Map symbols or names to codes before formatting.

Duration::between() throws for a date string

The string must be something new DateTimeImmutable($string) can read. Pass a DateTimeInterface or a Unix timestamp when your input uses another format.