Statamic Alpine Csp Forms Laravel Package

Getting Started

This is a Statamic add-on, not a general Laravel package, so the first step is confirming your project is a Statamic site with forms rendered through Antlers or Blade and served under a strict Content Security Policy.

1. Install the add-on

   composer require uams-web/statamic-alpine-csp-forms:0.1.0
   

   Because this is a 0.x pre-release, pin the exact version rather than using a floating constraint. Check Packagist for the exact package name and whether you need an explicit stability flag or @dev/@beta constraint.

2. Check auto-discovery and published assets Statamic add-ons normally register a service provider automatically. Confirm whether the add-on ships a config file or front-end assets that need publishing:

   php artisan vendor:publish --tag=statamic-alpine-csp-forms
   

   Use the tag documented in the add-on README; if no publish tag exists, skip this step.

3. Load the Alpine CSP build and the driver The add-on provides the alpine_csp form JavaScript driver. Follow the README for the exact asset tag or Vite entry point. The important part is that the page loads:

   • Alpine’s CSP-compatible build, not the standard inline-expression build.
   • The add-on’s driver script with your CSP nonce applied.

4. First use case Take one existing Statamic form with conditional fields — for example, a “Company” field that reveals “VAT number” only when a “Business” option is selected. Run it under Content-Security-Policy-Report-Only first, confirm the field conditions evaluate in the browser, then enforce the CSP.

Where to look first:

• The add-on README for the asset registration tag and required Alpine setup.
• Your form blueprint for existing field conditions.
• Your CSP middleware/config (spatie/laravel-csp or custom middleware) for the nonce and script-src rules.

Implementation Patterns

Use the add-on as the bridge between Statamic field conditions and Alpine CSP

The add-on has two jobs: load a CSP-safe Alpine form driver, and evaluate the field conditions defined in your Statamic blueprints in the browser. The server remains responsible for validation and submission handling; the driver only improves the form UX.

Typical workflow:

1. Define conditional fields in the blueprint as you normally would (for example using Statamic’s if/show_when condition syntax).
2. Render the form through Statamic’s form tags or your own Blade view.
3. Ensure the add-on’s driver script is loaded on pages containing those forms.
4. Verify that changing one field updates dependent fields without a round trip.

Keep Alpine expressions CSP-compatible

With Alpine’s CSP build you cannot rely on inline JavaScript expressions in attributes such as x-on:click="doSomething()" or inline object literals in x-data. Register named Alpine components/data objects in external JavaScript instead:

document.addEventListener('alpine:init', () => {
    Alpine.data('contactForm', () => ({
        submitted: false,
    }));
});

Then reference only the registered name in markup. This is the pattern the CSP build expects, and the add-on’s driver should follow the same constraint.

Propagate the CSP nonce to every script tag

If you use spatie/laravel-csp, make sure the nonce is applied to the add-on’s script tag as well as Alpine itself. A common pattern is to pass the nonce into your layout:

<script nonce="{{ csp_nonce() }}" src="{{ asset('vendor/statamic-alpine-csp-forms/driver.js') }}"></script>

Use the actual asset path or tag from the add-on README. If the nonce is missing from one script, the browser will block it and field conditions will silently stop working.

Pair browser behaviour with server-side validation

Field conditions are presentation logic. Do not use them as validation. A field hidden by the evaluator must still be rejected or ignored server-side according to your form’s validation rules. Statamic form submissions should continue to validate all required fields as configured.

Roll out behind Report-Only CSP

For an existing site, deploy with Content-Security-Policy-Report-Only first:

• Render a form with at least one conditional field.
• Open the browser console and check for CSP violations.
• Confirm the driver and Alpine CSP build both load with the nonce.
• Fix violations, then switch to enforcing mode.

This is especially important when moving from a non-CSP Alpine setup, because previously tolerated inline expressions will now be blocked.

Test the form in a real browser

A PHP feature test can assert that the form markup and script tags render, but it cannot verify the browser-side evaluator. Cover the actual behaviour with Dusk, Playwright, or a manual browser check:

• Toggle the controlling field.
• Confirm dependent fields show and hide.
• Submit the form and confirm server-side validation still behaves correctly.
• Reload with a hard refresh to rule out cached old driver assets.

Gotchas and Tips

0.x means breaking changes can arrive in minor releases

The release notes explicitly state that a minor release can carry a breaking change and will call it out first. Practical consequences:

• Pin the exact version in composer.json, for example "uams-web/statamic-alpine-csp-forms": "0.1.0".
• Read release notes before running composer update.
• Do not assume patch-level compatibility across minor versions.
• Expect API or asset-path changes before 1.0.0; keep your integration thin so upgrades are cheap.

Pre-release availability on Packagist

If Composer refuses to install the package due to stability, add an explicit constraint with a stability suffix or set minimum-stability carefully. Prefer a targeted constraint over lowering minimum stability for the whole project.

CSP build of Alpine has real syntax limitations

The most common failure mode is copying Alpine examples from the docs that use inline expressions. Under the CSP build those will not run. Symptoms include:

• Console errors about unsafe inline script or unsafe-eval.
• Alpine initialises but event handlers do nothing.
• Field conditions never update.

Fix by moving logic into registered Alpine components and binding only method or property names in markup.

Nonce mismatches and caching

Two frequent causes of “it worked yesterday”:

• Nonce mismatch: a cached page contains an old nonce while the current response sends a different one. Ensure pages containing forms are not cached with a stale nonce, or use a cache-safe nonce strategy.
• Stale assets: the browser serves an old driver script after an add-on update. Clear Statamic’s cache and your application cache:

  php artisan cache:clear
  php artisan statamic:stache:clear
  

  Then hard-refresh the browser.

Debugging checklist

When field conditions do not work:

1. Check the browser console for CSP violations.
2. Inspect the rendered HTML and confirm the driver script tag has the same nonce as the CSP header.
3. Confirm script-src allows the nonce or the host serving the driver.
4. Confirm the Alpine CSP build is loaded, not the standard Alpine build.
5. Confirm the conditional field’s condition syntax matches what the add-on’s evaluator supports.
6. Temporarily switch to Content-Security-Policy-Report-Only to see blocked resources without breaking the page.
7. Disable JavaScript and confirm the form still submits acceptably with server-side validation.

Extension points and compatibility

• The field-conditions evaluator is browser-side. If you need custom operators or condition semantics, check the add-on’s config and source before writing your own evaluator; the README is the source of truth for supported condition syntax.
• Confirm the add-on’s supported Statamic version range before upgrading Statamic. Use composer why-not uams-web/statamic-alpine-csp-forms <version> when resolving conflicts.
• Because the driver was extracted from a specific site (UAMS), expect some assumptions to remain from that integration. Read the driver source if you need to support unusual form markup or multiple forms on one page.

License and maintenance expectations

The add-on is MIT licensed, which is permissive for project use. It is still a pre-1.0 package, so treat it as an integration dependency that needs version pinning and periodic review rather than a stable platform component.