Download the PHP package survos/place-map-bundle without Composer

Place Map Bundle

An open-source place library + map view. Two things:

1. Place library — a Place entity (a precise point, a general area as a GeoJSON polygon, or both), imported from OpenStreetMap/Nominatim with place:import "Geneva, Switzerland".
2. Map rendering enhancement — a small Stimulus controller that adds clustered, thumbnail-on-zoom item markers to a Symfony UX Map (ux_map()) map.

This bundle deliberately does not ship its own map component or its own Leaflet wrapper. Rendering — tiles, the place polygon, the place marker, InfoWindows — is entirely symfony/ux-map + a renderer bridge (e.g. symfony/ux-leaflet-map). This bundle only adds the place-library data layer and the one thing ux-map doesn't do out of the box: clustered markers whose icon changes (dot → photo thumbnail) as you zoom in.

Requirements

• PHP 8.5+, Symfony 8.1+
• Doctrine ORM (ships the Place entity)
• The consuming app must itself require symfony/ux-map + a renderer bridge. This bundle's JS is written against symfony/ux-leaflet-map specifically (it grabs the raw Leaflet map/L instance off ux-map's own connect event) — a different renderer bridge (e.g. Google Maps) will not work with the enhancement controller, though the Place library / PlaceMapBuilder value-object conversion is renderer-agnostic.
• survos/imgproxy-bundle — optional. When installed, item thumbnails are signed imgproxy URLs (preset tiny); without it, PlaceMapBuilder::resolveThumb() passes the source URL through unchanged.
• on par in features/functionality with https://feature-map-google--fortepan.netlify.app/hu/map/?gc=46.7624,17.2513&gz=15

Why this split (and not a bespoke Leaflet wrapper)

Symfony\UX\Map\Marker supports a per-marker extra payload explicitly documented for "greater flexibility... via a custom Stimulus controller" — but the installed Leaflet bridge (ux-leaflet-map) does not round-trip that payload back onto the Leaflet marker instance it creates, so it can't drive an icon swap on zoom. Rather than fork/patch the bridge, item (photo) markers are built directly in assets/controllers/place_map_enhance_controller.js, on the same raw Leaflet map instance ux-map exposes via its ux:map:connect event — full control over clustering and icon swapping, zero forked bridge code, and the place-library layer (polygon + place marker, a small fixed set) still goes through ux-map normally via PlaceMapBuilder.

Commands

Configuration

Fetch strategy (cache/retry)

NominatimClient fetches through survos/fetch-bundle's PersistentFetcherInterface. This matters more here than for most APIs: Nominatim's usage policy caps unauthenticated use at ~1 request/second, so caching isn't just a performance nicety, it's what keeps repeat place:import runs (e.g. re-importing during development) from tripping the rate limit at all.

• Cache: keyed by the full request URL, cached forever in a SQLite pool at var/data/fetch_cache.db — until forget()/force_fetch. Re-running place:import for the same query never re-hits Nominatim.
• Retry: up to 5 attempts, full-jitter exponential backoff (200ms base, 10s cap), on transport errors, HTTP 429, and 5xx.

If a place import looks stuck on stale data, check the fetch-bundle cache pool before assuming Nominatim's data changed — forget() the specific query URL to force a fresh lookup.

Before 2026-08-08 this used a raw HttpClientInterface with no caching at all.

Usage

Build ux-map value objects from the place library with PlaceMapBuilder, then render with ux_map(). Add the enhancement controller to the same element via the attributes array so it can merge onto ux-map's own data-controller and listen for its ux:map:connect event:

ux_map()'s own attributes['data-controller'] handling normalizes whatever string you pass the same way stimulus_controller() does — that's why survos_stimulus('place-map-bundle', 'place-map-enhance') (which returns the friendly @survos/place-map-bundle/place-map-enhance form, never hand-derived) works directly there. The Stimulus value attribute names, however, are passed straight through unnormalized, so they must spell out the resolved identifier (survos--place-map-bundle--place-map-enhance) explicitly — the same identifier survos_stimulus()'s output normalizes to.

Data model

Place (table place_map_place): code (PK), label, lat/lng (nullable), geojson (nullable — a GeoJSON Polygon/MultiPolygon), boundingBox (nullable [south, north, west, east], cheap for map fit-bounds without parsing geojson), source/sourceId (provenance, e.g. osm / relation/1685488), meta (free-form, e.g. OSM's display_name/address parts).

Related bundles

This bundle imports and renders individual OSM/Nominatim places one query at a time (place:import "<query>") — a curated point/polygon library, not a name-resolution authority or a bulk matcher. Two companions cover the rest of the "what place is this?" problem:

• survos/geonames-bundle — country → admin region → city hierarchies from free text, including locale-specific alternate names (e.g. German "Wien" vs. French "Vienne" for the same city). SQLite-backed, no ORM.
• survos/poi-bundle — bulk/automated matching of a literal name against OSM features within a bounding box (e.g. matching a photo caption's place tag to a specific church or school), rather than one deliberately-chosen place at a time.

See survos/mono#28 for how the split was decided.