README

A Google Maps API package for Laravel built on Ports and Adapters (Hexagonal Architecture) — clean, testable, and designed to grow with your needs.

Why this package?

Most Google Maps packages for Laravel expose raw arrays and mix API calls directly into your business logic. This package takes a different approach:

• Ports and Adapters — your domain code never talks to Google directly; it depends on interfaces
• Typed DTOs — readonly classes with full IDE autocomplete, no more guessing array keys
• Built-in cache strategy — configurable TTL per use case to save money on API calls
• Facade + DI — use whichever style fits your team

Installation

composer require sysborg/gmaps-laravel

Publish the config:

php artisan vendor:publish --provider="Sysborg\GmapsLaravel\GmapsServiceProvider" --tag="gmaps-config"

Add your API key to .env:

GOOGLE_MAPS_API_KEY=your_key_here

Make sure the Places API is enabled in your Google Cloud Console.

Usage

Nearby Places Search

Find all locations within a radius from a geographic point.

Via Facade:

use Sysborg\GmapsLaravel\Facades\GMap;
use Sysborg\GmapsLaravel\DTOs\Coordinate;

$response = GMap::nearbySearch(
    coordinate: new Coordinate(-23.5505, -46.6333),
    radius:     1500,           // meters
    type:       'restaurant',   // optional
    keyword:    'pizza',        // optional
);

foreach ($response->places as $place) {
    echo $place->name;           // "Pizzaria Italia"
    echo $place->vicinity;       // "Rua Augusta, 100"
    echo $place->rating;         // 4.5
    echo $place->location->latitude;
    echo $place->location->longitude;
}

if ($response->hasNextPage()) {
    // fetch next page using $response->nextPageToken
}

Via Dependency Injection:

use Sysborg\GmapsLaravel\UseCases\Places\NearbySearchUseCase;
use Sysborg\GmapsLaravel\DTOs\Coordinate;
use Sysborg\GmapsLaravel\DTOs\Places\NearbySearchRequest;

class FindNearbyRestaurantsAction
{
    public function __construct(private readonly NearbySearchUseCase $useCase) {}

    public function handle(float $lat, float $lng): array
    {
        $response = $this->useCase->execute(new NearbySearchRequest(
            coordinate: new Coordinate($lat, $lng),
            radius:     1500,
            type:       'restaurant',
        ));

        return $response->toArray();
    }
}

Cache Strategy

Every API call is cached by default. The cache key is a deterministic hash of all request parameters — same input always hits the cache.

# Toggle cache on/off
GOOGLE_MAPS_CACHE_ENABLED=true

# Use any Laravel cache driver
GOOGLE_MAPS_CACHE_DRIVER=redis

# TTL per use case (seconds)
GOOGLE_MAPS_CACHE_NEARBY_TTL=3600

Full config reference at config/gmaps.php.

Architecture

src/
├── Contracts/          ← Ports (pure PHP interfaces, zero framework imports)
│   ├── Cache/CachePort.php
│   ├── Http/HttpClientPort.php
│   └── Places/PlacesPort.php
├── DTOs/               ← Immutable readonly value objects
│   ├── Coordinate.php
│   └── Places/  NearbySearchRequest, PlaceResult, NearbySearchResponse
├── UseCases/           ← Application layer (depends only on Ports + DTOs)
│   └── Places/NearbySearchUseCase.php
├── Adapters/           ← Infrastructure (implements Ports using Laravel/Guzzle)
│   ├── Cache/LaravelCacheAdapter.php
│   ├── Http/LaravelHttpAdapter.php
│   └── Places/GooglePlacesAdapter.php
├── Facades/GMap.php
└── GmapsServiceProvider.php

Testing

composer install
./vendor/bin/phpunit

All tests use Http::fake() — no real API calls are made.

OK (11 tests, 30 assertions)

Currently Implemented

Roadmap — Have a need? Open an issue!

This package is built to grow. The architecture makes it straightforward to add new APIs without touching existing code. If you need any of the below — or something not listed — open an issue and describe your use case. Contributions are welcome.

Have a specific need? Open an issue describing what you need and how you plan to use it. The more context you give, the faster it gets implemented.

Contributing

1. Fork the repository
2. Create a branch: git checkout -b feat/your-feature
3. Follow the existing patterns — one port, one adapter, one use case (see docs/plan/architecture.md)
4. Write tests with Http::fake()
5. Open a PR

Support the project

If this package saves you time or reduces your Google Maps API costs, consider buying a coffee. It helps keep this maintained and motivates new features to be added.

License

MIT © Anderson Arruda