README

Type-safe units, quantities & dimensional analysis for PHP

A lightweight, immutable, type-safe PHP library for working with quantities, units, and dimensional analysis. Define units, convert across compatible ones, and do arithmetic that refuses to add meters to seconds.

use KhaledAlam\Unit\Quantity;

echo Quantity::of(2, 'm')->add(Quantity::of(100, 'cm'))->to('m'); // "3 m"
echo Quantity::of(100, '°C')->to('°F')->format(1);                // "212.0 °F"
echo Quantity::of(4, 'm')->multiply(Quantity::of(3, 'm'));        // "12 m²"

No setup, no registration — common units are ready the moment you install.

▶️ Try the live demo — an interactive converter running in your browser.

Why Unit?

	Unit	Hand-rolled `* factor`	Raw floats
Blocks nonsensical math (`m + s`)	✅	❌	❌
Auto-converts compatible units	✅	❌	❌
Affine temperature scales (°C/°F/K)	✅	⚠️ easy to get wrong	❌
Derived units (`m/s`, `m²`)	✅	❌	❌
Immutable value objects	✅	—	❌
Zero dependencies	✅	✅	✅

If you've ever shipped a bug because someone stored centimeters in a "meters" column, this library is for you.

Installation

composer require khaledalam/unit

Requires PHP 8.2+.

Quick start

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

use KhaledAlam\Unit\Quantity;

// Common units are auto-registered — just use them.
$length1 = Quantity::of(2.0, 'm');
$length2 = Quantity::of(100.0, 'cm');

$sum = $length1->add($length2); // auto-converts cm -> m
echo $sum->to('m');             // "3 m"

Features

✅ Immutable value objects
✅ Dimensionally-aware arithmetic (add, subtract, multiply, divide)
✅ Automatic conversion between compatible units (e.g. cm → m)
✅ Correct affine temperature conversion (°C ↔ °F ↔ K)
✅ Derived/compound units rendered as m/s, m², m·s
✅ Scalar math (times, dividedBy, pow, sqrt, abs, negate)
✅ Named dimensions (dimensionName() → "velocity")
✅ Comparisons (equals, isGreaterThan, isLessThan)
✅ JsonSerializable output, Laravel cast & Doctrine type
✅ Enum-powered unit naming and a custom unit registry
✅ Zero runtime dependencies

Usage

Conversion

echo Quantity::of(2, 'm')->to('cm');   // "200 cm"
echo Quantity::of(5, 'km')->to('m');   // "5000 m"
echo Quantity::of(1, 'h')->to('s');    // "3600 s"

Arithmetic

$speed = Quantity::of(10, 'm')->divide(Quantity::of(2, 's')); // "5 m/s"
$area  = Quantity::of(2, 'm')->multiply(Quantity::of(3, 'm')); // "6 m²"

All operations return new Quantity objects with the proper dimension and unit.

Scalar math

echo Quantity::of(5, 'm')->times(3);      // "15 m"
echo Quantity::of(10, 'm')->dividedBy(4); // "2.5 m"
echo Quantity::of(2, 'm')->pow(2);        // "4 m²"
echo Quantity::of(4, 'm²')->sqrt();       // "2 m"
echo Quantity::of(-3, 'm')->abs();        // "3 m"

Dimension names

Quantity::of(1, 'm/s')->dimensionName(); // "velocity"
Quantity::of(1, 'N')->dimensionName();   // "force"
Quantity::of(1, 'Pa')->dimensionName();  // "pressure"

Temperature (affine scales)

echo Quantity::of(100, '°C')->to('°F')->format(1); // "212.0 °F"
echo Quantity::of(32, '°F')->to('°C')->format(1);  // "0.0 °C"
echo Quantity::of(25, '°C')->to('K')->format(2);   // "298.15 K"

Parsing strings

echo Quantity::parse('100 km/h')->to('mph')->format(2); // "62.14 mph"
echo Quantity::parse('-40 °C')->to('°F')->format(1);    // "-40.0 °F"
echo Quantity::parse('5 ft 3 in')->to('cm')->format(2); // "160.02 cm"  (segments summed)

Humanize (auto-pick the best unit)

echo Quantity::of(1500, 'm')->humanize();        // "1.5 km"
echo Quantity::of(2500000, 'B')->humanize();     // "2.5 MB"
echo Quantity::of(5400, 's')->humanize();        // "1.5 h"

