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.

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.

Installation

You can pull in this package through composer

composer require teamchallengeapps/distance

The package (particularly configuration) is designed to work with Laravel 5. Include our custom service provider within config/app.php:

'providers' => [
    'TeamChallengeApps\Distance\DistanceServiceProvider'
];

Usage

To create a new distance you, simply new-up an instance of the Distance class.

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

$meters = new Distance(100);

API

Converting

You can convert a distance object to a new unit using the to methods.

$meters = new Distance(1000);

$km = $meters->toKilometers();

echo $km->value; // 1

The following methods are built-in:

• toMeters()
• toKilometers()
• toMiles()
• toFootsteps()
• toSteps() (alias)

If you just want to get the conversion, without changing the object, you can use the asUnit method.

$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.

$meters = new Distance(1000.995);

echo $meters->value; // 1000.995
echo $meters->round(); // 1001.00

Comparison

Empty / zero

$distance new Distance(0);

if ($distance->isEmpty()) {
  //
}

if ($distance->isZero()) {
  
}

Value Comparison

$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

$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.

$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

$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

Formatting

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.

$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

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:

$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 :)

Changelog

Look at the CHANGELOG.md for this package.

Author

David Rushton - Team Challenge Apps Ltd