Gmap Widget Laravel Package

Getting Started

This is not a Laravel package — it is a Symfony bundle that plugs a Google Maps widget into Victoire DCMS, a Symfony 2/3-era visual CMS. There is no service provider, facade, config publish, or Blade view. As a Laravel developer your realistic options are (a) run it inside a legacy Victoire/Symfony app, or (b) use it as a reference implementation and port the concept to Blade + a JS map component.

Minimal steps to get it running in its native habitat:

1. composer require friendsofvictoire/gmap-widget in the Victoire application.
2. Register the bundle in app/AppKernel.php (Symfony 2/3 style; there is no Flex recipe).
3. Import the bundle's routing/config if the bundle exposes any, and run doctrine:schema:update (or a migration) so the widget's entity table exists.
4. Open the Victoire backend page editor, drag the "Gmap" widget into a slot, fill the address/coordinates/zoom form, and save.

Where to look first, in the repository:

• The bundle class (WidgetGmapBundle.php) — shows how the widget is registered with Victoire.
• Entity/WidgetGmap.php — the persisted fields you can extend (address, latitude, longitude, zoom, and similar).
• Form/WidgetGmapType.php — the editor-side form; this is your hook for adding fields or validation.
• Resources/views/WidgetGmap/*.twig — the front-end template that actually emits the Google Maps JavaScript and the map container.

First real use case: an editor drops a map into a "Contact" page and sets the address in the widget form; the page renders a map centered on that address. Everything after that is template overrides and API-key plumbing.

Implementation Patterns

The package is a classic Victoire widget triad — entity + form type + Twig template — registered through the bundle. Day-to-day work happens in three places:

Editor configuration. The widget form is the only thing content editors see. Add fields (map type, marker icon, height, "show directions" toggle) to WidgetGmapType and persist them on the widget entity. Keep the form focused: editors should not be typing raw JSON for map options.

Template override, not fork. Victoire resolves widget templates through Twig namespaces. Override the widget's template in your application (typically under app/Resources/VictoireWidgetGmapBundle/views/... in Symfony 2/3, or in your own bundle) to change markup, container IDs, CSS classes, and the JavaScript initializer. This is the main lever you have and avoids maintaining a fork.

Server-side geocoding. The 2016 code predates the era where client-side geocoding without a key was tenable. Geocode the address on save (form event or Doctrine listener) and store latitude/longitude, so rendering is a pure template render and never depends on a browser-side geocoder that can rate-limit or fail.

API key injection. Wire the Google Maps key through Symfony parameters/config.yml and pass it into the Twig template. Do not hardcode it in the widget template.

Rendering pattern. Victoire renders widgets inside page slots; the widget's Twig template owns the map container and the init script. If a page can hold more than one map, the initializer must use a per-widget unique DOM id (see gotchas).

Porting to Laravel (the practical path for most readers). Treat this bundle as a specification, not a dependency: a Blade component (<x-google-map :lat :lng :zoom />), a Livewire/Filament form for the editor fields, a config/services.php entry for the key, and a small JS module (Alpine.js or vanilla) that instantiates the map. You lose Victoire's drag-and-drop editor, but you keep the field model and template shape the bundle demonstrates.

Gotchas and Tips

• Version reality check. Last release was December 2016, 2 stars, 0 dependents. The code targets Symfony 2/3 and PHP 5/7 and will not install cleanly into a Symfony 4+ Flex or PHP 8 project. Expect Composer constraint conflicts and abandoned transitive dependencies. Treat it as unmaintained sample code.
• The API-key cliff. Google Maps has required an API key for years, and billing/Map JavaScript API behavior changed repeatedly after 2016. The bundled template almost certainly does not include a key parameter; add one and restrict it by HTTP referrer in Google Cloud Console.
• Duplicate DOM IDs. If the template uses a fixed id like #map, two widgets on one page will silently render only one map. Make the id derive from the widget's id/uid.
• Doctrine schema drift. The widget entity needs its table; forgetting doctrine:schema:update/migrations produces confusing save failures in the Victoire editor rather than an obvious error.
• Cache. Victoire caches rendered pages and Twig aggressively. After overriding a widget template or changing the form, clear the Symfony cache and re-save the page; otherwise you will debug a template that was never used.
• Debugging registration. If the widget does not appear in the editor, the bundle registration or the widget's service tag is wrong — inspect the container (debug:container / debug:event-dispatcher on the era-appropriate Symfony version) rather than the form.
• Debugging rendering. When the map is blank, check the browser console first: missing key, referrer restrictions, and JS API deprecation warnings all surface there, not in Symfony logs.
• Extension points worth knowing. The form type (add fields), the entity (add persisted options), the Twig template (markup/JS), and — if you keep the bundle in-tree — decorating Victoire's widget renderer. Avoid editing vendor code.
• Fork before relying. With zero dependents and no releases since 2016, fork the repository into your project (or vendor it) so you can patch the Google Maps script tags, DOM id handling, and key parameter yourself; upstream fixes are not coming.