Comparison

Quantity::of(1, 'm')->isGreaterThan(Quantity::of(90, 'cm')); // true
Quantity::of(1, 'm')->equals(Quantity::of(100, 'cm'));       // true

Precision & formatting

echo Quantity::of(1, 'm')->divide(Quantity::of(3, 's'))->format(2); // "0.33 m/s"

JSON

echo json_encode(Quantity::of(2, 'm')); // {"value":2,"unit":"m"}

Custom units

use KhaledAlam\Unit\{Unit, Name, Dimension, UnitRegistry};

UnitRegistry::register(new Unit('yard', 'yd', 0.9144, new Dimension(['L' => 1])));

echo Quantity::of(1, 'yd')->to('m'); // "0.9144 m"

Incompatible operations throw

Quantity::of(5, 'kg')->add(Quantity::of(3, 's')); // InvalidArgumentException

Supported units

Dimension	Units
Length	`mm`, `cm`, `m`, `km`, `in`, `ft`, `yd`, `mi`
Mass	`mg`, `g`, `kg`, `t`, `lb`, `oz`
Time	`ms`, `s`, `min`, `h`, `d`, `wk`
Area	`cm²`, `m²`, `km²`, `ft²`, `ha`, `acre`
Volume	`mL`, `L`, `m³`, `gal`
Temperature	`°C`, `°F`, `K`
Speed	`m/s`, `km/h`, `mph`, `kn`
Data	`bit`, `B`, `KB`, `MB`, `GB`, `TB`, `KiB`, `MiB`, `GiB`, `TiB`
Force	`N`, `kN`
Energy	`J`, `kJ`, `cal`, `kcal`, `Wh`, `kWh`
Power	`W`, `kW`, `hp`
Pressure	`Pa`, `kPa`, `bar`, `atm`, `psi`
Frequency	`Hz`, `kHz`, `MHz`, `GHz`
Angle	`rad`, `deg`, `grad`, `turn`

Need more? Open an issue or register your own.

Laravel integration

The package ships a service provider (auto-discovered) and an Eloquent cast. Store a quantity in a single column and get a Quantity back on access:

use Illuminate\Database\Eloquent\Model;
use KhaledAlam\Unit\Laravel\AsQuantity;

class Parcel extends Model
{
    protected function casts(): array
    {
        return ['weight' => AsQuantity::class];
    }
}

$parcel->weight = Quantity::of(2.5, 'kg'); // stored as "2.5 kg"
$parcel->weight->to('g');                   // 2500 g
$parcel->weight = '5 ft 3 in';              // strings are parsed on the way in

return [
    'units' => [
        new \KhaledAlam\Unit\Unit('furlong', 'fur', 201.168, new \KhaledAlam\Unit\Dimension(['L' => 1])),
    ],
];

Requires illuminate/database (already present in any Laravel app).

Symfony / Doctrine integration

A Doctrine DBAL type persists a Quantity as a string column. Register it once, then map any column with it:

use Doctrine\DBAL\Types\Type;
use KhaledAlam\Unit\Doctrine\QuantityType;

Type::addType(QuantityType::NAME, QuantityType::class); // e.g. in a bundle boot / bootstrap

use Doctrine\ORM\Mapping as ORM;

#[ORM\Column(type: 'quantity', nullable: true)]
public ?Quantity $weight = null;

Strings assigned to the property are parsed on write, and the column hydrates back into a Quantity on read.

Requires doctrine/dbal ^4.

Examples

Runnable scripts live in examples/:

php examples/basic.php
php examples/temperature.php
php examples/parse-and-humanize.php
php examples/scalar-math.php
php examples/shipping.php
php examples/physics.php

Testing & quality

composer test      # PHPUnit
composer analyse   # PHPStan (level max)
composer cs        # PHP-CS-Fixer (dry run)

The suite combines PHPUnit test classes with .phpt scenario tests and holds 100% line coverage, verified on PHP 8.2, 8.3, and 8.4 in CI (PHPStan level max, PSR-12).

Contributing

Contributions are welcome! Please read CONTRIBUTING.md and the Code of Conduct. Adding a unit is usually a three-line change.

khaledalam / unit

Maintainers

Package info

Statistics

Security