unicorn Documentation
Release 1.0.0
Philipp Bräutigam, Steffen Brand
February 23, 2017
Contents
1
User Guide
1.1 Requirements . . . . . . . . . . . .
1.2 Installation . . . . . . . . . . . . .
1.3 ConvertibleValue and Unit . . . . .
1.3.1
Unit . . . . . . . . . . . .
1.3.2
ConvertibleValue . . . . .
1.4 Converters . . . . . . . . . . . . .
1.4.1
Converting . . . . . . . .
1.4.2
Mathematical operations .
1.4.3
Nesting . . . . . . . . . .
1.4.4
Adding your own units . .
1.4.5
Extending converters . . .
1.4.6
Converter Registry . . . .
1.4.7
Converter Implementations
1.5 Contribute . . . . . . . . . . . . .
1.6 License . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
3
3
3
3
3
4
4
4
5
5
6
6
8
9
14
15
i
ii
unicorn Documentation, Release 1.0.0
A framework agnostic library to convert between several units.
Contents
1
unicorn Documentation, Release 1.0.0
2
Contents
CHAPTER 1
User Guide
Requirements
• PHP 7.0 or higher
• BCMath extension installed and enabled
Installation
The recommended way to install Unicorn is using Composer. Run the following command in your project directory:
composer require xynnn/unicorn
This requires you to have Composer installed globally, as explained in the installation chapter of the Composer documentation.
ConvertibleValue and Unit
This section will provide you general information on Unit and how to use the ConvertibleValue, which is
unicorns general data transfer object.
Unit
It consists of three properties:
• name: the full name of the unit, f.e. centimeter
• abbreviation: the abbreviation of the unit, f.e cm
• factor: the factor to normalize this unit to the converters base unit
It is important to understand how the factor is used in the internal process. Especially, if you want to add your own
units to a converter. The factor is used to normalize a value or convert a value.
Let’s say you want to normalize 1 kilometer to meter, as meter is the base unit of the LengthConverter. The
1 meter is 0.001 kilometer, so the factor of the unit kilometer is 0.001. This example is taken directly from the
LengthConverter constructor, where the Unit kilometer is already set up.
3
unicorn Documentation, Release 1.0.0
<?php
new Unit('kilometer', 'km', '0.001');
All converters already provide a number of units ready to use as static variables. Have a look at the corresponding
converters documentation to see which units are already provided.
<?php
$converter = new LengthConverter();
$converter::$kilometer; // the unit "meter" already set up and ready to use
ConvertibleValue
A ConvertibleValue is the general data transfer object of Unicorn. Before you start converting or performing
mathematical operations, you have to wrap your data in a ConvertibleValue.
It consists of two properties:
• value: the actual value
• unit: the unit in which the value is represented
If you want to represent 1000 meters as a ConvertibleValue, it will look like this:
<?php
$converter = new LengthConverter();
new ConvertibleValue('1000', $converter::$meter);
The value is supposed to be a string representation, since it allows endless decimals, while float is limited to 14
decimals. Since php loves type juggling and is able to cast almost anything to string, you might use int or float as well.
<?php
$converter = new LengthConverter();
new ConvertibleValue(1000.12345678901234, $converter::$meter);
Converters
This section will provide you general information on how to use converters.
Converting
To convert a ConvertibleValue to another Unit, you have to call the convert method. The method works as
follows: convert X of Unit Y to Unit Z. The convert method returns a ConvertibleValue, that you can use for
further operations. Let’s have a look at the convert methods signature:
<?php
/**
* @param ConvertibleValue $from
* @param Unit $to
* @return ConvertibleValue
*/
public function convert(ConvertibleValue $from, Unit $to): ConvertibleValue;
Here is a quick example that shows how to convert 110 centimeters to meters:
4
Chapter 1. User Guide
unicorn Documentation, Release 1.0.0
<?php
$converter = new LengthConverter();
$result = $converter->convert(new ConvertibleValue('110', $converter::$centimeter), $converter::$mete
$result->getValue(); // '1.10...' with 999 decimals
$result->getFloatValue(); // 1.1
$result->getUnit()->getAbbreviation(); // 'm'
$result->getUnit()->getName(); // 'meter'
Mathematical operations
Most converters extend the AbstractMathematicalConverter, which provides some basic mathematical operations. These are examples for adding and subtracting values, even if they are provided in different units. Mathematical operations keep the Unit of the first ConvertibleValue.
<?php
$converter = new LengthConverter();
// addition
$resultAdd = $converter->add(
new ConvertibleValue('1', $converter::$meter),
new ConvertibleValue('200', $converter::$centimeter)
);
$resultAdd->getValue(); // '3.0' with 999 decimals
$resultAdd->getFloatValue(); // 3
$resultAdd->getUnit()->getAbbreviation(); // 'm'
$resultAdd->getUnit()->getName(); // 'meter'
// subtraction
$resultSub = $converter->sub(
new ConvertibleValue('500', $converter::$centimeter),
new ConvertibleValue('3', $converter::$meter)
);
$resultSub->getValue(); // '800.0' with 999 decimals
$resultSub->getFloatValue(); // 800
$resultSub->getUnit()->getAbbreviation(); // 'cm'
$resultSub->getUnit()->getName(); // 'centimeter'
Nesting
Feel free to nest mathematical operations and conversions as you like, as they all work on ConvertibleValue,
which is the return type of all operations.
<?php
$converter = new LengthConverter();
try {
$result = $converter->convert(
$converter->add(
$converter->add(
new ConvertibleValue('10000', $converter::$nanometer),
new ConvertibleValue('10', $converter::$micrometer)
1.4. Converters
5
unicorn Documentation, Release 1.0.0
),
new ConvertibleValue('30000', $converter::$nanometer)
),
$converter::$micrometer
);
} catch (UnsupportedUnitException $e) {
// Unit might not be present in the converters units array
} catch (InvalidArgumentException $e) {
// Something is wrong with the provided ConvertibleValue or Unit
}
Adding your own units
All converters already provide a lot of units that you can use for conversions. However, if you are missing a Unit,
you can add it to the converter and start using it. To add a Unit to the converter, just use the addUnit or setUnits
method. Make sure to read about Unit_, before you start adding your own units.
<?php
$converter = new LengthConverter();
$myUnit = new Unit('myUnit', 'mu', '5');
$converter->addUnit($myUnit);
try {
$result = $converter->convert(new ConvertibleValue('1', $converter::$meter), $myUnit);
$result->getValue(); // '5.0' with 999 decimals
$result->getFloatValue(); // 5
$result->getUnit()->getAbbreviation(); // 'mu'
$result->getUnit()->getName(); // 'myUnit'
} catch (UnsupportedUnitException $e) {
// Unit might not be present in the converters units array
} catch (InvalidArgumentException $e) {
// Something is wrong with the provided ConvertibleValue or Unit
}
Note: Not all converters are factor-based converters. Some converters, like the TemperatureConverter, convert based
on formulas, so they don’t provide a addUnit oder setUnits method. If you want to add your own units, you need
to extend the converter. See Extending converters for further information.
Extending converters
Not all converters are factor-based converters. Some converters, like the TemperatureConverter, convert based on
formulas, so they don’t provide a addUnit oder setUnits method. If you want to add your own units, you need
to extend the converter.
This example shows you how to extend the TemperatureConverter and how you add your own unit myUnit.
The steps are:
• Extend the TemperatureConverter
• Add your own Unit as static member variable myUnit
• Call the parent constructor and afterwards initialize your own unit myUnit and add it to the units array.
• Override the getName method and return your own name mytemperature
6
Chapter 1. User Guide
unicorn Documentation, Release 1.0.0
• Override the normalize method and add a case for your own unit myUnit
• Override the convertTo method and add a case for your own unit myUnit
<?php
namespace Xynnn\Unicorn\Converter;
use Xynnn\Unicorn\Model\Unit;
use Xynnn\Unicorn\Model\ConvertibleValue;
class MyOwnTemperatureConverter extends TemperatureConverter
{
/**
* @var Unit $myUnit Static instance for conversions
*/
public static $myUnit;
/**
* LengthConverter constructor.
*/
public function __construct()
{
parent::__construct();
$this->units[] = self::$myUnit = new Unit('MyUnit ', 'mu');
}
/**
* @return string Name of the converter
*/
public function getName(): string
{
return 'unicorn.converter.mytemperature';
}
/**
* @param ConvertibleValue $cv The Convertible to be normalized
*/
protected function normalize(ConvertibleValue $cv)
{
switch ($cv->getUnit()) {
case self::$fahrenheit:
$value = bcdiv(bcmul(bcsub($cv->getValue(), '32', self::MAX_DECIMALS), '5', self::MAX
break;
case self::$kelvin:
$value = bcsub($cv->getValue(), '273.15', self::MAX_DECIMALS);
break;
case self::$myUnit:
$value = 1 * 1; // add your own formula
break;
default:
$value = $cv->getValue();
}
1.4. Converters
7
unicorn Documentation, Release 1.0.0
$cv->setValue($value);
$cv->setUnit($this->getBaseUnit());
}
/**
* @param ConvertibleValue $from The convertible to be converted
Unit to which is to be converted
* @param Unit $to
*/
protected function convertTo(ConvertibleValue $from, Unit $to)
{
switch ($to) {
case self::$fahrenheit:
$value = bcadd(bcdiv(bcmul($from->getValue(), '9', self::MAX_DECIMALS), '5', self::MA
break;
case self::$kelvin:
$value = bcadd($from->getValue(), '273.15', self::MAX_DECIMALS);
break;
case self::$myUnit:
$value = 1 * 1; // add your own formula
break;
default:
$value = $from->getValue();
}
$from->setValue($value);
$from->setUnit($to);
}
}
Note: If you’re using a factor-based converter, normally there is no reason to extend a converter. Better use the
addUnit oder setUnits methods instead. See Adding your own units for further information.
Converter Registry
If you need to use more than one converter in your project, but you don’t want to inject every single converter, you can
add a set of converters to the ConverterRegistry and inject the registry instead.
The ConverterRegistry can be instantiated with an array of converters:
<?php
$registry = new ConverterRegistry([
new LengthConverter(),
new CurrencyConverter(),
new TemperatureConverter(),
new DataStorageConverter(),
new DataTransferConverter()
]);
You can also add converters using the add method:
8
Chapter 1. User Guide
unicorn Documentation, Release 1.0.0
<?php
$registry = new ConverterRegistry();
$registry->add(new LengthConverter());
To get a converter instance from the ConverterRegistry, use the get method with the name of the converter:
<?php
$registry = new ConverterRegistry([
new LengthConverter(),
new CurrencyConverter()
]);
try {
$lengthConverter = $registry->get('unicorn.converter.length');
} catch (UnsupportedConverterException $e) {
// converter might not be present
}
Converter Implementations
LengthConverter
Use the LengthConverter to convert between different length units, f.e. from meters to miles.
Name
unicorn.converter.length
Base Unit
• meter
Features
• Conversion
• Mathematical operations
• Adding own units
1.4. Converters
9
unicorn Documentation, Release 1.0.0
Predefined Units
Name
nanometer
micrometer
millimeter
centimeter
decimeter
meter
kilometer
inch
feet
yard
mile
Abbreviation
nm
µm
mm
cm
dm
m
km
in
ft
yd
m
Factor
1000000000
1000000
1000
100
10
1
0.001
1/0.0254
1/0.3048
1/0.9144
1/1609.344
CurrencyConverter
Use the CurrencyConverter to convert between different currencies, f.e. from EUR to USD.
Note: This converter loads the current exchange rates from the ECB via Webservice once you start converting or
calculating. For more information check out https://github.com/steffenbrand/curr-curr
Name
unicorn.converter.currency
Base Unit
• EUR
Features
• Conversion
• Mathematical operations
• Adding own units
Predefined Units
Name
EUR
USD
JPY
BGN
CZK
10
Abbreviation
C
$
¥
Kč
Factor
1
dynamic
dynamic
dynamic
dynamic
Continued on next page
Chapter 1. User Guide
unicorn Documentation, Release 1.0.0
Table 1.1 – continued from previous page
Name
Abbreviation
Factor
DKK
kr
dynamic
GBP
£
dynamic
HUF
Ft
dynamic
PLN
zł
dynamic
RON
lei
dynamic
SEK
kr
dynamic
CHF
CHF
dynamic
NOK
kr
dynamic
HRK
kn
dynamic
RUB
dynamic
TRY
dynamic
AUD
$
dynamic
BRL
R$
dynamic
CAD
$
dynamic
CNY
¥
dynamic
HKD
$
dynamic
IDR
Rp
dynamic
ILS
dynamic
INR
dynamic
KRW
dynamic
MXN
$
dynamic
MYR
RM
dynamic
NZD
$
dynamic
PHP
dynamic
SGD
$
dynamic
THB
dynamic
ZAR
R
dynamic
Note: Blank currency abbreviations do exist in the converter, but readthedocs is not able to parse them.
TemperatureConverter
Use the TemperatureConverter to convert between different temperature units, f.e. from Celsius to Kelvin.
Name
unicorn.converter.temperature
Base Unit
• Celsius
Features
• Conversion
1.4. Converters
11
unicorn Documentation, Release 1.0.0
• Mathematical operations
Predefined Units
Name
Celsius
Fahrenheit
Kelvin
Abbreviation
°C
°F
K
Factor
formula
formula
formula
DataStorageConverter
Use the DataStorageConverter to convert between different temperature units, f.e. from Megabyte to Gigabyte.
Name
unicorn.converter.datastorage
Base Unit
• Megabyte
Features
• Conversion
• Mathematical operations
• Adding own units
Predefined Units
Name
Byte
Kilobyte
Megabyte
Gigabyte
Terabyte
Petabyte
Exabyte
Zettabyte
Yottabyte
12
Abbreviation
B
KB
MB
GB
TB
PB
EB
ZB
YB
Factor
1000000
1000
1
0.001
0.000001
0.000000001
0.000000000001
0.000000000000001
0.000000000000000001
Chapter 1. User Guide
unicorn Documentation, Release 1.0.0
Name
Kibibyte
Mebibyte
Gibibyte
Tebibyte
Pebibyte
Exibyte
Zebibyte
Yobibyte
Abbreviation
KiB
MiB
GiB
TiB
PiB
EiB
ZiB
YiB
Factor
976.5625
KiB-Factor/1024
MiB-Factor/1024
GiB-Factor/1024
TiB-Factor/1024
PiB-Factor/1024
EiB-Factor/1024
ZiB-Factor/1024
Name
Bit
Kilobit
Megabit
Gigabit
Terabit
Petabit
Exabit
Zettabit
Yottabit
Abbreviation
bit
Kbit
Mbit
Gbit
Tbit
Pbit
Ebit
Zbit
Ybit
Factor
8000000
8000
8
0.008
0.000008
0.000000008
0.000000000008
0.000000000000008
0.000000000000000008
Name
Kibibit
Mebibit
Gibibit
Tebibit
Pebibit
Exibit
Zebibit
Yobibit
Abbreviation
Kibit
Mibit
Gibit
Tibit
Pibit
Eibit
Zibit
Yibit
Factor
7812.5
Kibit-Factor/1024
Mibit-Factor/1024
Gibit-Factor/1024
Tibit-Factor/1024
Pibit-Factor/1024
Eibit-Factor/1024
Zibit-Factor/1024
DataTransferConverter
Use the DataTransferConverter to convert between different temperature units, f.e. from Megabyte to Gigabyte.
Name
unicorn.converter.datatransfer
Base Unit
• Megabit per second
Features
• Conversion
• Mathematical operations
• Adding own units
1.4. Converters
13
unicorn Documentation, Release 1.0.0
Predefined Units
Name
Bit per second
Kilobit per second
Megabit per second
Gigabit per second
Terabit per second
Petabit per second
Exabit per second
Zettabit per second
Yottabit per second
Abbreviation
bit/s
Kbit/s
Mbit/s
Gbit/s
Tbit/s
Pbit/s
Ebit/s
Zbit/s
Ybit/s
Factor
1000000
1000
1
0.001
0.000001
0.000000001
0.000000000001
0.000000000000001
0.000000000000000001
Name
Kibibit per second
Mebibit per second
Gibibit per second
Tebibit per second
Pebibit per second
Exibit per second
Zebibit per second
Yobibit per second
Abbreviation
Kibit/s
Mibit/s
Gibit/s
Tibit/s
Pibit/s
Eibit/s
Zibit/s
Yibit/s
Factor
7812.5
Kibit/s-Factor/1024
Mibit/s-Factor/1024
Gibit/s-Factor/1024
Tibit/s-Factor/1024
Pibit/s-Factor/1024
Eibit/s-Factor/1024
Zibit/s-Factor/1024
Name
Byte per second
Kilobyte per second
Megabyte per second
Gigabyte per second
Terabyte per second
Petabyte per second
Exabyte per second
Zettabyte per second
Yottabyte per second
Abbreviation
B/s
KB/s
MB/s
GB/s
TB/s
PB/s
EB/s
ZB/s
YB/s
Factor
125000
125
0.125
0.000125
0.000000125
0.000000000125
0.000000000000125
0.000000000000000125
0.000000000000000000125
Name
Kibibyte per second
Mebibyte per second
Gibibyte per second
Tebibyte per second
Pebibyte per second
Exibyte per second
Zebibyte per second
Yobibyte per second
Abbreviation
KiB/s
MiB/s
GiB/s
TiB/s
PiB/s
EiB/s
ZiB/s
YiB/s
Factor
122.07031296
KiB/s-Factor/1024
MiB/s-Factor/1024
GiB/s-Factor/1024
TiB/s-Factor/1024
PiB/s-Factor/1024
EiB/s-Factor/1024
ZiB/s-Factor/1024
Contribute
• Issue Tracker: https://github.com/xyNNN/unicorn/issues
• Source Code: https://github.com/xyNNN/unicorn
14
Chapter 1. User Guide
unicorn Documentation, Release 1.0.0
License
Unicorn is released under the GNU LGPL v3.0 license. Read it here: LICENSE
1.6. License
15