Statamic Form Settings Laravel Package

Getting Started

This is a Statamic add-on (not a plain Laravel package), so it lives alongside Statamic's own settings screens and follows Statamic's add-on conventions. v0.1.0 is the first public release, and its headline change is that the site form settings now live inside the add-on and are gated behind per-feature switches — nothing is enabled by default.

Minimal steps:

1. composer require uams-web/statamic-form-settings (confirm the exact vendor/package string in the README — the repo is UAMS-Web/statamic-form-settings, but at v0.1.0 the composer name is the thing to verify before you commit it).
2. Publish the add-on's config if a publish tag is documented: php artisan vendor:publish --tag=statamic-form-settings-config. Check config/statamic-form-settings.php (or config/statamic-form-settings.php-equivalent) for the feature switch keys.
3. Clear caches: php artisan config:clear && php artisan cache:clear && php please stache:clear.
4. Log into the Control Panel and look in Settings → Forms (Statamic add-ons typically register their settings screens under the Settings nav; if you don't see it, the switch is off — see below).

First use case worth validating end-to-end: take a single site in a multi-site install, flip one feature switch on, confirm the corresponding form settings screen appears in the CP, save a value, then submit the form from the front end and confirm the saved value is actually what gets used. That one loop proves the wiring: config → CP screen → persistence → runtime read.

Where to look first in the source: the add-on's service provider (what it registers, whether the switches are read at boot or at request time), and wherever the switches are defined — that file is the actual API surface of v0.1.0.

Implementation Patterns

Treat the switches as the integration point, not an afterthought. Because every feature is opt-in, the realistic rollout is incremental: enable one switch on one site, ship it, then widen. Keep a per-environment and per-site list of enabled switches in version control rather than clicking them in the CP, so staging and production agree.

Multi-site: read the switches per site, not globally. The release is explicitly about site form settings, so the interesting configuration is the site handle, not the app. If your config file keys switches by site handle, use that; if the CP is the source of truth, resolve settings in the context of the current site (Statamic::currentSite() / the entry's site) and never cache a resolved settings object across a site boundary in a long-running worker or queue job.

Wrap reads in one place. Don't sprinkle direct settings lookups through controllers, listeners and Blade. Put a small resolver (a repository class or a service binding) in front of the add-on that takes a site handle and returns a typed object with sane defaults for "switch off". When a feature is disabled, callers should get a predictable default rather than an exception — that's what lets you flip switches without a deploy.

Hook the submission lifecycle rather than duplicating it. Statamic form submissions fire events and expose the submission payload; if you need to act on configured settings (recipients, redirects, per-form behaviour), do it from a listener or a custom submission handler that reads through your resolver, so the CP-configured values stay the single source of truth.

Test the switch matrix, not just the happy path. Your feature tests should cover: switch off (defaults applied, no CP override read), switch on with no saved settings (defaults still applied), and switch on with saved settings for a different site (no leakage). Use Statamic's testing helpers for the CP screens if the add-on ships them; otherwise assert at the event/submission level, which is the behaviour you actually care about.

Gotchas and Tips

• Everything is off by default. The single most common first-run confusion will be "I installed it and nothing changed". That's the design. Check the switch values before you file a bug.
• Pre-1.0 means pin tightly. "uams-web/statamic-form-settings": "0.1.*" or an exact version. v0.1.0 already reshuffles where the settings live; assume the next minor may move config keys again. Read each release note before bumping.
• Config cache will bite you. php artisan config:cache during deploy freezes the switch values. If switches are meant to be CP-controlled at runtime, they can't live in a cached config file — check which of the two the add-on chose, because it changes your whole deploy story.
• Statamic's Stache cache is a second cache. After saving settings in the CP, stale reads usually mean php please stache:clear, not cache:clear. In local dev with stache.warm on, this is the usual culprit.
• Long-running processes. Octane, queue workers and scheduled commands won't see switch flips until they restart. Resolve settings per-job, or restart workers as part of the deploy.
• Missing CP screen is a permissions/switch problem, not a routing problem. Before digging into routes, confirm the user is a Super Admin (or has the relevant permission) and the switch is on for the current site.
• Debug by dumping the resolved settings object, not by tracing the CP request. The CP save path and the front-end read path are separate code paths; a bug is almost always that they disagree about which site they're looking at.
• Extension points to favour: the add-on's own resolver/service binding for reads, and Statamic's submission events for behaviour. Avoid editing published config in place if you can override it per environment, otherwise upgrades to v0.2+ will produce merge conflicts in a file you didn't mean to own.
• Compatibility: v0.1.0 doesn't document a Statamic major in the notes. Check composer.json require before upgrading Statamic — add-ons at 0.x commonly pin a single major.