Form Handler Signature Laravel Package

Getting Started

v1.4.0 is best treated as a presentation-policy alignment release: it inherits Form Flow ^1.11 presentation rules, adds bounded tokens, semantic action labels, and inert claim previews while keeping handler execution and validation out of the presentation layer. Start by confirming the package is installed alongside form-flow/form-flow:^1.11, then inspect the package config/service provider and the Form Flow presentation policy resolution points. A good first use case is a read-only claim preview: render the flow with inherited policy, verify action labels are semantic, confirm the preview cannot execute handlers, then wire the real submit path through validation and handler execution separately. The release notes indicate the full package Pest suite passed before release, so use those tests as the first regression baseline.

Implementation Patterns

• Keep presentation and execution separate: resolve the Form Flow presentation policy, render claim previews from a view model/DTO, and only call handlers after explicit validation.
• Use semantic action labels from policy/config rather than hardcoding button or action text in Blade/Livewire views.
• Enforce bounded tokens at the presentation boundary and test both normal and boundary token sizes.
• Make previews inert by design: no handler dispatch, no validation side effects, and no state mutation during preview rendering.
• In controllers or Livewire components, validate input first, then invoke the domain handler/action class; do not mix validation or business logic into presentation templates.
• Reuse inherited Form Flow policy rather than duplicating UI rules locally; this keeps day-to-day form behavior consistent across flows.
• Add feature tests for policy inheritance, semantic labels, bounded token behavior, inert previews, and the split between validation and handler execution.

Gotchas and Tips

• Check the Form Flow version constraint carefully: ^1.11 is required for the inherited presentation policy behavior.
• Inherited policy can override or mask local presentation config; debug the resolved policy, not just the local config file.
• Bounded tokens should fail safely. Test off-by-one and oversized token cases rather than only the happy path.
• Do not hardcode action labels; semantic labels are part of the release contract and may come from inherited policy.
• Verify claim previews are truly inert: no form submission, handler call, or validation side effect should occur while previewing.
• Keep handler execution and validation separate from presentation to avoid previews accidentally mutating state or surfacing execution errors as UI errors.
• When debugging, inspect in this order: Form Flow policy resolution, token bounds, action label mapping, preview inertness, then handler/validation wiring.