PHPackages                             batrox/distance - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. batrox/distance

ActiveLibrary[Utility & Helpers](/categories/utility)

batrox/distance
===============

PHP Distance (Value Object) Helper

v1.0.0(1y ago)034MITPHPPHP ^7.2|^8.0.2

Since Oct 25Pushed 1y agoCompare

[ Source](https://github.com/batrox/distance)[ Packagist](https://packagist.org/packages/batrox/distance)[ RSS](/packages/batrox-distance/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (2)Versions (2)Used By (0)

Distance Helper [![Build Status](https://camo.githubusercontent.com/dc621dfad8f97177a98317831f29403ebcb0bf2c59cd9db0a80f57b42210828a/68747470733a2f2f7472617669732d63692e6f72672f7465616d6368616c6c656e6765617070732f64697374616e63652e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/teamchallengeapps/distance)
=============================================================================================================================================================================================================================================================================================================================

[](#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](http://carbon.nesbot.com/), and an effort to refactor the code behind the virtual workplace walking challenge system [Big Team Challenge](https://bigteamchallenge.com).

Installation
------------

[](#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
-----

[](#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
---

[](#api)

### Converting

[](#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

[](#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

[](#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

[](#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

[](#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
------------

[](#contributing)

Please submit improvements and fixes :)

Changelog
---------

[](#changelog)

Look at the **[CHANGELOG.md](https://github.com/teamchallengeapps/distance/blob/master/CHANGELOG.md)** for this package.

Author
------

[](#author)

[David Rushton](https://github.com/davidrushton) - [Team Challenge Apps Ltd](https://bigteamchallenge.com)

###  Health Score

26

—

LowBetter than 43% of packages

Maintenance37

Infrequent updates — may be unmaintained

Popularity7

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 95.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

571d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/600ddb056d99d542b6cecb23d556a00117b3f9156d1f1f3fd239aaa4df5e5ce7?d=identicon)[batrox](/maintainers/batrox)

---

Top Contributors

[![davidrushton](https://avatars.githubusercontent.com/u/4039772?v=4)](https://github.com/davidrushton "davidrushton (22 commits)")[![batrox](https://avatars.githubusercontent.com/u/7557661?v=4)](https://github.com/batrox "batrox (1 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/batrox-distance/health.svg)

```
[![Health](https://phpackages.com/badges/batrox-distance/health.svg)](https://phpackages.com/packages/batrox-distance)
```

###  Alternatives

[barryvdh/laravel-ide-helper

Laravel IDE Helper, generates correct PHPDocs for all Facade classes, to improve auto-completion.

14.9k123.0M687](/packages/barryvdh-laravel-ide-helper)[orchestra/canvas

Code Generators for Laravel Applications and Packages

20917.2M158](/packages/orchestra-canvas)[illuminate/pipeline

The Illuminate Pipeline package.

9346.6M213](/packages/illuminate-pipeline)[illuminate/pagination

The Illuminate Pagination package.

10532.5M862](/packages/illuminate-pagination)[spatie/laravel-pjax

A pjax middleware for Laravel 5

513371.8k11](/packages/spatie-laravel-pjax)[spatie/laravel-mix-preload

Add preload and prefetch links based your Mix manifest

169176.0k2](/packages/spatie-laravel-mix-preload)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)