PHPackages                             renfordt/unit-lib - 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. renfordt/unit-lib

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

renfordt/unit-lib
=================

A PHP package for Units of Measurements

v1.1.0(4mo ago)02[1 PRs](https://github.com/renfordt/UnitLib/pulls)MITPHPPHP ^8.4CI passing

Since Oct 31Pushed 4mo ago1 watchersCompare

[ Source](https://github.com/renfordt/UnitLib)[ Packagist](https://packagist.org/packages/renfordt/unit-lib)[ Docs](https://github.com/renfordt/UnitLib)[ RSS](/packages/renfordt-unit-lib/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (3)Dependencies (7)Versions (10)Used By (0)

UnitLib
=======

[](#unitlib)

[![Badge](https://camo.githubusercontent.com/597fc35c6c4b1f77295d54de62a5d99408a239e110bdd871b34987ce81213051/687474703a2f2f696d672e736869656c64732e696f2f62616467652f736f757263652d72656e666f7264742f556e69744c69622d626c75652e737667)](https://github.com/renfordt/UnitLib)[![Packagist Version](https://camo.githubusercontent.com/e870769db3e0b8c1a4a34b28cc60fd8901d90d4784fa3ae18fd0d0b033dbcb77/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f72656e666f7264742f756e69742d6c6962)](https://packagist.org/packages/renfordt/unit-lib/)[![Packagist PHP Version](https://camo.githubusercontent.com/9c42e8d26a9098b26db9b69a0376e66997001c9590e85c9820f8aca269a066f4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f72656e666f7264742f756e69742d6c69622f706870)](https://camo.githubusercontent.com/9c42e8d26a9098b26db9b69a0376e66997001c9590e85c9820f8aca269a066f4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f72656e666f7264742f756e69742d6c69622f706870)[![GitHub License](https://camo.githubusercontent.com/011d83e3c996aad0ef632ae3ba97fbc880a26aa1bf538486bd6045072ff33815/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f72656e666f7264742f556e69744c6962)](https://camo.githubusercontent.com/011d83e3c996aad0ef632ae3ba97fbc880a26aa1bf538486bd6045072ff33815/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f72656e666f7264742f556e69744c6962)[![GitHub Actions Workflow Status](https://camo.githubusercontent.com/348d7e82c3dd3d20305b1cd0fcc1470d159e386a6d3ad3dd2155064c484a465a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f72656e666f7264742f636f6c6f72732f74657374732e796d6c3f6c6f676f3d676974687562)](https://camo.githubusercontent.com/348d7e82c3dd3d20305b1cd0fcc1470d159e386a6d3ad3dd2155064c484a465a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f72656e666f7264742f636f6c6f72732f74657374732e796d6c3f6c6f676f3d676974687562)[![Code Coverage](https://camo.githubusercontent.com/d578af7592d7ef25d98ce3ac41d6da1d11572f3113e3b702a2ba4834663c1033/68747470733a2f2f716c74792e73682f67682f72656e666f7264742f70726f6a656374732f556e69744c69622f636f7665726167652e737667)](https://qlty.sh/gh/renfordt/projects/UnitLib)[![Maintainability](https://camo.githubusercontent.com/5240797b871509d1c3465fd5a47f80d721b949f9710fd8d8db5fa90d304df8a3/68747470733a2f2f716c74792e73682f67682f72656e666f7264742f70726f6a656374732f556e69744c69622f6d61696e7461696e6162696c6974792e737667)](https://qlty.sh/gh/renfordt/projects/UnitLib)

> A modern, type-safe PHP library for handling physical quantities and unit conversions

---

Table of Contents
-----------------

[](#table-of-contents)

- [Overview](#overview)
- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Supported Quantities](#supported-quantities)
- [Usage Guide](#usage-guide)
    - [Creating Quantities](#creating-quantities)
    - [Converting Units](#converting-units)
    - [Arithmetic Operations](#arithmetic-operations)
    - [Derived Units through Operations](#derived-units-through-operations)
    - [Working with SI Prefixes](#working-with-si-prefixes)
    - [Temperature Conversions](#temperature-conversions)
- [Advanced Features](#advanced-features)
- [API Reference](#api-reference)
- [Development](#development)
- [Testing](#testing)
- [Contributing](#contributing)
- [License](#license)

---

Overview
--------

[](#overview)

UnitLib is a comprehensive PHP library designed for developers who need to work with physical quantities and perform accurate unit conversions. Built with modern PHP 8.4+ features, it provides a clean, type-safe API for handling measurements across various domains including length, mass, time, energy, and more.

### Why UnitLib?

[](#why-unitlib)

- **Type Safety**: Leverages PHP 8.4's property hooks for immutable, type-safe quantity objects
- **Zero Ambiguity**: No confusion about what unit you're working with
- **Extensive Unit Support**: From metric to imperial, nautical to scientific units
- **SI Prefix Support**: Automatic handling of kilo-, milli-, micro-, nano-, and more
- **Chainable API**: Fluent interface for readable, maintainable code
- **Well Tested**: Comprehensive test suite with strict coverage requirements

---

Features
--------

[](#features)

✨ **Comprehensive Unit Coverage**

- **Basic Quantities**: Length, Mass, Time, Temperature
- **Geometric**: Area, Volume
- **Mechanical**: Force, Pressure, Velocity, Acceleration, Torque, Density
- **Energy & Power**: Energy, Power, Frequency
- **Electrical**: Current, Voltage, Resistance, Charge, Capacitance, Inductance, MagneticFlux
- **Photometry**: Luminous Intensity
- **Chemistry**: Amount of Substance
- **Angular**: Angle

📐 **Flexible Conversions**

- Metric (SI) units with automatic prefix handling
- Imperial and US customary units
- Specialized units (nautical miles, knots, etc.)
- CGS units (maxwell, dyne, etc.)

🔒 **Type-Safe Design**

- Immutable quantity objects
- Strict type declarations throughout
- PHPStan level 9 compliant

🧮 **Advanced Mathematical Operations**

- Addition and subtraction of quantities
- Multiplication and division for derived units
- Power operations (e.g., Length² = Area)
- Automatic unit normalization
- Factory methods for convenient creation
- Ambiguity resolution (e.g., Force × Length can be Energy or Torque)

🔍 **Comparison Operations**

- Compare quantities: `greaterThan()`, `lessThan()`, `equals()`
- Epsilon-based floating-point equality
- Type-safe comparisons with automatic unit conversion
- Sorting support via `compareTo()`

📝 **String Parsing**

- Parse strings into quantities: `PhysicalQuantity::parse("5.5 meters")`
- Auto-detection or explicit type specification
- Support for decimals, negatives, SI prefixes

💾 **Serialization**

- JSON serialization via `JsonSerializable` interface
- Round-trip serialization with `fromJson()`
- Preserves both original and native values

🌡️ **Temperature Support**

- Handles offset-based conversions (Celsius, Fahrenheit)
- Kelvin, Rankine support
- Accurate inter-scale conversions

---

Requirements
------------

[](#requirements)

- **PHP**: 8.4 or higher
- **Composer**: For dependency management

---

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

[](#installation)

Install via Composer:

```
composer require renfordt/unit-lib
```

---

Quick Start
-----------

[](#quick-start)

```