PHPackages                             arraypress/geodistance - 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. arraypress/geodistance

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

arraypress/geodistance
======================

A PHP utility class for calculating geographical distances between coordinates using the Haversine formula

00PHP

Since Feb 15Pushed 1y ago1 watchersCompare

[ Source](https://github.com/arraypress/geodistance)[ Packagist](https://packagist.org/packages/arraypress/geodistance)[ RSS](/packages/arraypress-geodistance/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

ArrayPress GeoDistance
======================

[](#arraypress-geodistance)

A powerful PHP utility class for calculating geographical distances between coordinates using the Haversine formula. This library provides a clean, intuitive interface for accurate distance calculations in both miles and kilometers, with special integration for WordPress environments.

Features
--------

[](#features)

- 🌍 **Multi-Unit Support**: Calculate distances in miles or kilometers
- 🎯 **Precision**: Results rounded to 2 decimal places for practical use
- 🛡️ **Input Validation**: Comprehensive coordinate and unit validation
- 📐 **Haversine Formula**: Accurate great-circle distance calculations
- 🔒 **Type Safety**: Full type hinting and return type declarations
- ⚡ **Simple Interface**: Easy to understand and implement
- 🔄 **WordPress Integration**: Native WP\_Error support when in WordPress environment
- 🚫 **Error Handling**: Flexible error handling for both WordPress and standalone use

Requirements
------------

[](#requirements)

- PHP 7.4 or later
- WordPress

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

[](#installation)

Install via Composer:

```
composer require arraypress/geodistance
```

Basic Usage
-----------

[](#basic-usage)

```
use ArrayPress\Utils\Math\GeoDistance;

// New York coordinates
$pointA = [ 'latitude' => 40.7128, 'longitude' => -74.0060 ];

// London coordinates
$pointB = [ 'latitude' => 51.5074, 'longitude' => -0.1278 ];

// Initialize calculator
$calculator = new GeoDistance( $pointA, $pointB );

$distance = $calculator->get_distance();
if ( is_wp_error( $distance ) ) {
    echo $distance->get_error_message();
} else {
    echo "Distance: $distance {$calculator->get_unit()}";
}
```

Point Management
----------------

[](#point-management)

### Getting Points

[](#getting-points)

```
// Get current coordinates
$pointA = $calculator->get_point_a();
$pointB = $calculator->get_point_b();
```

### Setting Points

[](#setting-points)

```
// WordPress Environment
$result = $calculator->set_point_a([
    'latitude'  => 35.6762,
    'longitude' => 139.6503
]);

if ( is_wp_error( $result ) ) {
    echo $result->get_error_message();
}
```

### Checking if a Point is Within Radius

[](#checking-if-a-point-is-within-radius)

```
// Central Park, New York
$centralPoint = [ 'latitude' => 40.7829, 'longitude' => -73.9654 ];

// Times Square coordinates
$targetPoint = [ 'latitude' => 40.7580, 'longitude' => -73.9855 ];

// Initialize calculator with central point
$calculator = new GeoDistance( $centralPoint, $targetPoint );

// WordPress Environment
$radius = 2; // 2 miles radius
$isWithin = $calculator->is_within_radius( $targetPoint, $radius );
if ( is_wp_error( $isWithin ) ) {
    echo $isWithin->get_error_message();
} else {
    echo $isWithin ? "Location is within {$radius} {$calculator->get_unit()} radius" : "Location is outside radius";
}
```

Unit Management
---------------

[](#unit-management)

### Getting and Setting Units

[](#getting-and-setting-units)

```
// Get current unit
$currentUnit = $calculator->get_unit();

// WordPress Environment
$result = $calculator->set_unit( 'km' );
if ( is_wp_error( $result ) ) {
    echo $result->get_error_message();
}
```

Error Handling
--------------

[](#error-handling)

### WordPress Environment

[](#wordpress-environment)

```
// Check for errors using WP_Error
$calculator = new GeoDistance( $pointA, $pointB );

$result = $calculator->set_unit('invalid_unit');
if ( is_wp_error( $result ) ) {
    echo $result->get_error_message();
    echo $result->get_error_code();
}

// Get the last error
$lastError = $calculator->get_last_error();
if ( $lastError instanceof WP_Error ) {
    echo $lastError->get_error_message();
}
```

Error Codes
-----------

[](#error-codes)

The library uses the following error codes when in a WordPress environment:

- `invalid_coordinates`: Missing latitude or longitude keys
- `invalid_latitude`: Latitude value out of range (-90 to 90)
- `invalid_longitude`: Longitude value out of range (-180 to 180)
- `invalid_unit`: Unsupported unit of measurement
- `calculation_error`: Error during distance calculation

Use Cases
---------

[](#use-cases)

- Distance Calculation: Calculate distances between geographical points
- Location-Based Services: Determine proximity between locations
- Travel Applications: Calculate travel distances
- Geofencing: Determine if points are within specific distances
- Delivery Services: Calculate shipping distances and zones
- WordPress Integration: Seamless integration with WordPress applications

Contributing
------------

[](#contributing)

Contributions are welcome! Please feel free to submit a Pull Request.

License
-------

[](#license)

This project is licensed under the GPL-2.0-or-later License.

Support
-------

[](#support)

- [Documentation](https://github.com/arraypress/geodistance)
- [Issue Tracker](https://github.com/arraypress/geodistance/issues)

###  Health Score

14

—

LowBetter than 2% of packages

Maintenance33

Infrequent updates — may be unmaintained

Popularity0

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity16

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% 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.

### Community

Maintainers

![](https://www.gravatar.com/avatar/cd6eb8aff0903d87eb674d1ba3c5f3653899c0d7661504eb0deb7798ed86b643?d=identicon)[arraypress](/maintainers/arraypress)

---

Top Contributors

[![arraypress](https://avatars.githubusercontent.com/u/22668877?v=4)](https://github.com/arraypress "arraypress (7 commits)")

### Embed Badge

![Health badge](/badges/arraypress-geodistance/health.svg)

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

###  Alternatives

[ryangjchandler/filament-progress-column

Add a progress bar column to your Filament tables.

68117.5k1](/packages/ryangjchandler-filament-progress-column)

PHPackages © 2026

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