PHPackages                             zlikavac32/php-measure-units - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. zlikavac32/php-measure-units

ActiveLibrary[Utility & Helpers](/categories/utility)

zlikavac32/php-measure-units
============================

Measure units implementation for PHP

0.3.0(5y ago)4908MITPHPPHP ^8.0CI failing

Since Nov 4Pushed 5y ago1 watchersCompare

[ Source](https://github.com/zlikavac32/php-measuring-units)[ Packagist](https://packagist.org/packages/zlikavac32/php-measure-units)[ RSS](/packages/zlikavac32-php-measure-units/feed)WikiDiscussions master Synced today

READMEChangelogDependencies (4)Versions (5)Used By (0)

Units of measure for PHP
========================

[](#units-of-measure-for-php)

[![Build Status](https://github.com/zlikavac32/php-measuring-units/workflows/Build/badge.svg?branch=master)](https://github.com/zlikavac32/php-measuring-units/workflows/Build/badge.svg?branch=master)

Library to manage various measure units, quantities, and conversions between them.

Table of contents
-----------------

[](#table-of-contents)

1. [Introduction](#introduction)
2. [Installation](#installation)
3. [Configuration](#configuration)
4. [Usage](#usage)
    1. [Manipulating measure units](#manipulating-measure-units)
    2. [Quantities](#quantities)
    3. [Scale](#scale)
5. [Limitations](#limitations)
6. [Examples](#examples)

Introduction
------------

[](#introduction)

In the real world, a number on its own does not carry a lot of meaning. We usually associate a certain dimension with it like the length or the volume. Every dimension has its units of measures. By combining value with the dimension, we get a quantity.

Let's take a simple example of calculating a `sin` of an angle.

```
$angle = 90;

echo sin($angle);
```

We get `0.89399666360056` which is not one, and this is an example of a mismatched measure unit. Implementation of `sin` expects the value to be provided in radians while we provide in degrees. It's easy to make one such mistake so a better environment is needed.

Let's now imagine we have a concept of the quantity in PHP.

```
$angle = new Quantity(90, 'degc');

echo sin($angle->in('rad')->value());
```

Now it's much harder to make the previous mistake. If the dimension of the provided `$angle` is not the same as `rad`, this will fail. If the dimension is the same, then the value of `90` will be converted to a requested measure unit.

We could also have a `sin` function that directly accepts a quantity.

All in all, if you, for some reason, handle quantities in various units of measure, it's important to maintain consistency, So the goal of this library is to make manipulation of quantities and measure units easier and bring that consistency into the code.

It's important to note that this library does not yet implement the concept of dimension. Only the concept of measure unit is implemented. For example, both radians and steradians have the same representation in the terms of SI units (no unit), but we can not add them or subtract them. This library does not make this distinction yet.

Installation
------------

[](#installation)

The recommended installation is through Composer.

```
composer require zlikavac32/php-measure-units

```

Configuration
-------------

[](#configuration)

To work with measure units, some services must be constructed.

```
use Zlikavac32\UnitsOfMeasure\Defaults;
use Zlikavac32\UnitsOfMeasure\MapUnitNormalizer;
use Zlikavac32\UnitsOfMeasure\NativeRuntime;
use Zlikavac32\UnitsOfMeasure\SiFormParser;

$baseUnits = Defaults::siBaseUnits();

$transitionMap = Defaults::siDerivedUnits()
                         ->merge(Defaults::otherMetricUnits());

$imperialUnits = Defaults::imperialUnits();

$parser = new SiFormParser($baseUnits->merge($transitionMap->keys())->toArray(), $imperialUnits->keys()->toArray());

$normalizer = new MapUnitNormalizer(
    $transitionMap->merge($imperialUnits),
    $baseUnits
);

$unitsOfMeasure = new NativeRuntime(
  $parser,
  $normalizer
);
```

Variable `$unitsOfMeasure` is the main entry point for measurement units. `NativeRuntime` implements `\Zlikavac32\UnitsOfMeasure\Runtime` which can be used to create measure units and quantities.

Default implementation that is provided is `\Zlikavac32\UnitsOfMeasure\NativeRuntime` and it requires an instance of `\Zlikavac32\UnitsOfMeasure\Parser` and an instance of `\Zlikavac32\UnitsOfMeasure\Normalizer`.

The default implementation for the normalizer is `\Zlikavac32\UnitsOfMeasure\MapUnitNormalizer` which requires a map of transitions and a set of base units.

There are two implementations of the parser. One that uses canonical SI form like `kg.m` or `m.s-2` (`\Zlikavac32\UnitsOfMeasure\SiFormParser`) and the other uses more human form like `m/s` or `kg m/s2` (`\Zlikavac32\UnitsOfMeasure\HumanFormUnitsParser`).

`\Zlikavac32\UnitsOfMeasure\Defaults` contains a set of predefined base measure units as well as various derived units.

Usage
-----

[](#usage)

Once the measure unit environment is created, one can create a measure unit instance by calling `parse(string $measureUnit)` method which returns an instance of `\Zlikavac32\UnitsOfMeasure\MeasureUnit`.

```
echo (string) $unitsOfMeasure->parse('kg.m.s-2), "\n";
```

Instead of calling `parse()`, it's possible to use array syntax to retrieve a measuring unit.

```
echo (string) $unitsOfMeasure['kg.m.s-2'], "\n";
```

### Manipulating measure units

[](#manipulating-measure-units)

Measure units can be multiplied, divided, raised to a power, inverted or converted between each other. Measure unit interface is straight forward, except `in(string|MeasureUnit $measureUnit)` method. It returns an instance of `\Zlikavac32\UnitsOfMeasure\Ratio`. To properly define a ratio, it's not enough just to have a number. We must also keep track of whether conversion inverts original units. For example, when converting `Hz` to `s`, the ratio is one, but the unit is globally inverted. So converting `2 Hz` is actually `0.5 s`.

```
$m = $unitsOfMeasure['m'];
$kg = $unitsOfMeasure['kg'];
$s2 = $unitsOfMeasure['s2'];

$newton = $m->multiplyBy($kg)->divideBy($s2);

echo $newton->in('kN')->applyTo(5);
```

Check [Examples](#examples) for more info.

### Quantities

[](#quantities)

Instead of manually tracking value and its measure unit, they can be paired in a quantity.

Quantities can be created using `__invoke(int $value, string|MeasureUnit $measureUnit)` method. It returns an instance of `\Zlikavac32\UnitsOfMeasure\Quantity`.

```
echo (string) $unitsOfMeasure(3, 'm3'), "\n";

echo (string) $unitsOfMeasure(3, $unitsOfMeasure['s']), "\n";
```

Quantities can also be multiplied, divided, raised to a power, etc.

```
$m = $unitsOfMeasure(1, 'm');
$kg = $unitsOfMeasure(1, 'kg');
$s2 = $unitsOfMeasure(1, 's2');

$newton = $m->multiplyBy($kg)->divideBy($s2);

echo (string) $newton->in('kN');
```

When performing operations like multiply or divide, the resulting measure unit is not automatically reduced. For example, multiplying `kg`, with `m`, and then dividing by `s2`, will not be `N`. Measure unit is representing `N`, but it is not `N`. To get a measuring unit that is `N`, one must make an explicit call to the `in()` method.

```
echo (string) $newton, "\n";
echo (string) $newton->in('N');
```

Check [Examples](#examples) for more info.

### Scale

[](#scale)

This library also supports scaled measure units. For example, the measuring unit for gasoline consumption can be `l/100 km`. One other example is fluid flow like `m3/15 min`.

```
$gasolineConsumptionPer100Km = $unitsOfMeasure['l.100 km-1'];

// How many kilometers can we make with one liter if we had consumption of 4 liters per 100 kilometers
echo $gasolineConsumptionPer100Km->in('km.l-1')->applyTo(4);
```

To some extent, this can be used for direct measure unit conversion.

```
echo $unitsOfMeasure['123 cm']->in('m')->ratio()->asFloat(), "\n";
echo $unitsOfMeasure['500 kg.6 m.2 s-2']->in('kN')->ratio()->asFloat();
```

Different runtime operations could support different measure unit formats, so one might implement runtime that parses `100cm+1mm` as `101 cm` directly.

Limitations
-----------

[](#limitations)

One limitation mentioned above is that the user of this library must provide semantic checks to measure unit operations. This library will not complain if you try to add radians with steradians since they have the same SI uni representation.

Another limitation is that this library handles only measure unit conversions with a constant ratio. That being said, conversion from degrees Celsius to Kelvin is not supported out of the box. Custom runtime can still be provided to accommodate that need.

Examples
--------

[](#examples)

You can see more examples with code comments in [examples](/examples).

###  Health Score

29

—

LowBetter than 57% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity20

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~263 days

Total

3

Last Release

1909d ago

PHP version history (3 changes)0.1.0PHP ^7.3

0.2.0PHP ^7.4

0.3.0PHP ^8.0

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/1078270?v=4)[Marijan Šuflaj](/maintainers/zlikavac32)[@zlikavac32](https://github.com/zlikavac32)

---

Top Contributors

[![zlikavac32](https://avatars.githubusercontent.com/u/1078270?v=4)](https://github.com/zlikavac32 "zlikavac32 (18 commits)")

---

Tags

conversionsmeasuremeasurement-unitsphpunit-converterconversionunitsmeasurementsmeasure unitmeasuring unit

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/zlikavac32-php-measure-units/health.svg)

```
[![Health](https://phpackages.com/badges/zlikavac32-php-measure-units/health.svg)](https://phpackages.com/packages/zlikavac32-php-measure-units)
```

###  Alternatives

[cuyz/valinor

Dependency free PHP library that helps to map any input into a strongly-typed structure.

1.5k13.2M174](/packages/cuyz-valinor)[php-units-of-measure/php-units-of-measure

A PHP library for converting between standard units of measure.

3143.8M36](/packages/php-units-of-measure-php-units-of-measure)[florianv/swap

PHP currency conversion library for retrieving exchange rates from 30+ providers, with caching and fallback.

1.3k6.8M23](/packages/florianv-swap)[spatie/color

A little library to handle color conversions

38221.2M36](/packages/spatie-color)[gabrielelana/byte-units

Library to parse, format and convert byte units

1752.3M21](/packages/gabrielelana-byte-units)[ozdemirburak/iris

PHP library for color manipulation and conversion.

1201.9M23](/packages/ozdemirburak-iris)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)