Nova Policy Laravel Package

Getting Started

v2.0.0 is a Nova 4 compatibility release; it is the version to use when the host Laravel app is already on Laravel Nova 4. First check composer.json: the app should require laravel/nova:^4.0 and this package ^2.0. If the app is still on Nova 3, do not upgrade this package; stay on v1.

Minimal path:

1. Require vendor/package:^2.0 (use the package’s actual name) in a branch.
2. Publish any config/assets/migrations the package documents.
3. Register the package where Nova expects it: NovaServiceProvider::tools(), cards(), resources(), or on a resource via fields(), actions(), filters(), or cards().
4. Open a low-risk Nova resource/dashboard and verify the package renders, authorizes, and persists data.

First use case: add it to one admin-only Nova resource or dashboard, not every resource, and confirm the Nova 4 UI, menu entry, and authorization behavior before rolling it out broadly.

Implementation Patterns

• Treat v2 as a Nova 4-only integration. Use it for new Nova 4 admin panels and for migrating existing Nova 3 panels after Nova itself has been upgraded.
• Register through Nova’s normal extension points rather than ad hoc routes. Keep menu/navigation and authorization in the same place as other Nova tools, cards, and resources.
• For resource-level packages, attach fields/actions/filters in the resource class; for dashboard tools/cards, register in NovaServiceProvider; for custom tools, verify the tool’s route, menu, and canSee/authorization callbacks.
• Upgrade workflow: upgrade Nova to 4 in a branch, update this package to ^2.0, republish assets/config, run migrations, clear caches, then exercise create/read/update/delete, bulk actions, filters, and dashboard cards.
• Day-to-day, keep config in config/... and environment-specific values out of code; gate visibility with policies/gates so non-admin users do not see the tool/card unnecessarily.
• In CI, test against Nova 4 and the PHP/Laravel versions the app supports; commit the lock file so Nova/package versions do not drift between environments.

Gotchas and Tips

• v2.0.0 is a breaking compatibility line: v2 targets Nova 4 and should not be installed on Nova 3 apps. Pin ^1.0 for Nova 3 and ^2.0 for Nova 4.
• Composer resolution problems usually mean the app’s laravel/nova constraint or private Nova repository credentials are wrong; check composer why-not vendor/package 2.0.0.
• Stale frontend assets are a common Nova upgrade failure. Rebuild/re-publish the package’s assets, clear cached config/routes/views (php artisan optimize:clear), and hard-refresh the browser if a tool/card is blank.
• Re-test Nova 4 menu/navigation and authorization behavior; a tool that appeared in Nova 3 may need menu registration changes or updated canSee logic.
• Debug in this order: storage/logs/laravel.log, browser console/network for 404s on Nova assets, php artisan route:list | grep nova, service-provider registration, then config cache.
• Extension points to prefer: package config, policies/gates, Nova resource classes, custom fields/tools built against Nova 4, and published migrations. Avoid editing vendor files.