Statamic Simple Address Laravel Package

Technical Evaluation

Architecture fit This is a Statamic addon (Composer package installed into a Laravel app) that adds an address fieldtype/component with a map preview. Architecturally it follows the conventional and correct Statamic pattern: an addon service provider registers the fieldtype and views, behaviour is driven by a published config/simple-address.php, and the map layer is rendered client-side against a configurable tile endpoint. v0.2.4 hardens that boundary by removing the hard dependency on CARTO's basemap and making tile sources provider-neutral config (light layer, optional dark layer, fallback). That is the right direction for a TPM to see: presentation concerns are now configuration rather than baked-in vendor coupling, which reduces the chance that a provider change forces a package upgrade or a code fork. The package remains small in scope — a fieldtype, a config, and a JS map — so it integrates at the edge of the stack rather than into domain logic, which keeps blast radius low.

Integration feasibility Friction drops materially with this release. Previously the default CARTO tiles introduced a visible API-key watermark, which is a poor production look and often a support-ticket generator for content editors. Defaulting to OpenStreetMap means a fresh install renders a usable map with no key provisioning, no billing relationship, and no secrets to manage — a same-day evaluation is realistic. Integration is the standard composer require, php artisan vendor:publish for the config, and clearing config/view caches.

Technical risk

• Pre-1.0 versioning. At v0.2.4 there is no semver stability guarantee; the maintainer may change config keys or view structure in a minor bump. Pin an exact version and read changelogs before upgrading.
• OSM tile policy, not a technical bug but an operational one. OpenStreetMap's tile servers are donation-funded and explicitly not a production CDN for high-volume or heavy-traffic sites; attribution is mandatory and bulk usage is discouraged. The fix removes a watermark and adds a policy obligation in its place.
• Provider-agnostic means someone must own the choice. "Configure light and dark layers yourself" shifts tile-provider selection, licensing, and uptime onto us. That is a reasonable trade, but it is a decision, not a default.
• Appearance change on upgrade. Any site that deployed against v0.2.3 defaults will look different after upgrading; the release notes correctly frame this as "existing published configs remain compatible," meaning no fatal errors, not visual parity.
• Dark-mode fallback masks misconfiguration. Reusing the light layer when no dark layer is set is good UX, but it means a missing dark config fails silently rather than loudly.
• Unknowns to verify, not assume: supported Statamic major versions, PHP constraint, whether the tile layer is passed to the fieldtype view or rendered from config at build time, whether assets are versioned/published, and how the map library is bundled.

Key questions

1. Which Statamic (and therefore Laravel/PHP) versions are supported, and is the constraint declared in composer.json?
2. Does the tile layer config apply to the Control Panel fieldtype preview only, or to front-end rendered output as well? This determines who is exposed to the OSM usage policy.
3. Is there a documented path for swapping in a paid or self-hosted tile provider (Mapbox, MapTiler, Protomaps), and are attribution strings configurable?
4. What is the project's bus factor and release cadence — single maintainer, any CI, any tagged support policy?
5. Does the map make any outbound calls at page render that would need a CSP/connect-src or img-src allowlist update?

Integration Approach

Stack fit Fits any Laravel application running a supported Statamic version where address capture with a visual sanity-check is needed — editorial content types, store locators, directory listings, property records. It is not a geocoding or validation service; it renders a map for a human-readable address field. If the requirement is address autocomplete, coordinate storage, or normalisation, this package is one component and the rest must come from elsewhere. Confirm that assumption before scoping.

Migration path Upgrading from v0.2.3 is low-risk: the release explicitly preserves existing published configs, so no fatal config-key errors are expected. The real work is intentional rather than forced — decide whether to (a) accept the new OSM default, (b) re-publish the config and explicitly pin light and dark tile URLs, or (c) keep a custom CARTO setup if a contract already exists. If no config/simple-address.php was ever published, the new defaults apply silently; that is the case to watch, because appearance changes with no visible action taken.

Compatibility Verify the config file diff between v0.2.3 and v0.2.4 — "compatible" here means old keys keep working, and new keys fall back gracefully. Check that config:cache picks up the new keys in each environment, since a stale cached config is the most common cause of "the dark layer isn't applying." Also verify that asset publishing does not collide with previously published views or JS.

Sequencing

1. Pin v0.2.4 in composer.json and upgrade in a development environment first.
2. Diff the published config against the new stub; merge deliberately rather than overwriting local edits.
3. Update CSP / allowed image and script sources for the chosen tile host (tile.openstreetmap.org by default).
4. Visual QA: light mode, dark mode, missing-dark fallback path, mobile viewport, and a page with the map hidden.
5. Confirm attribution renders correctly (a licensing obligation, not a nicety).
6. Roll to staging, then production behind a normal release window. If traffic is high, complete step 1 of the tile-provider decision below before production.

Operational Impact

Maintenance Low code footprint, but pre-1.0 with a single-maintainer risk profile. Budget a light quarterly review: watch the repository for releases, re-read changelogs before bumping, and pin exact versions rather than using floating constraints. Because the package now depends on external tile infrastructure, maintenance is not purely "does the PHP still run" — it also includes "is our tile provider still appropriate, licensed, and up."

Support Community/GitHub support, no vendor SLA. Internal ownership should sit with the team that owns the Statamic site, with an explicit note in the runbook covering: which tile provider is configured, where the config lives, and what to change if tiles go blank. That single documented decision prevents most future incidents.

Scaling The critical scaling axis is not PHP — rendering a fieldtype is trivial — but tile egress and provider terms. OpenStreetMap is appropriate for low-to-moderate traffic and internal/editorial use; for a high-traffic public site, plan to move to a paid provider or self-hosted tiles via the new config, which v0.2.4 now makes a config change instead of a code change. Also consider privacy: client browsers will request tiles directly from the provider, disclosing visitor IPs to a third party. If that is a concern, a self-hosted or proxied tile source is the answer, and the same config hook supports it.

Failure modes

• Tile provider outage or rate-limiting → blank or grey map with address text intact. Confirm the component degrades gracefully and does not block form submission.
• CSP not updated → tiles silently blocked; looks identical to provider failure. Log and check browser console during rollout.
• Stale config cache → configured dark layer ignored, fallback used. Standard config:clear resolution.
• Provider terms violation (heavy traffic on OSM) → blocks or throttling, potentially without warning. Mitigate by choosing the provider deliberately.
• Future minor-version upgrade changing config keys → mitigated by pinning and changelog review.

Ramp-up Low. A developer familiar with Statamic can integrate and theme this in well under a day: install, publish, edit two tile URLs, verify attribution. The genuinely new knowledge required by this release is not Laravel or Statamic — it is tile-provider literacy (usage policies, attribution, licensing, cost curves). Assign that decision explicitly to one person rather than letting it default, because v0.2.4 correctly stopped making it for us.