Download the PHP package frostybee/geobee without Composer
On this page you can find all versions of the php package frostybee/geobee. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download frostybee/geobee
More information about frostybee/geobee
Files in frostybee/geobee
Package geobee
Short Description A simple, stand-alone PHP library for calculating the distance between geographical coordinates.
License MIT
Homepage https://github.com/frostybee/geobee
Informations about the package geobee
Geobee
A standalone PHP library for calculating the great-circle distance between geographical coordinates using a spherical Earth model.
Installation
This library requires no dependencies.
To install it:
- Clone this repository.
- Or use composer:
composer require frostybee/geobee
Units of Lengths
The following are the supported units of lengths along with their respective conversion factors:
m- Meters (default, base unit)km- Kilometers (1km = 1000 meters)mi- Miles (1mi = 1609.344 meters)nm- Nautical miles (1nm = 1852 meters)yd- Yards (1yd = 0.9144 meters)ft- Feet (1ft = 0.3048 meters)
Note: Unit symbols are case-insensitive (e.g., 'km', 'KM', 'Km' all work).
Usage
Using this library is simple and straightforward. Just instantiate the Calculator class and supply two pairs of latitude/longitude to the calculate() method as shown below.
Converting the Distance from Meters to other Units
Single Conversion
Use the to() method as show below. However, you must call the calculate() method once before doing any conversions.
You can also specify precision and rounding behavior:
Parameters for to() method:
$unit(string, required): Unit symbol for conversion$decimals(int|null, optional): Number of decimal places (1-9), null for no rounding$round(bool, optional, default=true): true = standard rounding, false = floor rounding
Batch Conversions
Convert the distance to multiple units efficiently:
Coordinate Validation
The library provides a public method to validate latitude/longitude coordinates before performing calculations.
Using isCoordinate() Method
Coordinate Requirements
- Latitude: Must be between -90 and +90 (decimal degrees)
- Longitude: Must be between -180 and +180 (decimal degrees)
- Both values can have up to 6 decimal places
- Optional +/- sign is allowed
- Arrays are not accepted as coordinate values
Validation Examples
Error Handling
The library throws exceptions for invalid input:
InvalidCoordinateFormatException: When coordinates fail validationInvalidUnitException: When an invalid or unsupported unit is specified
Advanced Usage
Method Chaining
The calculate() method returns the Calculator instance, enabling fluent method chaining:
Edge Cases
Zero Distance (Same Coordinates)
When calculating distance from a point to itself:
Note: toAll() returns an empty array when distance is zero, while to() returns 0.
Precision Control
Control the precision of converted distances:
API Reference
Calculator Class Methods
| Method | Parameters | Return Type | Description |
|---|---|---|---|
calculate() |
float $from_lat, float $from_lon, float $to_lat, float $to_lon |
self |
Calculates distance between two coordinates. Returns $this for chaining. |
getDistance() |
None | float |
Returns the calculated distance in meters. |
to() |
string $unit, ?int $decimals = null, bool $round = true |
float\|int |
Converts distance to specified unit. |
toMany() |
array $units = [], ?int $decimals = null, bool $round = true |
array |
Converts distance to multiple units. Returns associative array. |
toAll() |
?int $decimals = null, bool $round = true |
array |
Converts distance to all supported units. Returns associative array. |
isCoordinate() |
mixed $latitude, mixed $longitude |
bool |
Validates a coordinate pair. Returns true if valid. |
Implementation Details
- Algorithm: Great-circle distance using spherical Earth model (numerically stable implementation with
atan2()) - Earth Radius: 6,378,137 meters (WGS84 semi-major axis)
- Coordinate Format: Decimal degrees with up to 6 decimal places
- Precision: Suitable for most geographic distance calculations; for higher precision on an ellipsoidal model, consider using a full geodesic library
License
Geobee is an open-source library licensed under the MIT LICENSE.