Nova Matrix Input Field Laravel Package

Getting Started

Install the field via Composer:

composer require pavloniym/nova-matrix-input-field

The package uses Laravel auto-discovery; no additional service provider registration is normally required. Ensure your project is running a compatible Nova version (check composer.json constraints).

Add the field to a Nova resource:

use Pavloniym\NovaMatrixInputField\MatrixInput;

public function fields(Request $request)
{
    return [
        MatrixInput::make('Pricing Matrix')
            ->rows(['Basic', 'Pro', 'Enterprise'])
            ->columns(['Monthly', 'Yearly']),
    ];
}

On the Eloquent model, cast the underlying column to an array or JSON so Nova receives structured data:

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

Your first use case is typically a fixed grid of editable values—tiered pricing, feature availability by role, shift schedules, or survey responses—stored as a single JSON column.

Implementation Patterns

• Static matrices – Define rows and columns directly in the Nova resource for stable, known grids. Keep the definitions close to the field for readability.
• Dynamic matrices – Derive rows or columns from application data:

  ->rows(Role::pluck('name')->toArray())
  ->columns(['Read', 'Write', 'Delete'])
  

  Cache or memoize expensive queries if the matrix is large.
• Validation – Use Nova’s rules() with dot notation for nested cell validation:

  ->rules(['matrix.*.*' => 'nullable|numeric|min:0'])
  

  For complex rules, validate in a FormRequest or use ->rulesFor() if the package exposes per-cell hooks.
• Storage and retrieval – Store the matrix as JSON. Access values with array keys if you configure keyed rows/columns, or by index for flat structures. Document the shape for other developers.
• Display customization – Use ->displayUsing() to render a readable summary on detail and index views instead of raw JSON. For index tables, consider a separate computed field or accessor.
• Read-only and disabled states – Use ->readonly() or ->disabled() when the matrix should be visible but not editable (e.g., audit views).
• Defaults – Seed initial values with ->default([...]) for new records. Pair with ->nullable() if an empty matrix is valid.
• Integration with actions – Populate matrices from Nova actions by filling the model attribute before saving. Use the same JSON shape as the field.
• Reusable configuration – Extract row/column definitions into a config file, enum, or class constant when multiple resources share the same matrix structure.

Gotchas and Tips

• JSON casting is mandatory – Without an array or json cast, the field may receive a string or inconsistently shaped data. Double-check the model cast before debugging the Vue component.
• Nested validation – Nova rules for matrix cells need wildcard dot notation (matrix.*.*). A top-level array rule alone will not validate individual cells.
• Empty and null values – Decide whether an empty matrix should be null or []. Use ->nullable() and a default to avoid “array to string conversion” errors.
• Nova version compatibility – Matrix fields are tightly coupled to Nova’s frontend. After upgrading Nova major versions, test the field and review the package’s changelog. Patch releases like v1.0.12 are low-risk, but pin the version in composer.json and review the compare link for Nova constraint changes.
• Asset loading – If the field renders without styles or scripts, run php artisan nova:publish and check whether the package requires publishing assets (vendor:publish). Consult the README for the exact tag.
• Large matrices – Rendering hundreds of inputs can slow the Nova form. Limit rows/columns, lazy-load options, or split into multiple fields.
• Localization and labels – Row/column labels may be static strings. If you need translated labels, generate them via __() in the resource or override the field’s Vue component.
• Debugging – Inspect the raw JSON in the database first. Then check Nova’s field resolution with ->resolveUsing() only if you need custom hydration. Avoid manually json_encode-ing values before the field fills the model.
• Extension points – If the package supports publishing config or views, use those to customize behavior. For advanced needs, wrap MatrixInput in a custom Nova field or override the Vue component rather than modifying vendor files.
• Data migrations – When changing the matrix shape (renaming rows/columns), write a migration or accessor to map old keys to new ones; stored JSON will not be updated automatically.