alkauni/distance-coordinate-calculator

A Package to calculate the distance between two coordinate points

1.0.0 2024-07-26 15:07 UTC

Requires

• php: >=7.4
• illuminate/support: ^8.0

Requires (Dev)

• phpunit/phpunit: ^9.0

MIT

• hanifalkauni

• distance
• coordinates
• calculator

Published on Packagist.org on 2024-07-26 15:13 UTC

README

A feature-rich PHP & Laravel package to calculate geographical distance, check radius bounds, find nearest locations, and sort coordinate lists using the Haversine formula.

Features

• 📍 Calculate distance between two GPS coordinates (Latitude & Longitude).
• 📏 Multiple unit support: Kilometers (KM), Miles, Nautical Miles (N), and Meters (M).
• 🎯 Check if coordinates are within a specific radius (isWithinRadius).
• 🔎 Find the nearest location item from a list (findNearest).
• 📊 Sort location lists by distance (sortByDistance).
• 🏷️ Formatted output string with unit suffix (calculateFormatted).
• 🛡️ Latitude & Longitude validity checking (isValidCoordinate).
• ⚡ Laravel Package Auto-Discovery supported out of the box with Facade (Distance).

Installation

You can install the package via composer:

composer require alkauni/distance-coordinate-calculator

Laravel Auto-Discovery

If you are using Laravel 8+, the Service Provider and Facade will be registered automatically via Package Auto-Discovery.

(Optional) Publish the configuration file:

php artisan vendor:publish --provider="Alkauni\DistanceCoordinateCalculator\DistanceServiceProvider" --tag="config"

This will publish distance.php to your config/ directory:

return [
    'default_unit' => 'KM', // Options: 'KM', 'Miles', 'N', 'M'
];

Usage

1. Basic Distance Calculation

use Alkauni\DistanceCoordinateCalculator\Facades\Distance; // Or DistanceCalculator class

// Calculate distance in Kilometers
$distance = Distance::calculate(-6.200000, 106.816666, -6.917464, 107.619123);
// Output: ~118.44 (KM)

// Specify unit ('Miles', 'KM', 'M', 'N')
$miles = Distance::calculate(40.748817, -73.985428, 34.052235, -118.243683, 'Miles');

2. Formatted Distance Output

Get a formatted string with rounded decimals and unit label:

$formatted = Distance::calculateFormatted(-6.200000, 106.816666, -6.917464, 107.619123, 'KM', 2);
// Output: "118.44 KM"

3. Geofencing / Radius Check (isWithinRadius)

Check if a target location is within a given distance radius (e.g. for GPS attendance or delivery range):

$userLat = -6.200000;
$userLon = 106.816666;

$officeLat = -6.205000;
$officeLon = 106.818000;

$isAllowed = Distance::isWithinRadius($userLat, $userLon, $officeLat, $officeLon, 1.0, 'KM');
// Returns: true (user is within 1 KM radius of the office)

4. Find Nearest Location (findNearest)

Find the closest branch/store from an array of locations:

$userLat = -6.200000;
$userLon = 106.816666; // Jakarta

$branches = [
    ['name' => 'Surabaya Branch', 'lat' => -7.257472, 'lon' => 112.752088],
    ['name' => 'Bandung Branch', 'lat' => -6.917464, 'lon' => 107.619123],
    ['name' => 'Medan Branch', 'lat' => 3.595196, 'lon' => 98.672223],
];

$nearest = Distance::findNearest($userLat, $userLon, $branches);
// Returns: ['name' => 'Bandung Branch', 'lat' => -6.917464, 'lon' => 107.619123, 'distance' => 118.44]

5. Sort Locations by Distance (sortByDistance)

Sort an array or collection of location items by distance:

$sortedBranches = Distance::sortByDistance($userLat, $userLon, $branches, 'lat', 'lon', 'KM', 'asc');
// Returns array ordered from nearest to farthest, each item tagged with calculated 'distance'.

6. Validate Coordinates (isValidCoordinate)

Check if coordinates are within valid geographic latitude (-90 to 90) and longitude (-180 to 180):

$isValid = Distance::isValidCoordinate(-6.200000, 106.816666); // true
$isInvalid = Distance::isValidCoordinate(95.0, 200.0); // false

Supported Units

Unit Code	Description
KM	Kilometers (Default)
Miles	Miles
N	Nautical Miles
M	Meters

Testing

Run tests using PHPUnit:

vendor/bin/phpunit

License

The MIT License (MIT). Please see License File for more information.