Nova Boolean Group Field Laravel Package

Technical Evaluation

Architecture fit

This is a Laravel Nova custom field — an admin-layer UI extension, not a runtime service, API dependency, or domain model. Its architectural footprint is deliberately shallow: it renders a grouped checkbox control in a Nova form and persists selections as a JSON/array attribute on an Eloquent model.

That makes it a good fit under a narrow set of conditions:

• The product already runs Laravel + Nova for back-office administration.
• The domain concept is a closed, small set of booleans (roughly 4–8): notification preferences, permission bundles, feature flags, module access, onboarding steps.
• The flags are an admin convenience, not a canonical business entity.

It is a poor fit when grouped booleans need per-flag audit history, conditional logic, frequent expansion, customer-facing controls, compliance-grade permissioning, or multi-tenant isolation. At that point the JSON attribute becomes a liability — the package is not the problem, the storage shape is — and the correct move is a user_preferences-style table or first-class model.

Integration feasibility

Superficially high: composer require, a nullable JSON column, an array cast, and a field registration in the Nova resource. The real feasibility questions are less obvious and need to be answered from the source before any commitment:

• Does it extend Laravel\Nova\Fields\BooleanGroup, or does it ship its own Vue components and frontend conventions?
• Are assets prebuilt in dist/, or does the host app need a Node build step? A missing dist/ renders an empty div with no console error — a silent failure that costs engineering hours.
• Which methods does it add over native (options(), defaults, layout)? The README is thin; vendor/.../src/ is the actual documentation.
• What does composer.json constrain for php, laravel/framework, and nova? Last release is March 2024, so Nova 4.x is the safe assumption and Nova 5 must be smoke-tested, not assumed.

Technical risk

The dominant risk is maintenance, not correctness. Signals: 7 stars, zero dependents, a single release note in v1.0.3 that is only a changelog link, and no visible test suite. There is no vendor support path and no community backstop. Concretely:

• Nova upgrade risk (high): custom fields depend on frontend conventions that shift between Nova majors. Every Nova bump becomes a regression-test event for this field.
• Silent persistence failures (high likelihood, low severity): missing $fillable/$guarded or a missing array cast produces a form that saves nothing or an array_merge that fails obscurely. These are configuration risks the team controls, but they are the most common confusion point.
• Unauthorized-key writes (medium): JSON columns accept whatever the form posts; without a Rule::in on keys, typos persist.
• Field-level authorization (medium): small packages frequently skip or incompletely implement authorize(). This must be verified, not trusted.
• Abandonment (medium): small, MIT-licensed, low-adoption packages may need patching or forking. Exit cost is low only if references are wrapped and the storage format is documented.

Key questions

1. Are we on Nova 4 or 5, and has anyone proven this field round-trips on our exact version?
2. Does the package extend native BooleanGroup — and is its storage format byte-compatible with native, so rollback is a one-line change?
3. Are frontend assets prebuilt, or does this add a Node build dependency to our deploy pipeline?
4. Does field-level authorize() work, and does it apply to the field rather than only the resource?
5. Who owns this dependency — named engineer, pinned version, documented fallback?
6. Is the option set stable and small, or is it already trending toward per-flag metadata (the migration trigger)?

Integration Approach

Stack fit

Requires Laravel + Nova already in place. Do not add Nova to obtain this field — the cost/benefit collapses immediately. Verify composer.json constraints against our PHP, Laravel, and Nova versions before writing any code. Treat Nova 4.x as the supported baseline and Nova 5 as unverified until proven.

Migration path

For a new attribute (the recommended entry point), the path is short:

1. Add a nullable JSON column (jsonb on Postgres) and the array cast in the same commit — never the cast alone, never the column alone.
2. Register the field through a thin internal wrapper, not directly across resources.
3. Prove round-trip on a disposable resource: create, toggle, save, reopen.
4. Only then roll out to additional resources.

For swapping out native BooleanGroup on an existing column, the path is different and stricter: prove read/write parity on a disposable resource first. If formats diverge, write a one-time backfill and keep the old field live until parity is demonstrated. Do not migrate data on the assumption of compatibility.

Compatibility

• Storage: array/JSON, matching native Nova conventions if we are lucky; verify, don't assume.
• Validation: add explicit nullable, array, and a key-whitelist rule. Guard the "submit with nothing checked" path, which can yield null rather than an all-false object.
• Read side: normalize on read by merging stored values over defaults, so adding a fourth option needs no backfill migration. This is the highest-leverage habit with JSON-column fields and also what makes rollback survivable.
• Assets: confirm dist/ exists in vendor before deploy.

Sequencing

1. Spike (half day): read source, confirm namespace, inheritance, asset strategy, and constraints.
2. Wrapper: build App\Nova\Fields\PreferenceGroup with options sourced from config, nullable/array rules, key whitelist, and a resolveUsing defaults merge. Keep direct package references confined to this one file.
3. Pilot: one non-critical admin screen, fixed small option set, hideFromIndex() plus a displayUsing readable summary.
4. Tests: a feature test posting the payload through the Nova endpoint and asserting stored JSON — the cheapest insurance available given zero dependents and no upstream suite.
5. Authorization pass: confirm restricted users cannot edit the field.
6. Document: record the storage format in the repo and the one-line revert to native.
7. Expand only after all of the above, and only to settings screens of comparable blast radius.

Operational Impact

Maintenance

Ongoing cost is low in engineering hours but not zero in attention. The package is effectively unmaintained-by-default: 7 stars, zero dependents, one thin changelog release, no visible tests. Plan on the team absorbing the regression surface. The wrapper pattern converts a potential multi-file refactor into a one-file change, and that is the single most important operational decision here.

Support

There is no vendor support. Internal ownership must be explicit: a named engineer, a pinned version in composer.json, and a documented fallback to native BooleanGroup. Without that, this becomes an orphan dependency discovered during a Nova upgrade under time pressure.

Scaling

Scaling concerns here are not traffic — this is admin UI — they are design scaling:

• Option-set growth: 4–8 flags read well; 20 do not. Growth in the option list, or demand for per-flag metadata (labels, descriptions, timestamps), is the migration trigger to a proper model, not a reason to add another ->options() entry.
• Tenancy: JSON columns do not isolate per tenant. If multi-tenant settings appear on the roadmap, this pattern does not scale to it.
• Consumer surface: do not leak the JSON object into public API resources. Shape flags explicitly in the API resource so the storage shape stays an internal detail.

Failure modes

Ramp-up

Low for any engineer already fluent in Nova: the API mirrors native BooleanGroup, so the field itself is minutes of work. The learning is in the JSON-column discipline — defaults-merge on read, key whitelisting, storage-shape separation from API contracts — and in the rollout discipline: pin, wrap, test, document the exit ramp. Budget a half-day spike plus one focused day for wrapper, pilot, and test. The larger organizational task is the decision boundary: framing this as an internal admin efficiency lever with a named owner and a pilot scope, and not letting it drift into a customer-facing or compliance-adjacent dependency without a deliberate re-evaluation.