README

A PHP library for integrating with the Google Distance Matrix API in WordPress. This library provides robust distance and time calculations between multiple origins and destinations with support for WordPress transient caching and WP_Error handling.

Features

📊 Distance Calculations: Calculate distances between multiple origins and destinations
⏱️ Travel Times: Get accurate travel duration with traffic considerations
🚗 Multiple Modes: Support for driving, walking, cycling, and transit modes
🌍 International: Support for distance calculations worldwide
📏 Unit Flexibility: Support for both metric and imperial measurements
🔄 Response Parsing: Clean response object for easy data access
⚡ WordPress Integration: Native transient caching and WP_Error support
🛡️ Type Safety: Full type hinting and strict types
🚦 Traffic Data: Optional real-time traffic consideration
🗺️ Route Options: Support for route restrictions and preferences
🔗 Fluent Interface: Chainable methods for setting options

Requirements

PHP 7.4 or later
WordPress 6.7.1 or later
Google Distance Matrix API key

Installation

Install via Composer:

composer require arraypress/google-distance-matrix

Basic Usage

use ArrayPress\Google\DistanceMatrix\Client;

// Initialize client with your API key
$client = new Client( 'your-google-api-key' );

// Using fluent interface
$result = $client
	->set_mode( 'driving' )
	->set_units( 'imperial' )
	->set_avoid( 'tolls' )
	->calculate( 'New York, NY', 'Boston, MA' );

if ( ! is_wp_error( $result ) ) {
	// Get distance and duration
	$distance = $result->get_formatted_distance();
	$duration = $result->get_formatted_duration();

	echo "Distance: {$distance}\n";
	echo "Duration: {$duration}\n";

	// Get raw values in meters/seconds
	$meters  = $result->get_distance_meters();
	$seconds = $result->get_duration_seconds();
}

Setting Default Options

// Set defaults for multiple calculations
$client
	->set_mode( 'driving' )
	->set_units( 'imperial' )
	->set_language( 'en' );

// Use defaults
$result1 = $client->calculate( 'New York, NY', 'Boston, MA' );

// Override specific options
$result2 = $client->calculate(
	'New York, NY',
	'Boston, MA',
	[ 'mode' => 'transit' ]
);

// Reset to default options
$client->reset_options();

Multiple Origins/Destinations

$origins = [
	'San Francisco, CA',
	'Los Angeles, CA'
];

$destinations = [
	'Las Vegas, NV',
	'Phoenix, AZ',
	'San Diego, CA'
];

$result = $client
	->set_mode( 'driving' )
	->set_units( 'imperial' )
	->calculate( $origins, $destinations );

if ( ! is_wp_error( $result ) ) {
	$distances = $result->get_all_distances();
	foreach ( $distances as $route ) {
		echo "From: {$route['origin']}\n";
		echo "To: {$route['destination']}\n";
		echo "Distance: {$route['distance']['text']}\n";
		echo "Duration: {$route['duration']['text']}\n\n";
	}
}

Available Options

Travel Modes

const VALID_MODES = [
    'driving',
    'walking',
    'bicycling',
    'transit'
];

Units

const VALID_UNITS = [
    'metric',
    'imperial'
];

Avoid Options

const VALID_AVOID = [
    'tolls',
    'highways',
    'ferries'
];

Traffic Models

const VALID_TRAFFIC_MODELS = [
    'best_guess',
    'pessimistic',
    'optimistic'
];

Default Options

const DEFAULT_OPTIONS = [
    'mode' => 'driving',
    'units' => 'metric',
    'language' => 'en'
];

Working with Options Array

$result = $client->calculate(
    'New York, NY',
    'Boston, MA',
    [
        'mode' => 'driving',           // driving, walking, bicycling, transit
        'units' => 'imperial',         // metric or imperial
        'avoid' => 'tolls',           // tolls, highways, ferries
        'language' => 'en',           // response language
        'traffic_model' => 'best_guess' // best_guess, pessimistic, optimistic
    ]
);

Handling Responses with Caching

// Initialize with custom cache duration (1 hour = 3600 seconds)
$client = new Client( 'your-api-key', true, 3600 );

// Results will be cached
$result = $client->calculate( 'New York, NY', 'Boston, MA' );

// Clear specific cache
$client->clear_cache( 'matrix_New York, NY_Boston, MA' );

// Clear all distance matrix caches
$client->clear_cache();

API Methods

Client Methods

Option Setters

set_mode( string $mode ): Set travel mode
set_units( string $units ): Set distance units
set_avoid(?string $avoid ): Set features to avoid
set_language( string $language ): Set response language
set_traffic_model(?string $model ): Set traffic model
reset_options(): Reset all options to defaults

Core Methods

calculate( $origins, $destinations, $options = [] ): Calculate distances
clear_cache( $identifier = null ): Clear cached responses

Response Methods

Distance Methods

get_distance( $origin_index, $destination_index ): Get distance data for specific pair
get_duration( $origin_index, $destination_index ): Get duration data for specific pair
get_formatted_distance( $origin_index, $destination_index ): Get formatted distance string
get_formatted_duration( $origin_index, $destination_index ): Get formatted duration string
get_distance_meters( $origin_index, $destination_index ): Get distance in meters
get_duration_seconds( $origin_index, $destination_index ): Get duration in seconds

Data Access Methods

get_origins(): Get array of origin addresses
get_destinations(): Get array of destination addresses
get_all_distances(): Get all calculated distances in array format
get_element( $origin_index, $destination_index ): Get specific matrix element
get_element_status( $origin_index, $destination_index ): Get status of specific calculation
is_complete(): Check if all calculations were successful
find_nearest_destination( $origin_index ): Find nearest destination to specific origin

Use Cases

Delivery Planning: Calculate delivery routes and times
Shipping Costs: Distance-based shipping calculations
Service Areas: Define and check service coverage areas
Route Optimization: Find optimal routes for multiple destinations
Travel Time Estimation: Accurate travel time calculations
Fleet Management: Support for vehicle routing and planning
Coverage Analysis: Analyze service area coverage
Location Planning: Optimize location selection based on distance
E-commerce Shipping: Calculate shipping costs based on distance
Service Radius: Define service areas with time/distance constraints

arraypress / google-distance-matrix

Maintainers

Details