Nova Toggle Laravel Package

Technical Evaluation

Architecture fit. davidpiesse/nova-toggle is a presentation-layer-only package: a single Nova field class that extends Nova's core Boolean field plus a compiled Vue component registered through Nova's asset pipeline. It writes nothing to the database schema, introduces no service, no queue, no external call, and no data model. For a TPM this is the simplest possible architectural profile — a UI substitution inside an existing paid admin panel. The blast radius is bounded to Nova resources that opt in by changing one line (Boolean::make() → Toggle::make()). There is no value outside Laravel Nova, so the addressable footprint is the subset of the team that already licenses Nova.

Integration feasibility. High, with one hard gate: Nova major-version compatibility. The last release is 2022-07-22, which places it in the Nova 4 / Vue 2 era; Nova 5's Vue 3 + Vite pipeline is the documented failure mode. Feasibility therefore collapses into a single verification task — inspect the package's composer.json for an explicit laravel/nova constraint and inspect dist/ for whether a prebuilt bundle exists and which Vue major it targets. If the constraint is absent or wildcarded, that is a red flag meaning the package has never declared what it supports, and the decision becomes "pin and pilot," not "adopt."

Technical risk. Three risks matter at the PM level:

1. Silent render failure (highest severity). A Vue-2 bundle mounted into Vue 3 produces an empty field with a 200 response and clean logs. Data is intact, no error surfaces server-side, and automated tests cannot catch it. This must be caught by a visual QA step in the release checklist, not by the test suite.
2. Single-maintainer abandonment (highest likelihood). One maintainer, no release since 2022, zero dependents, community-only support. Nova's paid support does not extend to third-party fields. Assume unmaintained on day one. Mitigating factor: the package is roughly a hundred lines — one PHP class, one Vue component, one asset — so forking is hours, not weeks.
3. Component-name collision and stale published assets. Two field packages registering the same Vue component name silently win-or-lose on boot order; a stray vendor:publish copy under public/vendor/ can shadow the vendor bundle and mask an upgrade. Both are operational hygiene problems with known remedies, not design flaws.

Key questions for the team before adoption:

• Which Nova major are we on today, and is it in the package's declared constraint (if any)?
• Is a prebuilt dist/ committed, and does it target Vue 2 or Vue 3?
• Does src/Toggle.php genuinely extend Boolean, inheriting default(), rules(), nullable(), fillUsing(), onlyOnForms(), exceptOnForms()? If it reimplements them, field semantics will silently diverge from core.
• Do we actually use inline index editing? If not, the marginal benefit over a checkbox drops sharply and this becomes a cosmetic change.
• Who owns the fork if Nova's next major breaks it, and is that pre-authorized?

Integration Approach

Stack fit. Laravel + Nova, nothing else. Installation is a single composer require. There is no migration, no schema change, no data remediation — the underlying column stays boolean / tinyint(1). Rollback is reverting the import and the make() call. This is close to a zero-cost integration from an infrastructure standpoint; the cost lives entirely in verification and in the ongoing Nova-upgrade obligation.

Migration path. The realistic rollout is mechanical and resource-by-resource:

1. Inventory every Boolean::make() under app/Nova and classify each field.
2. Pilot one non-critical resource — a settings page or taxonomy table, never users.is_active first.
3. Verify all four surfaces plus inline index editing.
4. Confirm default() / rules() parity with Boolean.
5. Roll out per-resource under normal PR review.

Keep a written inventory of which fields are now toggles. It is the bounded QA checklist on every future Nova upgrade and the fastest way to know which workflows to spot-check if something breaks.

Compatibility. Two dimensions:

• Nova major. Pin the exact package version ("1.2.3", not ^1.0) and record the validated Nova version in-repo (docs/nova.md or a comment) so the person doing the next Nova upgrade knows this package is load-bearing.
• Field semantics. Retain Boolean for nullable / tri-state attributes (a two-position switch is the wrong affordance for an indeterminate state), for non-standard trueValue() / falseValue() mappings against string columns, and for fields that are genuinely form answers rather than live operational state.

