psvneo/t3-extension-merchants

This extension adds a plugin to display merchant records on an interactive Google Maps map, featuring location search, filtering, and a detail view.

8.0.1 2026-03-25 15:23 UTC

Requires

• php: ^8.2
• parsecsv/php-parsecsv: ^1.3
• psvneo/typo3-extension-easy-api: ^2.0
• typo3/cms-backend: ^14.1
• typo3/cms-core: ^14.1
• typo3/cms-extbase: ^14.1
• typo3/cms-fluid: ^14.1
• typo3/cms-frontend: ^14.1

Requires (Dev)

• psvneo/qa-toolset-t3: ^5.0

GPL-3.0-or-later

• extension
• merchant
• typo3

README

This extension adds a plugin to display merchant records on an interactive Google Maps map, featuring location search, filtering, and a detail view. It also provides a CLI command to import merchant data from a CSV file.

Requirements

• TYPO3 14+
• PHP 8.2+
• A Google Maps API key with the following APIs enabled in the Google Cloud Console:
  • Maps JavaScript API
  • Geocoding API
  • Places API (New)

Installation

• Install the extension via Composer:

  composer require psvneo/t3-extension-merchants
  

• Add Endpoint definition to your site config.yaml

  imports:
      -   resource: 'EXT:psvneo_merchants/Configuration/EasyApi.yaml'
  

Plugin Configuration (FlexForm)

Configure the plugin via the page content element. The following settings are available:

Map

Setting	Description
API Key	Your Google Maps API key
Map ID	Your Google Maps Map ID (required for AdvancedMarkerElement)
Initial Latitude	Latitude of the map center on initial load
Initial Longitude	Longitude of the map center on initial load
Initial Zoom	Zoom level on initial load

Important: The Map ID must be created in the Google Cloud Console under Google Maps Platform > Map Management. It is required for the advanced marker feature. Without a valid Map ID, markers will not be displayed.

Google Cloud Console Setup

1. Go to APIs & Services > Credentials and create or select an API key.
2. Under API restrictions, enable:
   • Maps JavaScript API
   • Geocoding API
   • Places API (New) — this is a separate entry from the legacy "Places API"
3. Go to Google Maps Platform > Map Management and create a Map ID with map type JavaScript.
4. Copy the Map ID into the plugin FlexForm.

Marker Icons

Custom marker icons are configured via TypoScript. The following four icons are used:

Icon	Description
Location marker	Marks the user's current or searched position
Merchant marker	Default state for merchant pins
Hover marker	Shown when hovering over a merchant pin
Selected marker	Shown when a merchant is selected (detail open)

Icons are SVG files located in Resources/Public/Icons/.

Import File Structure

"ID";"TITLE";"SUBTITLE";"ADDRESS";"LATITUDE";"LONGITUDE";"ZIP";"CITY";"FAX";"PHONE";"EMAIL";"WEBSITE";"PRIORITIZED";"CATEGORIES"
"123";"PSVNEO";"Internet, SEO, Programmierung";"Martinshardt 5";"50.850960";"8.032210";"57074";"Siegen";"12345/000000";"12345/000000";"[e-mail]";"https://psv-neo.de";"1";"Category A,Category B"

Importing Merchants via CSV

vendor/bin/typo3 psvneo_merchants:import CSVPATH PID

Arguments

Name	Description	Default
CSVPATH	The path to the import file (can be relative)	public/fileadmin/merchants.csv
PID	The storage PID of the merchants	255

Logging

Errors occurring during an import are logged to typo3temp/var/log/psvneo_merchants.import.log.

GDPR / DSGVO

The plugin displays a consent banner before loading the Google Maps API. Once the user accepts, the preference is stored in localStorage under the key psvneo_merchants_allow_gmap, and the map loads automatically on subsequent visits.