Google Maps Bundle Laravel Package

Getting Started

Reality check first: this is a Symfony bundle, not a Laravel package. If your app is Laravel, you almost certainly should not composer require it and hope the service provider auto-registers — there isn't one. Treat it as either (a) a Symfony-side dependency if you run a mixed stack, or (b) a reference implementation to copy the handful of cURL/Guzzle calls out of. The bundle itself is small, last released in 2018, and has essentially no community around it — so plan for it to be unmaintained.

Minimal install (Symfony context only):

composer require mkebza/google-maps-bundle

Then register the bundle the Symfony way for the era it targets (Symfony 3.x/4.x):

// config/bundles.php (Symfony 4) or app/AppKernel.php (Symfony 3)
Mkebza\GoogleMapsBundle\GoogleMapsBundle::class => ['all' => true],

Where to look first, in order:

1. README.md — for the exact config key namespace (google_maps: vs mkebza_google_maps: — these vary by author and this bundle predates conventions).
2. DependencyInjection/Configuration.php — the authoritative list of config options and their defaults. This is your real documentation.
3. DependencyInjection/GoogleMapsExtension.php and Resources/config/services.yml — shows the service IDs you'll inject and whether the API key is a constructor arg or a setter.
4. Services/ (or Service/) — the actual API wrappers. Read these before using them; at this star count, expect thin wrappers around file_get_contents or raw Guzzle with limited error handling.
5. Tests/ if present — the fastest way to see expected inputs/outputs.

Configure the key:

# config/packages/google_maps.yaml
google_maps:
    api_key: '%env(GOOGLE_MAPS_API_KEY)%'

First use case to validate the install: server-side geocoding. Take a user-entered address, resolve it to lat/lng, persist it. This exercises config loading, the HTTP client, and JSON decoding in one shot — if that works, the bundle is wired correctly.

public function geocode(GoogleMapsService $maps, string $address): array
{
    return $maps->geocode($address); // verify method name against Services/
}

If you're in Laravel and just need this functionality, skip the bundle and use Illuminate\Support\Facades\Http against the Geocoding API directly — it's ~15 lines and you control the error handling:

$response = Http::get('https://maps.googleapis.com/maps/api/geocode/json', [
    'address' => $address,
    'key' => config('services.google_maps.key'),
])->throw()->json();

Implementation Patterns

Wrap the bundle service in your own application service. Never let bundle service IDs leak into controllers or, worse, Blade/Twig templates. The bundle will be replaced eventually; your Geocoder interface won't.

interface Geocoder
{
    public function locate(string $address): ?Coordinates;
}

Bind the bundle's service to this interface in your container. That single indirection is what makes the abandoned-package risk survivable.

Cache aggressively and normalize. Geocoding results are effectively permanent for a given address and Google bills per request. Cache by a normalized key (strtolower(trim(preg_replace('/\s+/', ' ', $address)))) with a long TTL — a year is fine. Use Laravel's Cache::remember or Symfony's cache contracts depending on your stack.

return Cache::remember("geo:{$key}", now()->addYear(), fn () => $this->geocoder->locate($address));

Queue batch work. Distance Matrix and Directions calls are the expensive ones. If you're computing distances for a list of warehouses, dispatch a job per pair or per chunk rather than looping synchronously in a request. The bundle has no batching abstraction, so build it yourself.

Keep the API key server-side and split keys. The bundle is meant for server-to-server calls. Use a separate, IP-restricted key for the bundle and a separate, referrer-restricted browser key for any JS maps. Never reuse one key across both — Google will reject requests with a confusing REQUEST_DENIED if you do.

Configuration per environment. Point the key at an env var, and make the base URL configurable if the bundle exposes it. This lets you swap in a mock server (or an httptest-style fake) in tests without touching code.

For Laravel integration, bind, don't boot. If you truly must use the bundle's classes inside Laravel, register a small service provider that constructs the underlying service manually and resolves config from config/services.php. Don't attempt to run the Symfony DI extension — you'd be reimplementing half of Symfony's container.

Pair with a mapping frontend, not a server-side renderer. The bundle returns data; let your JS (Leaflet, Mapbox GL, Google Maps JS) do the drawing. Trying to get static map images through this bundle for anything interactive is a dead end.

Gotchas and Tips

It's abandoned — vendor the code if you use it. Last release 2018-12-13, one star, zero dependents. There will be no security patches, no PHP 8.3 fixes, no Symfony 6/7 support. If you decide to depend on it, either fork it under your org or copy the ~3 classes you need into app/Support/. Treat composer require as a short-term convenience only.

PHP and Symfony version constraints will fight you. A 2018 bundle will declare php: ^7.1 and symfony/framework-bundle: ^3.4|^4.0. Modern Composer will refuse to install it on PHP 8.2 + Symfony 6 without --ignore-platform-reqs, which is a red flag, not a workaround. Check composer.json before anything else.

Expect poor error handling. These bundles typically json_decode() the response and return the array without checking status. Google returns HTTP 200 with {"status": "ZERO_RESULTS"} or "OVER_QUERY_LIMIT" — a naive wrapper will happily hand you an empty array and your code will fatal on $result['results'][0]. Always validate:

if (($data['status'] ?? null) !== 'OK') {
    throw new GeocodingFailed($data['status'] ?? 'unknown', $data['error_message'] ?? '');
}

Billing and quota changed in 2018. The package predates Google's pay-as-you-go rework. There's no billing-account awareness and no quota handling. A missing billing account returns REQUEST_DENIED with a message about the API not being enabled — not an auth error — which sends people down the wrong debugging path. Check the API is enabled in Google Cloud Console and billing is active.

Debug by inspecting the raw HTTP traffic, not the bundle. Add a Guzzle history middleware or log the URL (with the key redacted) and the raw body. Nine times out of ten the bug is a malformed address, a URL-encoded comma, or a key restriction — all invisible at the bundle's return value.

Watch for the API-key-in-URL logging leak. Many of these wrappers build GET URLs with ?key=... and log them on error. Redact key before any Log::error or Sentry capture. This is a common way API keys end up in log aggregators.

Extension points are thin. You can decorate the bundle's service with a Symfony service decorator, or override the service definition in your app's services.yaml. That's the cleanest injection point for retries, caching, and metric collection — no need to fork for those.

Better alternatives exist for new work. geocoder-php/google-maps-provider (part of the Geocoder PHP ecosystem, actively maintained, framework-agnostic), or the official googlemaps/google-maps-services-php client. Both handle status codes, retries, and signing correctly, and neither ties you to a specific framework. Reach for those unless you have a hard constraint forcing this bundle.