Nova Wizard Laravel Package

Technical Evaluation

Architecture fit. zareismail/nova-wizard is a Laravel Nova field/tool add-on, not a general Laravel form library. It is a presentation-and-navigation layer that slices the flat array returned by a resource's fields() method into ordered, named steps rendered inside Nova's existing form. Practically, this makes it a fit for exactly one scenario: a team already standardized on Nova as its back-office CRUD layer, with an oversized create/edit form (identity → address → billing → review) that operations staff find error-prone or hard to train on. It is a poor fit for anything customer-facing, regulated, or revenue-critical, and it is meaningless for teams not running Nova.

Integration feasibility. The surface area is small: Composer install, possible Nova tool registration in NovaServiceProvider::tools(), optional asset publishing, and one base wizard class that declares steps as arrays of native Nova fields. Because wizard steps return standard Nova fields, existing policies, store()/update() behavior, lenses, and actions are preserved — the wizard reshapes fields() during create/update rather than introducing a parallel resource. A two-step proof of concept on one representative resource should surface the majority of integration questions (state handling, validation scoping, file uploads) within a day or two of engineering time. Feasibility is gated less by complexity than by version compatibility and thin documentation.

Technical risk. Medium-to-high, driven entirely by ecosystem health rather than conceptual difficulty. Signals: 14 stars, zero dependents, last release August 2023, single-maintainer profile, MIT license with no commercial support, and no visible evidence of CI or tests. The concrete risk is Nova major-version drift — Nova 4 (Vue 3) and Nova 5 altered tool bootstrapping and the asset pipeline, so a 2023-era package is plausibly Nova 4-only. There is also a functional question of whether per-step validation is enforced server-side, which matters for both data integrity and authorization.

Key questions to resolve before committing.

• Which Nova major versions does composer.json constrain, and which Laravel/PHP versions are actually tested?
• Is there a committed dist/ build, or must we compile assets with a matching Node/Vite toolchain?
• Is submission a single POST at the end, or per-step? (This determines whether Nova File fields and standard validation behave normally.)
• Are wizard steps declared server-side as standard Nova fields, or is there a custom Vue component surface we would inherit maintenance for?
• Is validation and authorization enforced server-side, or only as client-side gating during navigation?
• How is wizard state handled on refresh and back-navigation — client-only, session, or persisted draft?
• What is the maintainer's issue response pattern, and is a fork acceptable if the flow becomes important?

TPM recommendation. Approve only as a timeboxed spike for internal, low-blast-radius admin wizards, with a documented fork-or-replace plan before anything depends on it in production.

Integration Approach

Stack fit. Requires Laravel plus a licensed, pinned Nova installation. Best fit: teams whose admin CRUD is already on Nova and who would otherwise hand-roll multi-step Vue form components. Poor fit: teams not on Nova, teams tracking the newest Nova major, or any workflow with customer-visible, compliance, or revenue exposure.

Migration path. No schema or data migration is expected, since the wizard is a UI-path swap over an existing resource; the notable exception is introducing draft persistence columns if per-step state saving proves necessary. Recommended sequence:

1. Version feasibility check — read composer.json against target Nova/Laravel/PHP; inspect resources/js/ for Vue 2 vs. Vue 3 idioms; confirm whether a prebuilt dist/ exists.
2. Sandbox POC — install on a branch, register assets, rebuild one existing create form as a two-step wizard using the resource-decoration pattern (swap fields() only during create/update; leave index and detail untouched).
3. Validation and authorization review — confirm the full ruleset is enforced server-side on final submit, and that policies apply to all wizard-submitted attributes, not just the base resource.
4. UAT with actual admin operators — measure completion time and error rate against the current form; this is the evidence that justifies keeping it.
5. Feature-flagged rollout — behind a per-resource toggle or Nova tool flag so a single resource can be reverted without a deploy.
6. Documented rollback — remove the package, restore prior fields(), pin the exact version in composer.lock.

Compatibility and sequencing decisions.

• Prefer single-POST, client-only submission for a lightly maintained package: one endpoint, one ruleset, no server round-trips to break, and Nova File fields behave normally. Reserve server-side per-step state (session or draft_* columns) only where step N fields genuinely depend on step N-1 inputs — and accept that as the heavier, fork-prone path.
• Keep steps as small, individually testable PHP methods returning Nova field arrays, with conditional branching expressed in plain PHP rather than a JS config array.
• For multi-model flows (create User + Profile + Subscription), collect all fields in the wizard and perform the write inside DB::transaction() in store() or a custom controller — never create intermediate models per step, or abandoned flows orphan rows.
• Non-CRUD flows (imports, onboarding questionnaires) belong on a Nova tool page or lens posting to a custom controller, not forced into a resource form.

Operational Impact

Maintenance. Assume ownership. Budget for compatibility testing on every Nova/Laravel/PHP upgrade, periodic upstream health checks against a single maintainer, and a likely maintained fork if the workflow earns its keep. The first Nova major upgrade after adoption is the decision point: patch forward, fork, or replace. Assign a named internal owner and a short runbook covering install steps, asset publish tag, upgrade smoke test, and rollback.

Support. GitHub issues only — no SLA and no security-response guarantee. MIT licensing is permissive enough to fork and vendor-patch, which is the real mitigation. Do not route regulated or revenue-critical workflows through it, and treat a public CVE with no upstream response as a remove-and-replace trigger rather than a patching exercise.

Scaling. Admin wizard throughput is low-concurrency by nature, so application scaling is not the primary concern. Watch instead for request payload size on large multi-step forms, file-upload handling and orphan cleanup, server-side validation coverage for every step's fields, and partial-write behavior if per-step persistence is ever introduced. The realistic scaling limit is organizational: each additional wizard increases the fork surface you own.

Failure modes and mitigations.

• Nova upgrade breaks asset registration or the Vue component → smoke-test the wizard after every Nova/Laravel bump; pin versions.
• Client-only validation bypassed → enforce the full ruleset in a FormRequest on final submit; treat per-step validation as UX, not security.
• "All steps validate at once" on submit → scope rules to the active step or use sometimes/nullable until final submit.
• Wizard state lost on refresh or back-navigation → accept for short wizards; otherwise persist drafts to session or DB.
• Orphaned uploads or partial rows → transactional writes, idempotency keys, scheduled upload cleanup.
• Authorization gaps on custom step fields → verify policies cover wizard-submitted attributes, not just the base resource.
• Debugging opacity → inspect Vue props/state in DevTools and log the serialized payload before it reaches the model; most "wizard won't submit" bugs are payload or asset-pipeline issues.

Ramp-up. Low for Laravel/Nova developers — this is a layout and navigation layer, so existing Nova field knowledge transfers directly. Medium for teams without Nova experience, and higher than the star count suggests for everyone, because documentation is thin: the source in src/ and the README are effectively the spec. Allocate POC time to read src/ end to end and capture internal usage patterns so the second wizard is materially cheaper than the first.