README

A comprehensive Laravel utility package for geographic operations, including polygon point checks, distance calculations, and spatial data manipulation. This package provides both pure PHP implementations and MySQL spatial function integration.

Features

• 🎯 Point-in-Polygon Detection: Ray-casting algorithm implementation
• 🚀 Optimized Performance: Bounding box pre-filtering for faster checks
• 🗄️ MySQL Spatial Support: Leverage MySQL's built-in spatial functions
• 📏 Distance Calculations: Haversine formula for accurate distance measurement
• 🔄 WKT Conversion: Convert between array and Well-Known Text formats
• ⚡ Laravel Integration: Service provider, facade, and Artisan commands
• 🧪 Comprehensive Testing: Full test coverage with PHPUnit
• 🛠️ CLI Tools: Command-line testing and validation tools

Installation

Install the package via Composer:

composer require opensource-labs-gh/laravel-geo-utils

The package will automatically register its service provider and facade.

Publishing Configuration

Optionally, you can publish the configuration file:

php artisan vendor:publish --provider="OpensourceLabsGh\GeoUtils\GeoServiceProvider" --tag="geo-utils-config"

Usage

Basic Point-in-Polygon Check

use OpensourceLabsGh\GeoUtils\GeoHelper;
// Or use the facade
use OpensourceLabsGh\GeoUtils\Facades\GeoHelper;

$polygon = [
    ['lat' => 5.6037, 'lng' => -0.1870],
    ['lat' => 5.6037, 'lng' => -0.1700],
    ['lat' => 5.5800, 'lng' => -0.1700],
    ['lat' => 5.5800, 'lng' => -0.1870],
];

$point = ['lat' => 5.5919, 'lng' => -0.1785];

$isInside = GeoHelper::isPointInPolygon($polygon, $point);
// Returns: true

Optimized Point-in-Polygon Check

For better performance with large polygons, use the optimized version that includes bounding box pre-filtering:

$isInside = GeoHelper::isPointInPolygonOptimized($polygon, $point);

MySQL Spatial Functions

Use MySQL's built-in spatial functions for potentially better performance:

$polygonWkt = GeoHelper::arrayToWktPolygon($polygon);
$isInside = GeoHelper::isPointInPolygonMySQL($polygonWkt, 5.5919, -0.1785);

Distance Calculations

Calculate distances between two points using the Haversine formula:

$point1 = ['lat' => 37.7749, 'lng' => -122.4194]; // San Francisco
$point2 = ['lat' => 40.7128, 'lng' => -74.0060];  // New York

$distanceKm = GeoHelper::calculateDistance($point1, $point2, 'km');
$distanceMiles = GeoHelper::calculateDistance($point1, $point2, 'miles');
$distanceMeters = GeoHelper::calculateDistance($point1, $point2, 'meters');

// Results:
// $distanceKm ≈ 4135.46
// $distanceMiles ≈ 2569.46
// $distanceMeters ≈ 4135458.97

Bounding Box Operations

Get the bounding box of a polygon:

$boundingBox = GeoHelper::getBoundingBox($polygon);
// Returns:
// [
//     'min_lat' => 5.5800,
//     'max_lat' => 5.6037,
//     'min_lng' => -0.1870,
//     'max_lng' => -0.1700
// ]

// Quick check if point is within bounding box
$isInBounds = GeoHelper::isPointInBoundingBox($boundingBox, $point);

WKT Conversion

Convert array coordinates to Well-Known Text format:

$wktPolygon = GeoHelper::arrayToWktPolygon($polygon);
// Returns: "POLYGON((-0.187000 5.603700, -0.170000 5.603700, -0.170000 5.580000, -0.187000 5.580000, -0.187000 5.603700))"

Artisan Commands

The package includes a command-line tool for testing and validation:

Basic Point-in-Polygon Test

php artisan geo-utils:test

Custom Polygon and Point Test

php artisan geo-utils:test \
  --polygon='[{"lat":5.6037,"lng":-0.1870},{"lat":5.6037,"lng":-0.1700},{"lat":5.5800,"lng":-0.1700},{"lat":5.5800,"lng":-0.1870}]' \
  --point='{"lat":5.5919,"lng":-0.1785}'

Distance Calculation Test

php artisan geo-utils:test --distance

Bounding Box Test

php artisan geo-utils:test --bbox

Configuration

The package includes a configuration file with the following options:

return [
    'default_distance_unit' => 'km',
    'mysql_spatial_enabled' => true,
    'coordinate_precision' => 6,
    'validation' => [
        'strict_coordinates' => true,
        'min_polygon_points' => 3,
    ],
    'performance' => [
        'use_bounding_box_optimization' => true,
        'cache_bounding_boxes' => false,
    ],
];

API Reference

GeoHelper Methods

Data Formats

Point Format:

['lat' => float, 'lng' => float]

Polygon Format:

[
    ['lat' => float, 'lng' => float],
    ['lat' => float, 'lng' => float],
    ['lat' => float, 'lng' => float],
    // ... minimum 3 points required
]

Bounding Box Format:

[
    'min_lat' => float,
    'max_lat' => float,
    'min_lng' => float,
    'max_lng' => float
]

Performance Considerations

1. Bounding Box Optimization: For large polygons, use isPointInPolygonOptimized() which performs a quick bounding box check before the full polygon test.

2. MySQL Spatial Functions: When working with large datasets, consider using isPointInPolygonMySQL() which leverages MySQL's optimized spatial functions.

3. Coordinate Precision: Adjust coordinate_precision in config based on your needs - higher precision means more accuracy but potentially slower performance.

Error Handling

The package validates input data and throws InvalidArgumentException for:

• Polygons with fewer than 3 points
• Invalid coordinate values (latitude not between -90 and 90, longitude not between -180 and 180)
• Missing required array keys ('lat', 'lng')
• Invalid distance units
• Empty WKT strings

Testing

Run the package tests:

composer test

Or run tests with coverage:

composer test-coverage

Contributing

Please see CONTRIBUTING.md for details on how to contribute to this project.

Security

If you discover any security related issues, please email mawulikofiagbenyo@gmail.com instead of using the issue tracker.

Credits

• Mawuli Agbenyo
• All Contributors

License

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

Changelog

Please see CHANGELOG.md for more information about recent changes.

Support

• 📧 Email: mawulikofiagbenyo@gmail.com
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

Made with ❤️ by Opensource Labs Ghana