Download the PHP package andanteproject/measurement without Composer

Measurement

PHP Library - AndanteProject

A modern, type-safe PHP library for handling physical measurements with automatic unit conversion, internationalization, and precise calculations.

Table of Contents

• Features
• Installation
• Quick Start
• Core Concepts
• Working with Quantities
  • Conversions
  • Arithmetic
  • Dimensional Analysis
  • Comparisons
  • Auto-Scaling
• Parsing and Formatting
  • Parsing Strings
  • Formatting Output
• Available Quantities
  • Electric Current
  • Acceleration
  • Density
  • Angle
  • Electric Charge
  • Magnetic Flux
  • Illuminance
  • Data Transfer Rate
• Registries
  • UnitRegistry
  • ConversionFactorRegistry
  • ResultQuantityRegistry
  • FormulaUnitRegistry
  • QuantityDefaultConfigProviderInterface
• Adding Custom Quantities
  • Step 1: Create the Dimension
  • Step 2: Create the Unit Enum
  • Step 3: Create the Quantity Interface
  • Step 4: Create Quantity Classes
  • Step 5: Create a Provider
  • Step 6: Register with the Library
  • Step 7: Add Translations (Optional)
• Testing

Features

• Type-Safe Quantities - Three levels of type safety (dimension, system, unit) with compile-time type checking and full IDE autocompletion
• Dimensional Analysis - Automatic type resolution (Length × Length = Area, Length ÷ Time = Velocity) that prevents dimensional errors at compile time
• Arbitrary Precision - Exact calculations using brick/math with no floating-point precision errors, handles very large and very small numbers accurately
• Auto-Scaling - Smart unit selection (1000 g → 1 kg) that automatically chooses the most appropriate unit representation across all quantity types
• String Parsing - Parse strings like "100 km", "5.5 kWh", "25 °C" with locale-aware number parsing, supports unit symbols and full unit names
• Flexible Formatting - Multiple output styles (Short, Long, Narrow, Value-only, Unit-only) with locale-aware number formatting and translated unit names
• Internationalization - 9 locales (en, de, es, fr, it, pt, ja, ru, zh) with separate locale support for numbers and unit names
• Locale-Aware Numbers - Parse "1.500,5 m" (IT) or "1,500.5 m" (US) with custom thousand and decimal separators
• Unit Systems - Complete SI & Metric support, full Imperial unit support with conversions, and Digital units with both SI (decimal) and IEC (binary) prefixes
• Extensible - Easy to add custom dimensions and units with provider-based registration system and full integration with existing library features
• Modern PHP 8.1+ - Enums, readonly properties, strict types, PHPStan level 9, immutable value objects, trait-based functionality composition

Installation

Requirements

• PHP 8.1 or higher
• brick/math (for arbitrary precision arithmetic)

Quick Start

Core Concepts

Dimension vs Unit vs Quantity

• Dimension: The physical nature (Length, Mass, Energy)
• Unit: A specific scale (meter, kilometer, foot)
• Quantity: A value + unit (5 meters)

Three Levels of Type Safety

The library provides three levels of specificity for type-hinting quantities. This allows you to be as strict or flexible as your use case requires - from accepting any length unit, to requiring a specific measurement system, to enforcing an exact unit.

Creating Quantities

There are multiple ways to create quantities, each corresponding to the three levels of type safety. Use NumberFactory::create() to create precise numeric values from strings, integers, or floats.

Working with Quantities

Once you have quantity objects, you can convert between units, perform arithmetic, compare values, and more. All operations are immutable - they return new quantity objects rather than modifying the original.

Conversions

Use the to() method to convert a quantity to a different unit within the same dimension. The conversion is handled automatically using the library's conversion factor registry.

Arithmetic

Quantities support addition, subtraction, multiplication by scalars, and division by scalars. When adding or subtracting quantities with different units, the right operand is automatically converted to the left operand's unit.

Dimensional Analysis

When multiplying or dividing quantities, the library automatically determines the result type:

Comparisons

Compare quantities using intuitive methods. Comparisons work across different units - the library automatically converts to a common unit before comparing.

Auto-Scaling

The autoScale() method automatically converts a quantity to the most human-readable unit. It prefers values between 1 and 1000, choosing larger or smaller units as appropriate.

Parsing and Formatting

The library includes powerful parsing and formatting capabilities with full internationalization support. Parse measurement strings from user input, and format quantities for display in any locale.

Parsing Strings

Convert strings like "100 km" or "5.5 kWh" into quantity objects. The parser handles unit symbols, full unit names, and locale-specific number formats.

ParseOptions Reference

Formatting Output

Format quantities for display with control over style, precision, and locale. The formatter supports multiple styles (Short, Long, Narrow) and translates unit names into 9 languages.

FormatOptions Reference

FormatStyle Options

SymbolNotation Options

Registries

The library uses four registries to manage units, conversions, and dimensional analysis. All registries are pre-configured with built-in quantities.

UnitRegistry

Maps units to their quantity classes. Used for parsing and creating quantities.

ConversionFactorRegistry

Stores conversion factors from each unit to its dimension's base unit.

ResultQuantityRegistry

Determines what quantity class to return from dimensional operations.

FormulaUnitRegistry

Maps dimensional formulas to default units for each system. When the library creates a result from dimensional analysis, it uses this registry to determine which unit to express the result in.

QuantityDefaultConfigProviderInterface

The QuantityDefaultConfigProviderInterface is the recommended way to register custom quantities with all four registries at once. Instead of manually registering with each registry, implement this interface to centralize your quantity's configuration.

Adding Custom Quantities

