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";

Output:

1 kg
1 000 g
100 dkg

Support

I prefer to keep my work available to everyone. In order to do so I rely on voluntary contributions on Patreon.

License

This project is licensed under the MIT License. See the LICENSE file for details.