Sequencing. Deliberately decouple adoption from any Nova major-version work. Land this on a currently-supported Nova major during a quiet sprint, pilot on staging, and register the package on the Nova major-upgrade checklist with a named owner before the first production field goes live. Do not adopt this mid-upgrade-cycle — it converts a routine Nova bump into an ambiguous failure to debug.

Rollback design. Two mechanisms, both worth having:

• A per-resource revert (import + make() call), which is trivially safe because the column type is unchanged.
• A config-flag kill switch via a small field factory (App\Nova\Fields\Flag) that returns Boolean::make() when config('nova.toggles_enabled') is false. This flips the entire surface back to checkboxes without touching every resource — the right lever if a Nova minor upgrade breaks the component mid-sprint.

Operational Impact

Maintenance. Low in effort, non-zero in obligation. The package will not receive upstream fixes, so every Nova upgrade requires re-verifying the toggle surfaces. That cost is small but recurring and unbounded in time — it does not amortize away. The sane endgame, given the package is ~100 lines, is eventually promoting the PHP class and Vue component into an internal acme/nova-fields package. That removes single-maintainer exposure permanently and converts a re-verify-every-upgrade chore into code you own. Pre-authorize that fork path at adoption time so the decision isn't invented mid-incident.

Support. Community-only. No vendor SLA, no paid escalation. The escalation contact must be an internal named owner, written into the adoption record now. Because the code is small and readable, internal support is realistic — but only if someone has actually read src/Toggle.php and the service provider's boot() before the first incident.

Scaling. Effectively flat. The field is a client-side component on an admin panel used by a bounded population of staff — no meaningful scaling dimension. The one scaling-adjacent consideration is breadth of blast radius as adoption grows: ten resources with toggles is a larger QA checklist than one, but a proportionally trivial one. Keep the inventory current as that number grows.

Failure modes and detection. Rank by severity, not likelihood:

• Blank field, clean logs. The dominant failure. Detection is browser-console inspection on the pilot page during rollout and a visual QA step on every release that touches Nova assets. Server-side tests prove persistence and policy, not rendering — a broken Vue component returns 200 with no error. Do not treat a passing test suite as evidence the UI works.
• Lifecycle-critical false state. An unusable is_active toggle is an outage, not a cosmetic bug — if ops staff cannot reach the control, a live workflow is blocked. Route detection through visual QA and the field inventory.
• Accidental production flip. Inline index toggling does not bypass authorization (policy still gates the request), but it does make accidents cheaper: a misplaced click on a listing flips is_published in production. For lifecycle-critical flags, either add a confirmation affordance, move the field to onlyOnDetail(), or ensure the model fires an event so the change is attributable.
• Stale published assets. Looks correct before a Nova bump, broken after. Check public/vendor/ for a shadowing copy before debugging the package.

Diagnostic checklist for a blank field: curl -I the asset URL, confirm the service provider booted (php artisan about), then nova:publish --force and view:clear. A [Vue warn]: Failed to resolve component in the console points at a Vue-major mismatch, not at field configuration.

Ramp-up. Near-zero for engineers: one composer require, one import swap, one pilot resource. The real ramp-up is organizational, not technical — establishing the dependency policy this package exemplifies. Pin the exact version, name an owner, write the fork procedure and escalation contact into the adoption record, and add the package to the Nova upgrade checklist. Doing that once turns the next small single-maintainer UI dependency into a ten-minute call instead of a fresh debate.

Positioning for planning purposes. This is a back-office UX investment, not roadmap scope. It does not touch customer experience, revenue, or product surface. It is tactical, adopt-and-move-on, and should never block a Nova major-version upgrade. The correct framing to stakeholders: "we are taking on a small, bounded, permanently-owned maintenance obligation to make ops staff measurably less likely to mis-click production-adjacent flags." If inline index editing is not actually part of how the team works, the value proposition largely evaporates and a plain checkbox is the better answer.