Laravel Nova Json Field Laravel Package

Getting Started

• Install with Composer (composer require wamesk/laravel-nova-json-field) and let Nova discover the field; run nova:publish only if your Nova version/setup requires publishing field assets.
• Add the package’s JSON field to a resource’s fields() method and point it at the JSON column, e.g. a settings or configuration column on the model.
• Look first at the README’s named property / parameter API and its dependsOn examples. Those two features define how day-to-day usage works: named inputs map to JSON keys, and dependsOn rebuilds the form when another field changes.
• A good first use case is replacing a growing set of nullable configuration columns with a single JSON column, for example per-device or per-device-type settings edited from one Nova form.
• Make sure the Eloquent model casts the column appropriately ('settings' => 'array' or AsArrayObject) and confirm existing rows contain {} rather than [] or null. Release 1.2.2 handles the null case, but clean data avoids surprises.

Implementation Patterns

• Define the field’s named properties explicitly so each form input has a stable JSON key. This keeps the form self-documenting and avoids storing untyped, ad-hoc JSON.
• Use dependsOn for conditional schemas — for example, showing different configuration inputs based on a selected device type or template. The dependent field should be the one that genuinely determines the structure, not a cosmetic label.
• On update forms, existing JSON hydrates back into the named inputs. On create forms, provide sensible defaults by setting the model attribute before the form loads or by using the field’s default configuration.
• Since 1.2.2, dependsOn sync compares only field IDs. Changing a template name preserves the user’s edits; changing the actual device type rebuilds the structure and intentionally resets values. Design your forms around that distinction.
• Keep persistence in the field’s normal flow. If you customize with Nova’s fillUsing / resolveUsing, ensure the value passed for storage is a JSON object, not a PHP list.
• In API resources and other consumers, decode the JSON column and expose typed keys rather than returning the raw blob.
• For models with existing data, consider a small migration or model accessor that normalizes null/[] values to an empty object before the field reads them.

Gotchas and Tips

• Upgrade to 1.2.2. It fixes two serious day-to-day bugs: parameters silently not saving on records with no prior value, and user edits being reset on every dependsOn sync.
• The 1.2.1 null-value bug is subtle: PHP’s array cast on a null attribute returns [], which serializes to a JSON array. JSON.stringify then drops the named properties set by the form, so the request sends []. If a create form appears to ignore input, inspect the request payload first.
• Watch for JSON array-vs-object drift in the database. An empty JSON column should ideally be {}. [] indicates the old behavior or a misconfigured cast/default.
• Debugging checklist: open browser DevTools and inspect the Nova request payload; check the model cast; check whether the column is null/[]/{}; then check the field schema and the field IDs used by dependsOn.
• Don’t rely on metadata-only changes (such as a template name) to reset dependent values. Since 1.2.2 they won’t; only structural field-ID changes will.
• Test create and update flows separately. The null-attribute persistence bug only surfaced on first save / records without a stored value, so update-only testing would miss it.
• Pin the package version in composer.json and add a regression test that creates a record with no existing JSON value and asserts the named inputs persist.
• Treat the field’s property definitions and dependsOn configuration as the main extension points; reach for custom fillUsing/resolveUsing only when the built-in mapping cannot express your structure.