Download the PHP package gowelle/laravel-route-matrix without Composer

Laravel Route Matrix

A Laravel wrapper for the Google Routes API with support for route calculation, distance matrices, and waypoint optimization.

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Usage
  • Basic Route Calculation
  • Travel Modes
  • Traffic-Aware Routing
  • Route Modifiers
  • Alternative Routes
  • Waypoint Optimization
• Route Matrix
  • One to Many
  • Many to One
  • Many to Many
  • Courier Example
• Response Objects
• Eloquent Integration
• Configuration
• Exception Handling
• Testing
• License

Features

• 🚗 Multiple Travel Modes - Driving, walking, bicycling, two-wheeler, transit
• 🚦 Traffic-Aware Routing - Real-time and historical traffic data
• 📍 Flexible Waypoints - Coordinates, Place IDs, or addresses
• 📊 Distance Matrix - Calculate N×M origin-destination pairs
• 🎯 Find Closest - Get closest/fastest destination helpers
• ⚡ Fluent API - Elegant, chainable method calls
• 🧪 Fully Tested - 125+ tests with Pest PHP

Requirements

• PHP 8.3+
• Laravel 11.x, 12.x, or 13.x
• Google Cloud API key with Routes API enabled

Installation

Install the package via Composer:

Publish the configuration file:

Add your Google API key to your .env file:

Quick Start

Usage

Basic Route Calculation

Using Addresses

Using Place IDs

With Intermediate Waypoints

Travel Modes

Traffic-Aware Routing

Route Modifiers

Alternative Routes

Fuel-Efficient Routes

Waypoint Optimization

Departure Time

Extra Computations

Custom Field Mask

Specify which fields to include in the response:

High Quality Polylines

Localization

Complete Example

Eloquent Integration (Routable Trait)

You can make your Eloquent models "routable" by implementing the Routable contract and using the HasRoute trait. This allows you to pass models directly to the API headers.

1. Implement the interface and trait:

2. Use models in route requests:

3. Or initiate directly from the model:

Response Caching

To reduce API costs and improve performance, you can enable built-in caching.

1. Configure caching in config/google-routes.php:

When enabled, identical requests (same origin, destination, and options) will be served from the cache for the specified TTL duration.

Route Matrix (Distance Matrix)

The Route Matrix API allows you to calculate distances and travel times between multiple origins and destinations efficiently.

One Origin to Multiple Destinations

Multiple Origins to One Destination

Many to Many (Full Matrix)

Sorting Results

RouteMatrixElement Properties

Each element in the matrix contains:

• originIndex - Index of the origin (0-based)
• destinationIndex - Index of the destination (0-based)
• distanceMeters - Distance in meters
• duration - Duration string (e.g., "1234s")
• condition - Route condition (ROUTE_EXISTS, ROUTE_NOT_FOUND)

Helper methods:

• routeExists() - Check if a route was found
• getDurationInSeconds() - Get duration as integer
• getDistanceInKilometers() - Get distance in km
• getDistanceInMiles() - Get distance in miles
• getFormattedDuration() - Get human-readable duration

Real-World Example: Courier Pickup & Delivery

A courier needs to pick up packages from multiple stores and deliver to customers (some packages share the same destination):

Output:

Response Objects

RoutesResponse

The main response object containing:

• routes - Collection of Route objects
• fallbackInfo - Information about routing fallback (if any)
• geocodingResults - Geocoding information for address waypoints

Route

Individual route containing:

• distanceMeters - Total distance in meters
• duration - Duration string (e.g., "165s")
• polyline - Encoded polyline or GeoJSON
• legs - Collection of RouteLeg objects
• viewport - Map bounding box
• routeLabels - Route type labels
• warnings - Route warnings

Helper methods:

• getDurationInSeconds() - Get duration as integer
• getDistanceInKilometers() - Get distance in km
• getDistanceInMiles() - Get distance in miles
• getFormattedDuration() - Get human-readable duration
• isDefaultRoute() - Check if default route
• isFuelEfficient() - Check if fuel-efficient route

Configuration

The configuration file (config/google-routes.php) includes:

Exception Handling

The package throws specific exceptions:

Testing

Run the test suite:

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security-related issues, please email [email protected] instead of using the issue tracker.

Credits

• Gowelle
• All Contributors

License

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