Setup

Setting up convertor could not be simpler.

Include the library in your project and you are good to go!

include("Convertor.php");

Convert A Unit

To convert a unit, create an instance of Convertor passsing two arguments to the constructor. The first argument is the value to be converted from, the second argument is a case sensitive string representing its unit. This returns a Convertor object that will refrenece all its conversions to your initial unit and value.

You can then call the to() function on the Convertor object, passing the desired output unit as the first argument.

$demoConvertor = new Convertor(10, "m");
$demoConvertor->to("ft"); //returns converted value

Result: 10 Meters = 32.808398950131 Feet

A full list of available units can be found in the Available Units section.

Convert to Multiple Units

Once you have setup your Convertor instance you can convert the same value into multiple units by calling the to() function multiple times.

$demoConvertor = new Convertor(10, "m");
$demoConvertor->to("km"); //returns converted value in kilometers
$demoConvertor->to("ft"); //returns converted value in feet

Results:
10 Meters = 0.01 kilometre
10 Meters = 32.808398950131 Feet

Multiple Unit Array Output

Alternatively, you can pass an array of units to the to() function. This will return an associative array containting all of the conversions.

$demoConvertor->to(["km","ft","in"]); //returns an array of converted values in kilometers, feet and inches

The result of the above function would be:

[
    "km" => 0.01,
    "ft" => 32.808398950131,
    "in" => 393.70078740157
]

Convert to All Compatible Units

You can convert a value to all compatible units using the toAll() function

$demoConvertor = new Convertor(10, "m");
$demoConvertor->toAll(); //returns all compatible converted value

This will return an associative array containing the conversions for all compatible units, in the case of "meters" as an inital unit, Convertor will return all available distance unit conversions.

[
    "m" => 10,
    "km" => 0.01,
    "dm" => 100,
    "cm" => 1000,
    "mm" => 10000,
    "μm" => 10000000,
    "nm" => 10000000000,
    "pm" => 10000000000000,
    "in" => 393.70078740157,
    "ft" => 32.808398950131,
    "yd" => 10.936132983377,
    "mi" => 0.0062137119223733
]

List Compatible Units

You can generate a list of all compatible units using the getUnits() function.

$demoConvertor = new Convertor();
$demoConvertor->getUnits("m"); //returns converted value

This will return an array of all available units compatible with the specified unit:

["m", "km", "dm", "cm", "mm", "μm", "nm", "pm", "in", "ft", "yd", "mi"]

Change Initial Value

You can change the value and unit you are converting from at any point using the from() function.

$demoConvertor = new Convertor(10,"m");
$demoConvertor->to("ft"); //returns converted value in feet
$demoConvertor->from(5.23,"km"); //sets new from value in new unit
$demoConvertor->to("mi"); //returns converted new value in miles

Results:
10 Meters = 32.808398950131 Feet
5.23 Kilometers = 3.2497713354013 Miles

Result Precision

The precision of the results can be set using two optional arguments in the to() function to specify the decimal precision and use of rounding.

In adition to the standard first argument of the conversion unit, the second argument is an integer representing the decimal precision of the result, the third argument is a booolean that indicates wheather the result should be rounded (true, default value) or truncated (false).

$precisionConvertor->to("ft", 4, true);

Result: 10 Meters = 32.8084 Feet (rounded to 4 decimal places)

Adding Custom Units

It is possibly to add your own unit to Convertor using the addUnit() function.

The function takes three parameters, the first is the string symbol for the new unit, the second argument is the base unit for the conversion, this determines which category the unit can be converted in (more information on base usits can be found below), the third argument is the conversion function of the new unit to the base unit, if it is a simple multiplier/divisior then you can pass a number for this argument, if it is more complex then a callback can be used.

//add the kilometre unit
$precisionConvertor->addUnit("km", "m", 1000); //add the kilometre unit to the length conversion base unit "m", a kilometer is 1000m;

//add Fahrenheit to the temperature category, this has a complex conversion calculation so uses a callback
var fahrenheitConversion = function($val, $tofrom){
    //$val - value to convert
    //$tofrom - wheather it is being converted to or from the base unit (true - to base unit, false - from base unit to current unit)

    return $tofrom ? ($val * 9/5 - 459.67) : (($val + 459.67) * 5/9);
}

$precisionConvertor->addUnit("f", "k", fahrenheitConversion); //add the Fahrenheit unit to the temperature conversion base unit "k", ;

//create a new base unit for a sound category, with a base unit of dB
$precisionConvertor->addUnit("dB", "dB", 1); //create the base unit of dB, a base unit should alwasys have a conversion value of 1;

Base Units

Convertor works by storing each type of unit as a conversion function from a base unit. This way only one conversion function needs to be stored with each unit to enable conversion between any in the same category.

When a conversion is requested Convertor will first convert the provided value into the base unit for that category, then convert it into the chosen output units.

The base unit for each category can be found highligted in the Available Units section.

Removing Units

If you want to remove a unit from Convertor to make room for one with the same symbol string, you can use the removeUnit() function. this function takes one argument, which is the string representing the unit symbol.

$demoConvertor = new Convertor();
$demoConvertor->removeUnit("km"); //remove kilometre unit

Available Units

Convertor comes with a large number of standard units build in. this section details all of these units by category.

The base unit for each category is highlighted in bold.

Length

m - Meter
km - Kilometer
dm - Decimeter
cm - Centimeter
mm - Milimeter
μm - Micrometer
nm - Nanometer
pm - Picometer
in - Inch
ft - Foot
yd - Yard
mi - Mile
h - Hand
ly - LightYear
au - Astronomical Unit
pc - Parsec

Area

m2 - Square Meter
km2 - Square Kilometer
cm2 - Square Centimeter
mm2 - Square Milimeter
ft2 - Square Foot
mi2 - Square Mile
ac - Acre
ha - hectare

Volume

l - Litre
ml - Mililitre
m3 - Cubic Meter
pt - Pint
gal - Galon

Weight

kg - Kilogram
g - Gram
mg - Miligram
N - Newton (based on earth gravity)
st - Stone
lb - Pound
oz - Ounce
t - Metric Tonne
ukt - UK Long Ton
ust - US short Ton

Speed

mps - Meters per Second
kph - Kilometers Per Hour
mph - Miles Per Hour

Rotation

deg - Degrees
rad - Radian

Temperature

k - Kelvin
c - Centigrade
f - Fahrenheit

Pressure

pa - Pascal
kpa - kilopascal
mpa - MegaPascal
bar - Bar
mbar - Milibar
psi - Pound-force per square inch

Time

s - Second
year - Year (365 days)
month - Month (31 days)
week - Week
day - Day
hr - Hour
min - Minute
ms - Milisecond
μs - Microsecond
ns - Nanosecond

Energy/Power

j - Joule
kj - Kilojoule
mj - Megajoule
cal - Calorie
Nm - Newton Meter
ftlb - Foot Pound
whr - Watt Hour
kwhr - Kilowatt Hour
mwhr - Megawatt Hour
mev - Mega Electron Volt