The library is fully extensible - you can add your own quantity types that integrate seamlessly with the existing system. This section walks through creating a custom "Viscosity" quantity as an example. The same pattern applies to any physical quantity you need to add.

Step 1: Create the Dimension

A dimension represents the physical nature of a quantity, defined by its dimensional formula using the seven SI base dimensions: Length (L), Mass (M), Time (T), Electric Current (I), Temperature (Θ), Amount of Substance (N), and Luminous Intensity (J).

Examples of dimensional formulas:

• Velocity = L¹T⁻¹ (length per time)
• Force = L¹M¹T⁻² (mass times acceleration)
• Pressure = L⁻¹M¹T⁻² (force per area)
• Viscosity = L⁻¹M¹T⁻¹ (used in this example)

Step 2: Create the Unit Enum

Units are implemented as PHP enums that implement UnitInterface. Each unit defines its symbol, name, dimension, and measurement system (SI, Metric, or Imperial). The enum pattern provides type safety and IDE autocompletion.

Step 3: Create the Quantity Interface

Create an interface that extends QuantityInterface. This enables type-hinting for your quantity in function signatures and allows for the three-level type safety pattern (generic → system-specific → unit-specific).

Step 4: Create Quantity Classes

Create the actual quantity classes that hold values. Use the provided traits (ConvertibleTrait, ComparableTrait, CalculableTrait, AutoScalableTrait) to get conversion, comparison, arithmetic, and auto-scaling functionality without writing boilerplate code.

Step 5: Create a Provider

The provider centralizes all registry configuration for your quantity. It defines which units exist, their conversion factors to the base unit, and how dimensional analysis results should be mapped. This is the recommended pattern used by all built-in quantities.

Step 6: Register with the Library

Call your provider's registration methods during application bootstrap to make your quantity available throughout the library. After registration, parsing, formatting, conversions, and dimensional analysis will all work with your custom quantity.

Step 7: Add Translations (Optional)

To enable localized formatting with FormatStyle::Long, register translations programmatically using the TranslationLoader::registerTranslation() method.

The registerTranslation() method accepts a unit and an array mapping plural rules (one, other) to translated names. Registered translations take precedence over built-in translations, so you can also use this to override existing unit names if needed.

Available Quantities

The library provides 29 quantity types with 200+ units. Each quantity includes:

• A generic class accepting any unit in the dimension
• Mid-level classes for system-specific type safety (Metric/Imperial/SI)
• Unit-specific classes for maximum type safety

Length [L¹]

The SI base unit of distance. Supports metric and imperial systems.

Mass [M¹]

The SI base unit of mass. Supports metric and imperial systems.

Time [T¹]

The SI base unit of time. All Time classes include PHP DateInterval integration:

• toPhpDateInterval() - convert to PHP \DateInterval
• ofPhpDateInterval(\DateInterval $interval) - create from PHP \DateInterval

Temperature [Θ¹]

Uses affine conversions (factor + offset) for Celsius and Fahrenheit.

Electric Current [I¹]

The SI base unit of electric current.

Area [L²]

Derived from Length × Length.

Volume [L³]

Derived from Length × Length × Length. Includes gas measurement units.

Velocity [L¹T⁻¹]

Derived from Length ÷ Time.

Acceleration [L¹T⁻²]

Derived from Velocity ÷ Time.

Force [L¹M¹T⁻²]

Derived from Mass × Acceleration.

Pressure [L⁻¹M¹T⁻²]

Derived from Force ÷ Area.

Energy [L²M¹T⁻²]

Work and heat. Includes electrical and thermal units.

Power [L²M¹T⁻³]

Derived from Energy ÷ Time.

Density [L⁻³M¹]

Derived from Mass ÷ Volume.

Frequency [T⁻¹]

Derived from 1 ÷ Time.

Angle [dimensionless]

Plane angle measurement.

Electric Potential [L²M¹T⁻³I⁻¹]

Voltage. Derived from Power ÷ Current.

Electric Resistance [L²M¹T⁻³I⁻²]

Derived from Voltage ÷ Current.

Electric Capacitance [L⁻²M⁻¹T⁴I²]

Ability to store electric charge.

Electric Charge [T¹I¹]

Derived from Current × Time.

Inductance [L²M¹T⁻²I⁻²]

Property of an electrical conductor.

Magnetic Flux [L²M¹T⁻²I⁻¹]

Measure of total magnetic field through a surface.

Luminous Intensity [J¹]

The SI base unit of luminous intensity.

Luminous Flux [J¹]

Total amount of visible light emitted.

Illuminance [L⁻²J¹]

Derived from Luminous Flux ÷ Area.

Calorific Value [L⁻¹M¹T⁻²]

Energy per unit volume. Used for gas billing.

Digital Information [D¹]

Data storage capacity. Supports SI (decimal) and IEC (binary) prefixes.

SI Units (decimal, powers of 10):

IEC Units (binary, powers of 2):

Data Transfer Rate [D¹T⁻¹]

Measures the speed of data transmission, commonly used for network bandwidth, internet connection speeds, and file transfer rates. Like Digital Information, this quantity supports both SI (decimal) and IEC (binary) prefixes. ISPs and network equipment typically advertise speeds using SI units (e.g., "100 Mbps fiber"), while operating systems often report actual transfer rates in IEC units (e.g., "12 MiB/s"). This distinction matters because 100 Mbps (megabits per second) equals 12.5 MB/s (megabytes per second) but only about 11.92 MiB/s (mebibytes per second).

SI Units:

IEC Units:

Testing

Docker Support

Built with ❤️ by AndanteProject team.