Nova Textlist Field Laravel Package

Getting Started

This package is an archived, low-usage Nova field. Verify compatibility with your Nova/PHP version before adopting it; if it works, treat it as a small utility field rather than a long-term dependency.

1. Confirm installability

   • Check the README and composer.json for the exact namespace and Laravel/Nova constraints.
   • Try composer require masoudi/nova-textlist-field in a disposable branch. If constraints block it, fork the repo and relax them rather than forcing --ignore-platform-reqs in production.
   • Because the last release was September 2022 and there are no dependents, inspect the field class before using it. It is small enough to vendor into app/Nova/Fields if needed.

2. Add a storage column

   • Expect the field to store a list as JSON or a delimited string. Confirm from the source.
   • For JSON-style storage, use a text or json column, not string:

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

   • Cast it on the model so Nova reads/writes an array:

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

3. Register the field on a Nova resource

   • Use the namespace from the package source. A typical usage looks like:

   use Masoudi\NovaTextlistField\TextList;
   
   public function fields(Request $request)
   {
       return [
           TextList::make('Bullet Points', 'bullet_points')
               ->rules(['nullable', 'array'])
               ->help('One item per line'),
       ];
   }
   

4. First use case

   • Start with a simple string array: bullet points, tags, checklist labels, or short option lists. Avoid using it for structured objects unless you verify the field supports nested data. The safest day-one use is a flat list of strings displayed and edited in Nova.

Implementation Patterns

Flat-list model pattern

Use the field for a flat array column and pair it with an array cast. Validate items as strings:

TextList::make('Ingredients', 'ingredients')
    ->rules(['nullable', 'array'])
    ->rulesFor('ingredients.*', ['string', 'max:100']);

If the field stores a delimited string instead of JSON, adjust the cast and validation accordingly. Read the field’s fill()/resolve() methods to confirm the data shape.

Index and detail display

Arrays rarely render well by default in Nova index tables. Normalize display early:

TextList::make('Tags', 'tags')
    ->displayUsing(fn ($value) => is_array($value)
        ? implode(', ', $value)
        : (string) $value)
    ->onlyOnForms(); // or use a separate formatted field on index

For detail views, either let the field render or replace it with a Text field that joins the array.

Form-only editing with computed display

A common workflow is to edit with TextList but show a polished value elsewhere:

TextList::make('Keywords', 'keywords')
    ->onlyOnForms()
    ->rules(['nullable', 'array']),

Text::make('Keywords', function () {
    return collect($this->keywords ?? [])->implode(', ');
})->onlyOnDetail(),

Migration from comma-separated input

If existing data is a comma-separated string, do not point the field at it without a migration. Normalize first:

$model->keywords = array_filter(array_map('trim', explode(',', $model->keywords)));
$model->save();

Then cast to array and switch the column to json/text.

Fork-and-extend pattern

Given the archived status, the most realistic long-term pattern is to copy the field into your app and own it:

• Copy the field class into app/Nova/Fields/TextList.php.
• Replace the package namespace with App\Nova\Fields.
• Add tests for fill/resolve behavior and empty-state handling.
• Keep the public API (make, rules, displayUsing) close to Nova’s native field conventions so resources do not need rewrites later.

This also lets you add features the package may lack, such as reordering, item-level validation messages, or a separator configuration.

Gotchas and Tips

• Archived package: No fixes for Nova 4/5 API changes, PHP 8.2+ deprecations, or dependency conflicts. Pin the version and audit the source before production use.
• Composer constraint failures: The package may declare old Laravel/Nova versions. Avoid --ignore-platform-reqs as a permanent fix; fork and update composer.json, or vendor the class locally.
• Data shape mismatch: The biggest failure mode is assuming JSON when the field serializes delimited text, or vice versa. Check the field’s resolve() and fill() methods before writing migrations or casts.
• Validation must match storage: If the field stores an array, use array rules. If it stores a string, do not validate as array. Mixed expectations lead to “Array to string conversion” errors.
• Empty values: Normalize null, [], and '' consistently. Add an accessor or mutator if the field returns inconsistent empty states.
• Index table breakage: Nova may try to render an array directly. Use displayUsing or hide the field from index and show a joined Text field instead.
• Nova field lifecycle: Custom fields rely on resolve, fill, and sometimes fillUsing. If the package was built for an older Nova version, test create, update, and detail screens explicitly.
• No community support: With 3 stars and 0 dependents, expect no answers to issues. Keep a local copy and document your changes.
• Extension points: Prefer Nova’s native displayUsing, resolveUsing, fillUsing, and rules methods over editing package internals. If you must edit, fork immediately so upgrades are deliberate.