Laravel Wizard Laravel Package

Getting Started

Start by installing the package and publishing any config/views it exposes, then read the package README alongside config/wizard.php (or the package’s equivalent config) and the provided step/wizard classes. The first thing to identify is how a wizard is defined: step order, per-step validation, persistence, and the final redirect hook.

A practical first use case is an onboarding/signup flow: step 1 collects account details, step 2 collects profile/company data, step 3 reviews and confirms. Wire the wizard into a controller or Livewire component, persist draft state in the session/database as the package expects, and redirect to a dashboard on completion. In v4.5.0, the final redirect can now receive parameters, so use that from the start for contextual destinations such as a tenant dashboard, localized completion page, or return_to flow.

Implementation Patterns

• Keep steps small and explicit. Define each step as its own class/config entry with its own validation rules and persistence logic. This keeps controllers thin and makes step-level testing straightforward.
• Treat the wizard as a state machine. Use the package’s next/previous/complete APIs rather than manually tracking the current step in session. Let the package own step state and only validate/commit the current step.
• Use redirect parameters for context propagation. v4.5.0’s redirection parameter support is useful when completion must land on a scoped route, e.g. a tenant dashboard, a localized page, or a resource-specific summary. Prefer named routes and associative parameters rather than manually concatenating query strings.
• Pattern: service/action per step. Put business logic in actions/services and call them from the step handler. The wizard controls flow; the actions control domain changes.
• Pattern: draft persistence. For longer flows, persist draft data after each step and key it to the authenticated user/session. This supports resuming after accidental navigation or login refresh.
• Integration tip: authorize each step. Add middleware/policies around the wizard routes and re-check ownership on every step, not only on entry.
• Integration tip: use events for completion. Emit a domain event when the wizard completes and let listeners handle notifications, provisioning, or analytics.

Gotchas and Tips

• v4.5.0 is additive. The new redirect-parameter support is a feature, not a breaking change. Existing redirects should continue to work, but confirm your redirect targets still match the expected route signatures.
• Do not assume parameters persist across every step. The release note is specifically about redirection passing parameters. If intermediate step URLs need tenant/locale context, verify the package carries that context or add it explicitly to your route generation.
• Validate redirect parameters. When passing a return_to or URL-like parameter, validate against allowed hosts/paths to avoid open-redirect issues. Prefer route names plus scalar IDs over arbitrary URLs.
• Watch route parameter names. Use named route parameters consistently. A mismatch between the redirect parameter key and the route definition will fail only at redirect time and can be easy to miss in tests.
• Session and multi-tab behavior are common failure points. Two open wizard tabs can overwrite each other’s draft state. If that matters, key state by wizard instance or persist a version/timestamp.
• Debug redirect issues at the route layer. Use route:list, inspect the generated redirect URL, and assert redirects with parameters in feature tests. Log the final redirect target when diagnosing “wrong page after completion” bugs.
• Test the completion path explicitly. Add a feature test that completes the wizard and asserts both the redirect route and its parameters, especially after upgrading to v4.5.0.
• Extension points to check first: custom step resolver, redirect callback/config, step persistence driver, and view rendering hooks. These are usually the cleanest places to adapt the package without forking it.