Accessible Forms Laravel Package

Getting Started

• Install with composer require studio24/accessible-forms. The package is framework-agnostic, so in Laravel you wire it into a controller/form request and render the output from Blade rather than expecting a full Laravel form builder.
• First places to look: the package README for the Form/field API, the bundled templates (labels, fieldsets, error summary), and any config file for default CSS classes or template paths. If you need to override markup, publish/copy the templates into resources/views/vendor/accessible-forms (or the package’s documented override path).
• First use case: a contact form with a fieldset-based radio group, server-side Laravel validation, an error summary at the top, and per-field error messages. Build the form object in a controller, populate it from old() on validation failure, pass Laravel’s MessageBag into the form, and render it in Blade.
• If you have a Content Security Policy, start with the new v0.3.0 nonce option: pass the per-request nonce into the form renderer so its inline JavaScript is allowed. Get the nonce from your CSP integration (e.g. Vite::cspNonce() or your CSP package) and pass it at render time.

Implementation Patterns

• One form class per form. Encapsulate field definitions, labels, hints, and validation rules in App\Forms\ContactForm (or similar) so controllers stay thin. A typical flow is: instantiate the form, bind request data, run $request->validate($form->rules()), then $form->setErrors($validator->errors()) and re-render on failure.
• Render whole form vs. individual fields. Use the package’s full-form render for simple pages, and field-level rendering when you need custom layout (e.g. a two-column address block). Keep the package responsible for labels, aria-describedby, aria-invalid, and error text so accessibility attributes stay consistent.
• Error summary pattern. Render the error summary above the form, linking each error to its field ID. This is the main accessibility win over hand-written Blade forms; don’t duplicate error markup manually.
• Laravel validation mapping. Match field names exactly, including array notation (items.0.name). For checkboxes/radios, ensure the form repopulates checked state from old(); for selects, ensure the selected option is restored. Use Laravel’s required, email, etc. as the source of truth and let the package handle presentation.
• CSP nonce integration (v0.3.0). Pass the nonce through the form’s render options/configuration rather than hardcoding it. In a Blade layout you can do something like {!! $form->render(['nonce' => $nonce]) !!} (check the README for the exact signature). If you render form partials via AJAX, include the nonce on those responses too, and keep it per-request—never cache a rendered form containing a nonce.
• CSRF and method spoofing. In Laravel, keep @csrf in the surrounding Blade form or confirm the package emits a CSRF hidden input. For PUT/PATCH/DELETE, add @method(...) outside the package output unless the package supports it directly.
• Extension points. Prefer custom field classes/templates over post-processing HTML strings. If a field type is missing, extend the base field and register/override the template rather than string-replacing rendered output.

Gotchas and Tips

• v0.3.0 is a non-breaking feature release. The only change is the optional nonce parameter for inline JavaScript. Upgrading from 0.2.x should be safe, but re-test any page with a strict CSP because the inline script will now be blocked if the nonce is not supplied.
• Nonce must match the response header. A nonce passed to the form but not included in the Content-Security-Policy header (or vice versa) still fails. With spatie/laravel-csp or Laravel’s Vite nonce, read the same value in both places.
• Don’t cache rendered forms with nonces. Response caching, view caching of rendered HTML, or storing rendered form markup will reuse an old nonce and break CSP. Cache the form definition, not the rendered output.
• Progressive enhancement. The inline JavaScript is an enhancement (likely focus management/error summary behaviour). Ensure validation and error display work with JS disabled; the server-side error summary and field errors should be sufficient.
• Escaping. The package returns HTML, so Blade output will use {!! !!}. Verify that user-supplied values (names, messages) are escaped by the package; if you inject custom HTML into labels/hints, escape it yourself.
• Pre-1.0 API churn. At 0.3.x the API may still change. Pin to ^0.3 and read the changelog before minor upgrades; watch for renamed render options or template paths.
• Debugging CSP issues. Inspect the rendered HTML for the nonce attribute on the <script> tag, check the browser console for “Refused to execute inline script”, and confirm the Content-Security-Policy response header contains the same nonce. If the nonce is missing, check that the render call actually received it (many integrations silently drop unknown options).
• Error bag quirks. Laravel’s default error bag and custom bags can diverge; pass the same bag the form expects, and watch for old() keys that differ from field names (e.g. nested array fields) when repopulating.