batrox / distance
PHP Distance (Value Object) Helper
Requires
- php: ^7.2|^8.0.2
- illuminate/support: ^6.0|^7.0|^8.0|^9.0|^10.0|^11.0
Requires (Dev)
- phpunit/phpunit: ^7.0|^8.0|^9.0|^10.0
This package is auto-updated.
Last update: 2024-11-25 08:44:38 UTC
README
## 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.