Nova Json Laravel Package

Getting Started

Treat 64robots/nova-json as a small Nova form/detail field for editing JSON stored on a model. It is archived, so first verify that its Nova/Laravel constraints match your app before adopting it. It does not replace model casts, migrations, or validation.

Minimal setup:

1. Confirm compatibility before installing:

   • Check the package composer.json for Nova, Laravel, and PHP constraints.
   • Check the README and source for the exact namespace and expected value type.
   • If you are on Nova 4/5, test carefully; archived Nova fields often rely on older asset/build conventions.

2. Add a JSON-capable column if you do not already have one:

Schema::table('projects', function (Blueprint $table) {
    $table->json('settings')->nullable();
});

3. Cast the attribute on the model:

protected $casts = [
    'settings' => 'array',
];

4. Add the field to the Nova resource. Verify the import from the README; it is commonly used as:

use R64\NovaJson\NovaJson;

public function fields(Request $request)
{
    return [
        NovaJson::make('Settings')
            ->rules('nullable', 'json')
            ->hideFromIndex(),
    ];
}

5. If the package ships publishable assets, publish them according to its README and clear Nova caches.

Where to look first:

• The package README for the exact field API and namespace.
• src/NovaJson.php or the main field class for resolve, fill, and default behavior.
• The Vue component under resources/js to understand whether it expects a JSON string or an already-decoded array.
• composer.json for Nova compatibility.
• Your model casts and database column type, because most failures come from a mismatch between raw JSON strings and cast arrays.

First useful use case: a settings, metadata, or payload column on a resource. Use the field for occasional admin edits, hide it from index views, and keep normal application reads/writes on the model cast rather than on the Nova field.

Implementation Patterns

Use the Nova field as an editing surface, not as your application’s JSON layer. Keep encoding, decoding, defaults, and validation in the model/domain layer so API and Nova behavior stay consistent.

Basic resource pattern:

use R64\NovaJson\NovaJson;

public function fields(Request $request)
{
    return [
        NovaJson::make('Settings')
            ->rules('nullable')
            ->hideFromIndex()
            ->help('Enter a JSON object, for example: {"theme":"dark"}'),
    ];
}

Pair it with a model cast:

protected $casts = [
    'settings' => 'array',
];

If the field expects a raw string but your model cast returns an array, do not blindly add another json_encode. Inspect the field’s resolve/fill methods first. Double-encoding is a common failure mode with JSON Nova fields.

Validation pattern: validate syntax and shape separately. The Laravel json rule checks syntax only; it does not enforce that the payload is an object, has required keys, or uses allowed types.

NovaJson::make('Settings')
    ->rules([
        'nullable',
        function ($attribute, $value, $fail) {
            if ($value === null || $value === '') {
                return;
            }

            $json = is_array($value) ? json_encode($value) : $value;
            $decoded = json_decode($json, true);

            if (json_last_error() !== JSON_ERROR_NONE) {
                return $fail('Settings must be valid JSON: '.json_last_error_msg());
            }

            if (! is_array($decoded)) {
                $fail('Settings must decode to a JSON object or array.');
            }

            if (array_key_exists('theme', $decoded) && ! is_string($decoded['theme'])) {
                $fail('The theme value must be a string.');
            }
        },
    ])
    ->hideFromIndex();

Recommended workflows:

• Use hideFromIndex() for large JSON so index requests and tables stay fast.
• Use onlyOnDetail() or readonly() for audit/history views.
• Normalize empty input in one place: decide whether empty means null, '', or {}. Do not let different screens produce different empties.
• Use a model mutator or accessor when the database column is text instead of native json, or when the package expects a different representation than your cast.
• Keep API resources and business logic reading $model->settings as an array via the cast, not by decoding raw request values.
• For large or schemas-heavy JSON, prefer a dedicated code editor field or a custom Nova field. This package is intentionally thin.

If you need to customize behavior, prefer a small subclass or custom validation rule over editing vendor files:

class ProjectSettingsJson extends NovaJson
{
    public function resolve($resource, $attribute = null)
    {
        parent::resolve($resource, $attribute);

        // Normalize null/empty values for the form here if needed.
    }
}

Gotchas and Tips

• Archived package: no guarantees for new Nova/Laravel/PHP versions, no security updates, and likely no support for modern Nova asset pipelines. Pin versions and avoid adopting it for new critical admin surfaces without a fallback plan.
• Cast vs raw string mismatch: the most common issue is a model cast returning an array while the Nova field expects a JSON string, or the reverse. Check the field source and test create, update, detail, and index screens.
• Double encoding: if the field already encodes on save, adding another json_encode in a mutator can store a JSON string containing JSON. Inspect the stored value directly in the database.
• Empty values: null, '', '{}', and '[]' are not interchangeable. Validation and application code should agree on what empty means.
• Validation scope: json rules only prove syntax. Use custom rules for required keys, allowed types, nested structure, and size limits.
• Search, sort, and filter: JSON columns are not automatically searchable/sortable in Nova. Add custom filters or generated columns if you need querying by JSON keys.
• Database differences: native MySQL/PostgreSQL JSON columns behave differently from text/longText. Confirm how your database stores and returns the value before assuming the field sees a string.
• Large payloads: the field is a text editor, not a schema-aware UI. Large JSON can make forms slow and unwieldy; hide it from index and consider read-only detail views.
• Security: do not render raw JSON as HTML. Treat the payload as untrusted data, apply field authorization, and avoid exposing secrets in JSON columns through Nova.
• Nova asset issues: if the field does not appear or renders unstyled, check published assets, compiled JS, and Nova’s asset registration. Old field packages often break after Nova major upgrades.
• Debugging: inspect the Nova request payload, the field’s resolve/fill behavior, the model cast, and the raw database value. Log json_last_error_msg() when decoding fails.
• Fallback: if compatibility or maintenance becomes a problem, a standard Nova Textarea with JSON validation, or a small custom field built for your Nova version, is often safer than keeping an archived dependency.