Novachecklists Laravel Package

Getting Started

Install and inspect before wiring anything up.

composer require e2consult/novachecklists

Before you go further, open vendor/e2consult/novachecklists/composer.json and check the version constraints. As of the last release (2019-10-20) this package targets the Laravel 5.8/6.x + Nova 2 era. If your app is on Nova 3+, Composer will likely refuse to install it, or install it into a codebase where the field's JS asset was never built for your Nova version. Plan for a fork-and-fix rather than a clean install.

First place to look: the package's src/ directory and README.md in that order. A checklist package almost always boils down to (a) a Nova field class backed by a JSON or text column, (b) a HasChecklists-style trait, (c) a migration for a checklist_items table, and (d) a config file overriding the item model. Confirm which of those exist before designing around them.

Minimal wiring:

1. Publish assets and config: php artisan vendor:publish --provider="E2Consult\NovaChecklists\NovaChecklistsServiceProvider" (verify the provider class name from composer.json's extra.laravel.providers).
2. Run the package migration to create the items table.
3. Add the trait to the model you want checklists on.
4. Add the field to that model's Nova resource.

First use case: a per-resource task list — e.g. an onboarding checklist on a Client resource, or QA steps on a Deployment. That is the shape this package is built for: a repeatable list of toggleable items attached to a single Eloquent record, edited inline in Nova.

Implementation Patterns

Field-on-resource pattern (the happy path). One checklist per model instance, items stored in the package table keyed by model type + id. Add the field to fields() and let Nova render the checklist UI. Good for "steps to complete before closing this ticket" style workflows.

Trait + relation pattern. If the trait exposes a checklists() or items() relationship, you can drive the checklist from outside Nova too — seed defaults on model creation via an observer, or recompute completion percentage in a computed Nova field. This is the pattern that makes the package useful in application code rather than just as a UI widget.

Template checklists. For repeatable workflows, keep a canonical checklist as config (or a checklist_templates table) and clone it into real items on created. This avoids hand-building items in every Nova resource and gives you a single place to update process.

Progress surfacing. Expose a completion or progress accessor on the model and render it as a Progress field or a badge column in the index. The checklist becomes meaningful at the resource-index level rather than only after you open a record.

Authorization. Gate item toggling with the parent model's Nova policy (update ability). If the package ships its own controller for the AJAX toggle, check whether it calls authorize() — 2019-era Nova packages frequently did not.

Integration tip: if you need checklists across several models, use the polymorphic shape (checkable_type / checkable_id) rather than duplicating columns. If the package doesn't support morphs natively, the trait is usually the place to add it.

Gotchas and Tips

It is effectively abandoned. Nine stars, zero dependents, last release 2019. Treat it as a reference implementation you own, not a dependency you track. Fork it into packages/ with a path repository before you build anything real on it.

Nova asset compilation is the first wall. Nova 3+ requires fields to build against laravel-nova via nova.mix.js and webpack.mix.js. A 2019 field ships pre-built JS for Nova 2. You will need to add the mix config, run npm install && npm run prod inside the package, and register the built asset in NovaServiceProvider::serving(). Budget a day for this alone.

Composer constraint conflicts. Expect laravel/framework: ^5.8|^6.0 and laravel/nova: ^2.0. Fork and relax them; the PHP code is usually compatible with Laravel 9/10 since it's mostly Eloquent and simple controllers.

JSON column casting. If items are stored as a JSON blob on the parent model, remember to cast ('checklist' => 'array'). Without it you get strings back and in_array checks silently fail. Also watch MySQL 5.7 strict mode if the column has no default.

Ordering. Check whether the package has a position/order column. If not, add one — unordered checklists are unusable in practice and reordering after the fact means writing your own sort UI.

Nova actions bypass field saves. If you're using actions to bulk-complete items, remember actions hydrate and save the model but do not go through the field's fillUsing. Write the action's handle against the relation directly.

N+1 on the index. Rendering a completion badge per row will lazy-load items for every record. Eager-load in the resource's indexQuery or compute progress via a withCount subquery.

Debugging checklist rendering. Run php artisan nova:publish, then php artisan config:clear && php artisan view:clear. If the field renders empty, check storage/logs/laravel.log for the package's toggle endpoint 404ing — the route registration in the service provider is the usual culprit after a Nova upgrade.

Extension points worth keeping: the config's model override (swap in your own ChecklistItem subclass for custom behaviour), the field's resolveUsing/fillUsing (to normalize data shapes),and the trait (to add observers, defaults, and morph support). Everything else in a package this size is best replaced than patched.