Statamic Simple Address Laravel Package

Getting Started

This is a Statamic addon (el-schneider/statamic-simple-address), so it runs on top of a Laravel + Statamic app rather than a plain Laravel project.

1. composer require el-schneider/statamic-simple-address
2. Publish the config: php artisan vendor:publish --tag="simple-address-config" (verify the tag with php artisan vendor:publish --provider=... if it doesn't resolve).
3. Open config/simple-address.php first — as of v0.2.4 this is where the map tile layers live, and it's the file you'll touch most.
4. Add the fieldtype to a blueprint (e.g. a location or contact collection): field handle address, type simple_address.
5. Create/edit an entry and confirm the map preview renders.

First use case: a single address field on an entry with a map preview and stored lat/lng, rendered on the front end via Antlers.

Implementation Patterns

Blueprint-driven address fields. Configure the field once in the blueprint and let editors pick addresses; store the structured result on the entry. Keep the handle stable (address) so templates and any geocoding logic don't churn.

Rendering in Antlers. Read the field as a structured value rather than a raw string, e.g. {{ address:line1 }}, {{ address:lat }}, {{ address:lng }}. Guard with {{ if address }} — a failed geocode often yields an empty field rather than an exception.

Tile layer configuration (v0.2.4+). The config now exposes provider-neutral light and dark tile layers. Point both at any XYZ-style source by supplying a URL template with {z}/{x}/{y} placeholders:

'tiles' => [
    'light' => 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
    'dark'  => 'https://your-provider.example/dark/{z}/{x}/{y}.png',
],

Because the default is now OpenStreetMap, you get a working map out of the box with no API key or watermark — good for local dev and low-traffic sites.

Dark mode. If you don't set a separate dark layer, the light layer is reused, so you can ship a dark theme without sourcing a second provider. Wire the front end to swap layers on a prefers-color-scheme / theme-class toggle rather than expecting the package to detect it.

Provider swap strategy. Treat tile URLs as environment-specific: keep OSM defaults in the committed config for dev, and override to a paid provider (MapTiler, Stadia, Thunderforest, self-hosted) in production via env-driven config. This keeps you compliant with OSM's tile usage policy without changing code.

Existing installs. v0.2.4 is backward compatible with published configs, so an upgrade won't break anything — but a previously published config also won't gain the new tile keys. Merge the new keys in manually, or republish and diff.

Gotchas and Tips

• OSM tile usage policy. tile.openstreetmap.org is fine for development and low-volume production, but it forbids heavy/bulk use and requires attribution. Set a descriptive User-Agent/Referer and put "© OpenStreetMap contributors" on every map. For real traffic, switch to a commercial or self-hosted provider.
• Old configs don't auto-update. After upgrading to v0.2.4, if you had a published simple-address.php it still holds the old CARTO defaults (and their watermarks). Actively replace those entries — the compatibility guarantee is about not breaking, not about migrating values.
• Config caching. Run php artisan config:clear (and re-cache) after editing tile URLs; a stale bootstrap/cache/config.php is the usual reason a provider change "does nothing."
• Content Security Policy. New tile hosts must be allowed in img-src (or connect-src if tiles are fetched via JS). Switching to OSM means adding https://tile.openstreetmap.org — a CSP violation shows up only in the browser console, not in Laravel logs.
• Dark fallback is silent. If your dark map looks identical to light, that's the documented fallback, not a bug. Check that tiles.dark is actually set and non-empty.
• Geocoding failures are quiet. Empty coordinates are the common symptom; validate on save or surface a field-level error so editors notice.
• Cache geocoding results. Repeated geocoding on every render will burn through provider quotas and slow pages; persist lat/lng on the entry and resolve once.
• Attribution and zoom/center live in the front-end map config, not this package — keep them next to your tile config so they move together when you change providers.
• Extension point: the config file is the intended seam. Prefer env-driven config over forking the addon; keep the published file thin so future releases are easy to diff.