Distance Helper 
 About
This Distance Helper package contains a tested PHP Value Object which makes working with, comparing, converting and formatting distances (meters, kilometers and steps) easy and fluent., (*1)
The inspriation for the package came from PHP helpers like Carbon, and an effort to refactor the code behind the virtual workplace walking challenge system Big Team Challenge., (*2)
Installation
You can pull in this package through composer, (*3)
composer require teamchallengeapps/distance
The package (particularly configuration) is designed to work with Laravel 5. Include our custom service provider within config/app.php:, (*4)
'providers' => [
'TeamChallengeApps\Distance\DistanceServiceProvider'
];
Usage
To create a new distance you, simply new-up an instance of the Distance class., (*5)
use TeamChallengeApps\Distance\Distance;
$meters = new Distance(100, 'meters');
$km = new Distance(10.5, 'kilometers');
$miles = new Distance(10, 'miles');
$steps = new Distance(10000, 'footsteps');
The default distance is meters, so ommitting the second (optional) constructor argument will default to meters, (*6)
$meters = new Distance(100);
API
Converting
You can convert a distance object to a new unit using the to methods., (*7)
$meters = new Distance(1000);
$km = $meters->toKilometers();
echo $km->value; // 1
The following methods are built-in:, (*8)
toMeters()toKilometers()toMiles()toFootsteps()-
toSteps() (alias)
If you just want to get the conversion, without changing the object, you can use the asUnit method., (*9)
$meters = new Distance(1000);
echo $meters->asUnit('kilometers'); // 1
echo $meters->value; // 1000
Rounding
Each unit has it's own decimal precision, and you can get the rounded format by using the round method., (*10)
$meters = new Distance(1000.995);
echo $meters->value; // 1000.995
echo $meters->round(); // 1001.00
Comparison
Empty / zero, (*11)
$distance new Distance(0);
if ($distance->isEmpty()) {
//
}
if ($distance->isZero()) {
}
Value Comparison, (*12)
$distance = new Distance(10);
$total = new Distance(100);
if ($distance->lt($total)) {
// Less than
}
if ($distance->lte($total)) {
// Less than or equal
}
if ($distance->gt($total)) {
// Greater than
}
if ($distance->gte($total)) {
// Greater than or equal
}
Percentage Of, (*13)
$distance = new Distance(10);
$total = new Distance(100);
$percentage = $distance->percentageOf($total); // 10
By default, the percentage is capped at 100, but passing false as the second parameter will always return the real percentage., (*14)
$distance = new Distance(150);
$total = new Distance(100);
$percentage = $distance->percentageOf($total); // 100
$percentage = $distance->percentageOf($total, false); // 150
Modifying
You can add or subtract distances, (*15)
$total = new Distance(1000);
$logged = new Distance(10);
$total->increment($logged);
echo $total->value; // 1010
$total = new Distance(1010);
$redeemed = new Distance(10);
$total->decrement($logged);
echo $total->value; // 1000
Using PHP's magic __toString() method, echo-ing or casting the object itself will round and use the number_format function to return a string-representation of the value., (*16)
$distance = new Distance(100500.591);
echo $distance; // 10,500.59
$value = (string) $distance;
echo $value; // 10,500.59
You can change the default formatting options to include/omit the comma and the unit suffix. Publish the config file using, (*17)
php artisan vendor:publish --provider="TeamChallengeApps\Distance\DistanceServiceProvider" --tag="config"
return [
'format' => [
'comma' => true,
'suffix' => false,
];
];
You can also use the toStringWithSuffix method to force the suffix on the end, for example:, (*18)
$meters = new Distance(100, 'meters');
echo $meters->toStringWithSuffix(); // 1000 m
$km = new Distance(10.5, 'kilometers');
echo $km->toStringWithSuffix(); // 1000 km
$miles = new Distance(10, 'miles');
echo $miles->toStringWithSuffix(); // 1000 mi.
$steps = new Distance(10000, 'footsteps');
echo $steps->toStringWithSuffix(); // 1000 steps
Contributing
Please submit improvements and fixes :), (*19)
Changelog
Look at the CHANGELOG.md for this package., (*20)
Author
David Rushton - Team Challenge Apps Ltd, (*21)
Wallogit.com
