PHPackages sysborg/gmaps-laravel - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. sysborg/gmaps-laravel ActiveLibrary[Utility & Helpers](/categories/utility) sysborg/gmaps-laravel ===================== Google Maps API package for Laravel using Ports and Adapters architecture 0.0.1(2mo ago)01MITPHPPHP ^8.2 Since Mar 1Pushed 2mo agoCompare [ Source](https://github.com/sysborg/gmaps-laravel)[ Packagist](https://packagist.org/packages/sysborg/gmaps-laravel)[ RSS](/packages/sysborg-gmaps-laravel/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (6)Versions (2)Used By (0) sysborg/gmaps-laravel ===================== [](#sysborggmaps-laravel) > A Google Maps API package for Laravel built on **Ports and Adapters (Hexagonal Architecture)** — clean, testable, and designed to grow with your needs. [![PHP](https://camo.githubusercontent.com/187240af044d09d5b14a1d9d9ebdf3f7a993e4c7bc09bdb46b4ba661a891bf5b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322532422d626c7565)](https://php.net)[![Laravel](https://camo.githubusercontent.com/0171c541f6433dcec81b1736e87bba993ce6d1b126d0954ece853c872cc659f7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d31312532422d726564)](https://laravel.com)[![License](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](LICENSE)[![Tests](https://camo.githubusercontent.com/d940ad7f0752e2cbe0d63c50dcebf329078807390051c41fe63258f1b5c4e182/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f74657374732d70617373696e672d627269676874677265656e)](#testing) --- Why this package? ----------------- [](#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 ------------ [](#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](https://console.cloud.google.com). --- Usage ----- [](#usage) ### Nearby Places Search [](#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 -------------- [](#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`](config/gmaps.php). --- Architecture ------------ [](#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 ------- [](#testing) ``` composer install ./vendor/bin/phpunit ``` All tests use `Http::fake()` — no real API calls are made. ``` OK (11 tests, 30 assertions) ``` --- Currently Implemented --------------------- [](#currently-implemented) FeatureStatusPlaces — Nearby Search✅Cache with TTL per use case✅Facade + DI integration✅Typed DTOs (readonly)✅PHPUnit tests with Http::fake()✅--- Roadmap — Have a need? Open an issue! ------------------------------------- [](#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. FeatureNotesPlaces — Text SearchSearch by keyword anywherePlaces — Place DetailsFull details by `place_id`Places — AutocompleteFor address/search inputsGeocoding APIAddress ↔ coordinatesReverse GeocodingCoordinates → formatted addressDirections APIRoutes with waypointsDistance MatrixMulti-origin/destination travel timeStatic MapsGenerate map image URLsElevation APIAltitude for coordinatesTime Zone APITimezone from coordinatesRoads APISnap-to-road, speed limitsPagination helperAuto-fetch next pagesMulti-page collectorMerge all paginated results automatically> **Have a specific need?** [Open an issue](https://github.com/andmarruda/gmaps-laravel/issues) describing what you need and how you plan to use it. The more context you give, the faster it gets implemented. --- Contributing ------------ [](#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`](docs/plan/architecture.md)) 4. Write tests with `Http::fake()` 5. Open a PR --- Support the project ------------------- [](#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. [![Buy Me a Coffee](https://camo.githubusercontent.com/919a04afeb7c06d313e361b104566d208a8630180a28826bdcd1202b63559a31/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4275792532304d6525323061253230436f666665652d254532253938253935253230537570706f727425323074686525323070726f6a6563742d79656c6c6f773f7374796c653d666f722d7468652d6261646765266c6f676f3d6275792d6d652d612d636f66666565266c6f676f436f6c6f723d626c61636b)](https://buymeacoffee.com/andmarruda) --- License ------- [](#license) MIT © [Anderson Arruda](https://github.com/andmarruda) ### Health Score 34 — LowBetter than 77% of packages Maintenance86 Actively maintained with recent releases Popularity1 Limited adoption so far Community6 Small or concentrated contributor base Maturity36 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 69d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/3a6c206a9669758146bf810648f37de32eb5cd5c07b8faa66c987b84fe3da696?d=identicon)[sysborg](/maintainers/sysborg) --- Top Contributors [![sysborg](https://avatars.githubusercontent.com/u/59512284?v=4)](https://github.com/sysborg "sysborg (1 commits)") --- Tags laravelgeocodinghexagonalgoogle mapsplaces ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/sysborg-gmaps-laravel/health.svg) ``` [![Health](https://phpackages.com/badges/sysborg-gmaps-laravel/health.svg)](https://phpackages.com/packages/sysborg-gmaps-laravel) ``` ### Alternatives [laravel/pulse Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application. 1.7k12.1M99](/packages/laravel-pulse)[spatie/laravel-enum Laravel Enum support 3655.4M31](/packages/spatie-laravel-enum)[psalm/plugin-laravel Psalm plugin for Laravel 3274.9M308](/packages/psalm-plugin-laravel)[roots/acorn Framework for Roots WordPress projects built with Laravel components. 9682.1M97](/packages/roots-acorn)[laragear/preload Effortlessly make a Preload script for your Laravel application. 119363.5k](/packages/laragear-preload)[dragon-code/pretty-routes Pretty Routes for Laravel 10058.7k4](/packages/dragon-code-pretty-routes) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)