Nova Checkboxes Field Laravel Package

Getting Started

The v5.0 release is a compatibility cut for Laravel Nova 5.0 — treat it as a major upgrade of the host dependency, not a feature drop. Start by confirming your stack can take it:

php artisan --version        # Nova 5 targets Laravel 11+
php -v                       # PHP 8.2+
composer show laravel/nova   # must be ^5.0

Then pull the matching major of this package:

composer require <vendor>/<package>:"^5.0" -W
php artisan vendor:publish --provider="<Vendor>\<Package>\<Package>ServiceProvider" --tag=config
php artisan migrate
php artisan nova:publish

Where to look first: the package's src/ service provider (boot/register), its config/<package>.php, and the dist/ bundle — if a new dist is present, the JS side was rebuilt for Nova 5 and you should not carry over an old published asset set. First use case: register the tool in app/Providers/NovaServiceProvider.php and confirm it renders inside a Nova 5 dashboard before wiring any business logic:

public function tools()
{
    return [
        new \<Vendor>\<Package>\<PackageTool,
    ];
}

If the package exposes cards, fields, or actions instead of a tool, register one of each in a throwaway resource and verify they render — that single smoke test catches most of the Nova 5 breakage.

Implementation Patterns

Tool registration and menu placement. Keep registration in NovaServiceProvider::tools() and control visibility with canSee/canRun callbacks rather than hiding in the UI layer. Authorisation belongs in policies; Nova 5 evaluates them consistently across tools, actions, and fields, so a Gate::define in a service provider is the cleanest place for package-specific abilities.

Configuration over forking. The published config is the intended extension point. Override endpoints, pagination, cache TTLs, and feature flags there; every fork of the package's Vue components is a future upgrade cost you'll pay again at Nova 6.

Upgrade workflow for the major bump. Do this on a branch, in this order: bump the package, run composer update -W, php artisan nova:publish, php artisan optimize:clear, then walk every screen the package touches. Committing the rebuilt public/vendor/<package> assets alongside the composer.lock change keeps deploys deterministic and makes the diff reviewable.

Coexistence during migration. If you can't move Nova itself yet, pin the package to ^4.0 — the two majors are not intended to run side by side, and the asset bundles will collide in public/vendor. Where a package version supports both hosts, prefer an explicit constraint over * so a composer update can't silently drag Nova forward.

Testing integration. Nova's own test helpers plus Nova::actingAs() cover the HTTP surface. Assert authorisation outcomes (403 vs. hidden) separately from rendering — those are the two things that regress most often across a Nova major.

Gotchas and Tips

• Version alignment is the whole story. Package v5 ↔ Nova v5, full stop. The most common post-upgrade failure is a stale public/vendor/<package> bundle from the v4 build being served against Nova 5's JS — the tool loads but silently renders nothing, or throws a console error you'll never see in PHP logs. Clear it and republish before debugging anything else.
• Published config is not merged. New keys added in v5 won't appear in an existing config/<package>.php. Diff the package's config against yours after upgrading; missing keys usually fall back to null rather than a sane default.
• Caches lie. config:clear, view:clear, and route:clear before you file a bug. Nova's own caches plus OPcache on the published assets produce "the upgrade did nothing" reports constantly.
• Auth failures look like render failures. A blank tool panel is frequently a policy or canSee mismatch, not a frontend problem. Check storage/logs/laravel.log and the network tab for a 403 before touching Vue.
• Private distribution. Nova packages are usually behind a licensed Composer repo; CI needs NOVA_USERNAME/NOVA_PASSWORD (or a auth.json secret) or the build fails at install, not at runtime.
• Release notes are thin. "Update for Nova 5.0" tells you compatibility landed but not what changed internally. Read the diff on the service provider and any published migrations before deploying — silent migration or config changes are the realistic risk in a compat-only major.
• Extension points to prefer if you need behaviour the config doesn't cover: a subclassed tool/field registered in your own provider, or a Nova event listener, rather than editing vendor/.