README

A PHP library to represent various physical quantities as value objects with the ability to convert between units and format them according to International System of Units (SI) or Imperial standards.

Requirements

PHP: ^8.5
Extensions:
- ext-ds
- ext-intl

Installation

To install, use composer:

composer require pdobrovolny/quantity

Setup & Development

Setup

Clone the repository and install dependencies:

git clone https://gitlab.com/pdobrovolny/quantity.git
cd quantity
composer install

Running Tests

The project uses Pest for testing.

vendor/bin/pest

Static Analysis

Check code quality with PHPStan:

vendor/bin/phpstan analyse

Refactoring & Code Style

The project uses Rector for automated refactoring:

vendor/bin/rector process

Project Structure

src/: Core library logic.
- Container/: Quantity value object implementations.
- Contracts/: Interfaces for quantities and factories.
- Enums/: Enumerations for dimensions and exponents.
- Factory/: Factories for creating quantities.
- Formatter/: Logic for unit and quantity formatting.
tests/: Test suite.
- unit/: Unit tests.
- integration/: Integration tests.

Documentation and usage

A library to represent various quantities as value objects with the ability to convert from one Unit of Measurement to another.

International System of Units

Base units

Amount of substance
Electric current
Length
Luminous intensity
Mass (base unit is kilogram)
Thermodynamic temperature
Time

Derived units

Absorbed dose
Acceleration
Angle
Area
Capacitance
Catalytic activity
Electric resistance (Resistance)
Electric charge (Charge)
Electric conductance (Conductance)
Equivalent dose
Force
Frequency
Illuminance
Inductance
Luminous flux
Magnetic flux
Magnetic flux density
Power
Pressure
Radioactivity
Solid angle
Velocity
Voltage
Volume
Volumetric flow rate
Work

Sub-units

Angle
- ArcMinute
- ArcSecond
- Degree
Length
- Astronomical unit
- Light year
- Parsec
Mass
- Atomic mass unit
- Dalton
- Tonne
Time
- Day
- Hour
- Minute
Celsius
Bel
Hectare
Liter
Optical power
Volt-ampere

Imperial units

Area
- Square Chain
- Square Foot
- Square Furlong
- Square Inch
- Square League
- Square Mile
- Square Yard
Length
- Chain
- Foot
- Furlong
- Inch
- League
- Mile
- Yard
Mass
- Grain
- Hundredweight
- Ounce
- Pound
- Stone
- Ton
Volume
- Cubic Chain
- Cubic Foot
- Cubic Furlong
- Cubic Inch
- Cubic League
- Cubic Mile
- Cubic Yard
- UK
  - FluidOunce
  - Gallon
  - Gill
  - Pint
  - Quart
- US
  - FluidOunce
  - Gallon
  - Gill
  - Pint
  - Quart
Fahrenheit

Examples

Main examples

Basic usage:

$length = new Length(1.);

\var_dump($length->value);                            // double(1)
\var_dump(EUnitSymbol::fromQuantity($length)->value); // string(1) "m"

Create a quantity by the factory:

$quantityFactory = new QuantityFactory();

$length = $quantityFactory->createWithValue(ILength::class, 1., EMetricExponent::KILO);

\var_dump($length->value);     // double(1000)
\var_dump($length::class);     // string(50) "PDobrovolny\Quantity\Container\Metric\Basic\Length"

Create a quantity by a formula:

$quantityFactory = new QuantityFactory();
$length = $quantityFactory->createWithValue(ILength::class, 100000);
$time = $quantityFactory->createWithValue(ITime::class, 3600);

$velocity = $quantityFactory->create(IVelocity::class, \compact('length', 'time'));

\var_dump($velocity->value);        // double(27.777777777778)
\var_dump($velocity::class);        // string(54) "PDobrovolny\Quantity\Container\Metric\Derived\Velocity"

Customization factory:

final readonly class MyLength implements ILength
{
    public function __construct(public float $value)
    {
    }
}

$quantityFactory = new QuantityFactory([
    ILength::class => autowire(MyLength::class),
]);

$length = $quantityFactory->createWithValue(ILength::class, 1.);
\var_dump($length::class);          // string(16) "example\MyLength"

Converting examples

Mile to Length:

$quantityFactory = new QuantityFactory();
$mile = $quantityFactory->createWithValue(IMile::class, 1);

$length = $quantityFactory->create(ILength::class, \compact('mile'));

\var_dump($length->value);      // double(1609.344)

Celsius to Fahrenheit:

$quantityFactory = new QuantityFactory();

$celsius = $quantityFactory->createWithValue(ICelsius::class, 20);
$thermodynamicTemperature = $quantityFactory->create(IThermodynamicTemperature::class, compact('celsius'));
$fahrenheit = $quantityFactory->create(IFahrenheit::class, compact('thermodynamicTemperature'));

\var_dump($fahrenheit->value);      // double(68)

Formatting example

Creating of QuantityFormatter:

$formatter = new QuantityFormatter(
    new \NumberFormatter('cs_CZ', \NumberFormatter::PATTERN_DECIMAL)
);

Scaling a quantity:

$quantity = new Length(1.);

echo $formatter->format($quantity) . "\n\n";

echo $formatter->format($quantity, EMetricExponent::MILLI) . "\n";
echo $formatter->format($quantity, EMetricExponent::BASE) . "\n";
echo $formatter->format($quantity, EMetricExponent::DECA) . "\n";
echo $formatter->format($quantity, EMetricExponent::KILO) . "\n";

Output:

1 m

1 000 mm
1 m
0,1 dam
0,001 km

Mass formatting (base unit is kilogram):

$quantity = new Mass(1.); // 1 kg

echo $formatter->format($quantity) . "\n";
echo $formatter->format($quantity, EMetricExponent::BASE) . "\n";
echo $formatter->format($quantity, EMetricExponent::DECI) . "\n";