README

Set of DTOs to deal with various physical units and conversions.

This repository contains a collection of Data Transfer Objects (DTOs) that are designed to handle various physical unit representations and conversions effectively. The DTOs ensure consistent unit management, making it easier to work with different measurement systems in software applications.

Installation

To install the DTOs, you can use the following command:

composer require webboy/measurement-units

Usage

The DTOs are designed to be easy to use and understand. Here is an example of how you can use the Distance DTO:

use Webboy\MeasurementUnits\Measurements\DistanceMeasurementDto;

// Create a new distance measurement.
$measurement = new DistanceMeasurementDto();

// Set the value of the measurement.
$distance_value = $measurement->createValue(100, DistanceUnitEnum::KILOMETER->value);

// Print the distance value.
echo ("My distance in km is: " . $distance_value . PHP_EOL);

// Convert the distance value to meters.
$converted_distance_value = $distance_value->to(DistanceUnitEnum::MILE->value);

// Print the converted distance value.
echo ("My distance in miles is: " . $converted_distance_value . PHP_EOL);

Available DTOs

The following DTOs are available in this package:

• AreaMeasurementDto
• DistanceMeasurementDto
• MassMeasurementDto
• SpeedMeasurementDto
• TemperatureMeasurementDto
• VolumeMeasurementDto
• PressureMeasurementDto
• TorqueMeasurementDto
• PowerMeasurementDto
• FuelConsumptionMeasurementDto
• BatteryCapacityMeasurementDto
• VoltageMeasurementDto

Customizing the DTOs

The DTOs are designed to be easily customizable. You can extend the DTOs to add new units or modify existing ones. Here is an example of how you can extend the Distance DTO:

use Webboy\MeasurementUnits\Enums\Units\DistanceUnitEnum;
use Webboy\MeasurementUnits\Measurements\DistanceMeasurementDto;

// Create a new CUSTOM distance measurement with a custom base unit.
$measurement = new CustomMeasurementDto(
    'custom',
    'Length',
    'ft',
    [
        // You can use a DistanceUnitEnum value as the ID.
        new Webboy\MeasurementUnits\Units\DistanceUnitDto(DistanceUnitEnum::FOOT),

        // You can use a CustomUnitDto to create a completely custom unit.
        new Webboy\MeasurementUnits\Units\CustomUnitDto(
            id: 'miles',
            name: 'Miles',
            symbol: 'mi',
            toBase: fn($value) => $value * 5280,
            fromBase: fn($value) => $value / 5280,
            validIds: false
        )
    ]
);

// Set the value of the measurement.
$distance_value = $measurement->createValue(1000, DistanceUnitEnum::FOOT->value);

// Print the value.
echo ("My distance in feet is: " . $distance_value . PHP_EOL);

// Convert the value.
$converted_distance_value = $distance_value->to('miles');

// Print the converted value.
echo ("My distance in miles is: " . $converted_distance_value . PHP_EOL);

Fancy Customization

You can also use the CustomUnitDto to create a completely custom unit. This allows you to define your own conversion functions and custom units. Here is an example of how you can use the CustomUnitDto:

use Webboy\MeasurementUnits\Measurements\CustomMeasurementDto;
use Webboy\MeasurementUnits\Units\CustomUnitDto;

// Create a new CUSTOM measurement with a custom base unit.
$wizardness = new CustomMeasurementDto(
    id:'Wizardness',
    name: 'Wizardness level',
    units: [
        // Set the base unit.
        new CustomUnitDto(
            'merlin',
            'Merlin',
            'MRLN',
            fn($value) => $value,
            fn($value) => $value,
            true
        ),
        new CustomUnitDto(
            'harry',
            'Harry',
            'HRRY',
            fn($value) => $value / 3.223,
            fn($value) => $value * 3.223,
        ),
        new CustomUnitDto(
            'gandalf',
            'Gandalf',
            'GND',
            fn($value) => $value * 2.122,
            fn($value) => $value / 2.122,
        ),
    ]
);

// Set the value of the measurement.
$wizardness_value = $wizardness->createValue(1, 'gandalf');

// Print the wizardness value.
echo ("My wizardness in gandalf is: " . $wizardness_value . PHP_EOL);

// Convert the wizardness value to harry.
$converted_wizardness_value = $wizardness_value->to('harry');

// Print the converted wizardness value.
echo ("My wizardness in harry is: " . $converted_wizardness_value . PHP_EOL);

Extending the DTOs

You can also extend the DTOs to add new functionality or modify existing behavior. Here is an example of how you can extend the Distance DTO:

class FuelCapacity extends CustomMeasurementDto
{
    // It will load unit definitions from a Definitions/FuelCapacity/FuelCapacityDefinitions.php file.
    public function __construct()
    {
        parent::__construct(
            id:'fuel-capacity',
            name:'Fuel Capacity',
            base_unit_id:VolumeUnitEnum::LITRE->value,
            units: [
                new Webboy\MeasurementUnits\Units\VolumeUnitDto(VolumeUnitEnum::LITRE),
                new Webboy\MeasurementUnits\Units\VolumeUnitDto(VolumeUnitEnum::GALLON),
            ]

        );
    }
}

// Create a new value with a custom measurement.
$measurement = new FuelCapacity();

$fuel_capacity = $measurement->createValue(100, VolumeUnitEnum::GALLON->value);

// Print the fuel capacity value.
echo ("My fuel capacity in gallons is: " . $fuel_capacity . PHP_EOL);

// Convert the fuel capacity value to liters.
$converted_fuel_capacity = $fuel_capacity->to(VolumeUnitEnum::LITRE->value);

// Print the converted fuel capacity value.
echo ("My fuel capacity in liters is: " . $converted_fuel_capacity . PHP_EOL);

Even more fancy extensions

You can also extend the existing units, or extend the basic units to create new ones. You can also create new DTOs that extend the existing ones. Here is an example of how you can create your own measurements and units

class MyVolumeUnit extends UnitDto
{
    public function __construct()
    {
        parent::__construct(
            id:'my-volume-unit',
            name: 'My Volume Unit',
            symbol: 'mvu',
            toBase: fn($value) => $value,
            fromBase: fn($value) => $value,
            isBase: true,
            validIds: false
        );
    }
}

class MyKiloVolumeUnit extends UnitDto
{
    public function __construct()
    {
        parent::__construct(
            id:'my-kilo-volume-unit',
            name: 'My Kilo Volume Unit',
            symbol: 'Kmvu',
            toBase: fn($value) => $value * 1000,
            fromBase: fn($value) => $value / 1000,
        );
    }
}

class ImaginaryMeasurement extends MeasurementDto
{
    // It will load unit definitions from a Definitions/FuelCapacity/FuelCapacityDefinitions.php file.
    public function __construct()
    {
        parent::__construct(
            id: 'imaginary-measurement',
            name: 'ImaginaryMeasurement',
            units:[
                new MyVolumeUnit(),
                new MyKiloVolumeUnit()
            ]
        );
    }
}

// Create a new value with a custom measurement.
$measurement = new ImaginaryMeasurement();

$value = $measurement->createValue(100, 'my-volume-unit');

// Print the value.
echo ("My value in {$value->unit->symbol} is: " . $value . PHP_EOL);

// Convert value to my-kilo-volume-unit.
$converted_value = $value->to('my-kilo-volume-unit');

// Print the converted value.
echo ("My fuel value in {$converted_value->unit->symbol} is: " . $converted_value . PHP_EOL);

Testing

To run the tests, you can use the following command:

composer run-script test

Contributing

If you would like to contribute to this project, please feel free to submit a pull request. We welcome contributions