Locator

Locations with address, coordinates and region, a store finder block that searches them, and a map block for a single address. Addresses are geocoded through Google when a location is saved.

• Module key locator
• Default on
• Switch EVOLVE_MODULE_LOCATOR, see Modules
• Role access evolve.roles.modules.locator
• Panel /evolve/locator/location, /evolve/locator/region

Requirements

Two Google keys from the project's Google Cloud project, both in .env:

Variable	Used for
GOOGLE_GEOCODING_API_KEY	turning a location's address into coordinates when it is saved (Geocoding API)
GOOGLE_MAPS_API_KEY	rendering maps on the site (Maps JavaScript API)

The package ships no keys 2.19. Earlier versions carried Racerfish fallback keys as config defaults; those keys are rotated. A site that relied on them sets its own before updating, otherwise map and zip search stop with the update and only the health check says why. Restrict the keys in the Google Cloud console to the site's domains.

Without GOOGLE_GEOCODING_API_KEY saving a location leaves latitude and longitude empty and the log notes the skipped geocoding. Without GOOGLE_MAPS_API_KEY the store finder lists and filters without the map and the map block renders its empty frame. Nothing fails, but the API keys health check names the missing key while the module is on.

Configuration

config/locator.php has no .env keys. allow-blocks (block editor on locations) and allow-routeable are both false. With allow-routeable on, the module exposes api/locator/location and api/locator/region for a custom frontend; the shipped store finder block does not need them.

In the panel

• Locations at /evolve/locator/location: name, address, contact details, region, opening hours and the coordinates the geocoder found. Saving an address geocodes it; the geocoder rejects empty or overlong input and times out after five seconds.
• Regions at /evolve/locator/region: groups of locations used as a filter.
• Cmd-K: "Locations", "Regions", "New location". Locations are in the global search.

On the site

Block	Component	Fields
Standort-Finder	locator.locations	title, intro text. A Livewire search over all locations with distance and region filter.
Karte	locator.map	pin link, address, zoom level, a map style as JSON. One address on a map.

Both blocks render from the module. CMS-editable fields in the store finder are escaped before output (fixed in 2.5).

Publishing

locator.config publishes config/locator.php. locator.components publishes the block definitions, the Map.php blueprint to app/Blueprints, frontend views to theme/views/vendor/locator/frontend and the block views to theme/views/components/blocks/locator.

Verifying

Save a location with a full address and check that latitude and longitude are filled. If they stay empty, the geocoding key is missing, restricted to the wrong API, or the Geocoding API is not enabled in the Google project. Geocoding results are cached, so correct the key and save the location again.