Google Maps Lib Laravel Package

Getting Started

1. Install via Composer (it is a plain PHP library, not a Laravel package, so there is no service provider to discover):

   composer require puwnz/google-maps-lib
   

   Confirm your project satisfies the PHP 7.3+ requirement — if you are on an older runtime the constraint will resolve to nothing or fail.

2. Read the README first, then the source. With a single-star package the README is the spec. After that, list vendor/puwnz/google-maps-lib/src to see the actual classes. The library is small, so you should be able to read the whole namespace in one sitting before relying on it — this is the fastest way to learn the real method signatures rather than guessing from docs.

3. Gather your Google Maps API key. The library is a thin wrapper that generates the map markup/JS; it does not magically get you a key. Enable the Maps JavaScript API in Google Cloud Console and restrict the key by HTTP referrer for the browser.

4. First use case: render a map with a center point and one marker in a Blade view.

   // app/Http/Controllers/MapController.php
   public function show()
   {
       $map = new \Puwnz\GoogleMapsLib\...\GoogleMap(config('services.google.maps_key'));
       $map->setCenter(51.5074, -0.1278);
       $map->addMarker(51.5074, -0.1278, 'London');
   
       return view('map', ['map' => $map]);
   }
   

   {{-- resources/views/map.blade.php --}}
   {!! $map->render() !!}
   

   Verify the exact namespace and method names against src/ — the README is the only reliable reference. Once one marker renders, you have validated install, autoload, API key, and output path in a single step.

Implementation Patterns

• Controller builds, view renders. The natural fit for this library is to construct the map in a controller (or a small service/form request) and pass the built object to a Blade view, where you {!! $map->render() !!} it. Keep the map setup out of Blade so it stays testable.
• Wrap it behind your own class. Because the API is small and unlikely to change shape, put a MapService (or GoogleMapFactory) in app/Services that owns the package. When the package is abandoned (see Gotchas) you replace one file instead of grepping the codebase.
• Config, not literals. Put the API key in config/services.php under a google.maps_key entry reading env('GOOGLE_MAPS_KEY'). Never hard-code it in a controller or pass it from a request.
• Marker-driven patterns. Typical day-to-day work is: fetch models from Eloquent, loop over them, and add a marker per row (lat/lng columns, a label, and optionally an info-window body). Keep the loop in the service layer, not the template:

  foreach (Venue::all() as $venue) {
      $map->addMarker($venue->lat, $venue->lng, $venue->name);
  }
  

• Multiple maps. Instantiate separately per map rather than reusing one object; check the source for whether state is static — if it is, reuse across requests in a single test suite will leak.
• Testing. Don't hit the network in tests. Assert against the generated HTML/JS string from render() (contains the center coordinates and marker count) or stub the service. Snapshot the rendered output is enough for regression coverage.

Gotchas and Tips

• It is not a Laravel package. No ServiceProvider, no Facade, no published config. You wire it manually. Do not add it to config/app.php providers — it will error.
• API key is client-side. Anything render() emits is visible to visitors. Referrer restrictions and API restrictions in Cloud Console are your only protection; a server-side proxy is overkill for a JS-API wrapper but you cannot hide the key.
• Pin the version. With one star and no dependents, releases are infrequent and possibly unmaintained. Use an exact or ~ constraint in composer.json and commit composer.lock. Do not composer update this package blindly.
• PHP 7.3+ only. If you upgrade to PHP 8.x, verify the package still runs — an abandoned lib can hit deprecations ({} string offsets, dynamic properties). Add a compatibility test.
• Debugging output. When the map is blank, first check the rendered HTML in "View Source" in the browser: confirm the API key appears, the script tag loads, and the console shows the standard Google error (RefererNotAllowedMapError, InvalidKeyMapError). These are Google errors, not package errors — do not waste time in the library source.
• Escape your data. Markers with user-supplied labels go into JS strings. Check whether the library escapes label/info-window content; if not, json_encode or e() the values yourself before passing them in.
• Extension points are thin. There is no event system or plugin layer. If you need clustering, custom controls, or a routing layer, either extend the map class by subclassing or (more realistically) fall back to the native Maps JavaScript API directly and use this library only for the boilerplate you cannot replicate quickly.
• Migration off is realistic. Because the surface is small, keep the wrapper class as an abstraction boundary; if the package dies, swapping to googlemaps/markerclusterer, a Blade component that emits the JS API directly, or another maintained wrapper is a single-file change.