Statamic Super Location Laravel Package

Getting Started

Scope note: This assessment is based on the v2.0.0 release notes only (Add Statamic 6 support for super location fieldtype) — no source, README, or repo data was supplied. Package internals below are described as conventions typical of Statamic fieldtype addons; verify names and config keys against the vendor README and config/ file before shipping.

Install

composer require <vendor>/<super-location>
php artisan vendor:publish --tag="super-location-config"   # check the actual tag

Configure the credential first. A location fieldtype needs a geocoding provider, so expect an API key in config/super-location.php and an .env entry (SUPER_LOCATION_API_KEY or similar). Confirm the config key name by diffing the published file — guessing here is the most common first-run failure.

Then add the field to a blueprint. Easiest path is the Control Panel: Blueprints → your collection → Add Field → Super Location. The YAML equivalent is roughly:

fields:
  - handle: location
    field:
      type: super_location
      display: Location

First use case — one address on one entry. Create the field, save an entry with a searched address, then read it back:

{{ location }}
  <p>{{ address }}</p>
  <div data-lat="{{ latitude }}" data-lng="{{ longitude }}"></div>
{{ /location }}

Where to look next, in order: (1) the published config for provider/key settings, (2) the addon's README fieldtype options and augmentation docs, (3) the fieldtype's Vue component in resources/js if you need to know exactly what shape is saved. Check composer.json constraints early — v2 requires Statamic 6, so an existing Statamic 5 site cannot take this upgrade.

Implementation Patterns

Treat the saved value as an array, not a string. Location fieldtypes normally persist a structure (address, lat, lng, and often place-id/components). Read it defensively, especially in Blade:

$location = $entry->get('location');           // array|null
$lat = data_get($location, 'latitude');

Multiple pins via Grid/Replicator. For store locators, nest the fieldtype so editors can add many locations:

fields:
  - handle: locations
    field:
      type: grid
      fields:
        - handle: place
          field:
            type: super_location

Then loop and filter out entries with no coordinates — editors will leave blank rows.

Render maps client-side, not server-side. Keep the fieldtype as the data-entry tool and render with Leaflet/Mapbox/Google Maps on the front end using the stored lat/lng. This keeps you out of the addon's JS entirely and survives addon upgrades better.

Cache geocoding output, never the map tiles. If you resolve addresses from stored coordinates (e.g. reverse geocode for display), wrap that in Cache::remember() keyed on lat/lng. Upstream geocoding is rate-limited and billed.

Live Preview is a good smoke test. Statamic's Live Preview will render the field's draft payload through your template before the entry is saved. If your template breaks on unsaved entries, it's almost always a null-vs-empty-array assumption — fix it there and you've pre-empted the same bug in production.

Keep display formatting in a presenter, not the template. A small accessor or view model that returns a formatted lat,lng string and a display address pays off the moment you swap map providers or add a second render target (JSON API, sitemap, structured data).

Gotchas and Tips

• v2.0.0 is a compatibility cut, not a feature release. The only documented change is Statamic 6 support, and a major version bump on an addon usually raises the statamic/cms constraint rather than widening it. Assume Statamic 5 is dropped: pin ^1.0 if you're staying on Statamic 5, and don't attempt a mixed-version install. Check composer.json before running composer update in a working site.
• Upgrade order matters. Upgrade Statamic first, then the addon — and clear caches after: php artisan statamic:stache:clear, php artisan view:clear, and php artisan config:clear if you edited config. Stale stache and compiled config are the two most common "the field renders blank after upgrade" causes.
• The API key is the leak vector. If any rendering path puts a key into front-end markup, restrict it by HTTP referrer (or proxy geocoding through your own endpoint). Also remember config:cache in production freezes the config array — .env changes need a re-cache.
• Blank vs missing coordinates. Editors can save an address without a picked coordinate, or vice versa. Normalise on read (data_get($loc, 'latitude') with a null check) and validate on save where possible.
• Static caching will freeze your map markup. If you enable Statamic's static caching, any server-rendered address/marker markup is cached until the entry is saved. Prefer hydrating maps from JSON at request time.
• Coordinate precision and locale. Float display, thousands separators, and comma-decimal locales are a classic source of invalid lat,lng strings. Format with number_format($lat, 6, '.', '') before it reaches a JS map library.
• Extension points to check: the fieldtype's Vue component (custom UI/behaviour), the published config (provider selection, default zoom, allowed components), and the augmentation method if you want the value to serialise differently for the REST/GraphQL API.
• No changelog for intervening 1.x releases was supplied. If you're jumping from an older 1.x, read the full changelog rather than the v2.0.0 note — deprecations may have landed earlier.