Nova Tooltip Field Laravel Package

Getting Started

This release (v1.0.2) is a compatibility bump: it adds support for recent Laravel Nova and PHP versions. There are no new features or API changes called out, so treat it as a maintenance update to your dependency constraints rather than something that changes how you use the package.

1. Check the constraint change before upgrading. Open the package's composer.json on the tagged release and compare its require block with the version you have installed:

   composer show vendor/package --all | head -40
   composer why vendor/package
   

   Confirm your laravel/nova and php versions now fall inside the supported range. If you are on an older Nova major or PHP 7.x, verify whether that combination is still allowed or was dropped.

2. Upgrade in a branch.

   composer require vendor/package:^1.0.2 --with-dependencies
   php artisan optimize:clear
   

   Because this touches framework-level constraints, let Composer resolve laravel/nova alongside it — do not pin Nova manually unless you have a reason to.

3. Republish and re-register if needed. If the package ships config, migrations, or compiled assets, run the publish tag and migrate:

   php artisan vendor:publish --tag=<package-tag> --force
   php artisan migrate
   

4. First use case. The fastest smoke test is to boot Nova and open the page where the package surfaces (a tool in the sidebar, a card on the dashboard, or a field on a resource detail screen). If it renders and its routes respond, the version bump did its job.

Where to look first when something is off: storage/logs/laravel.log, your app/Nova/NovaServiceProvider.php registration block, and the package's composer.json constraints — in that order.

Implementation Patterns

• Register once, in NovaServiceProvider. Tools go in tools(), cards in cards() (or a dashboard's cards()), resource tools in the resource's tools() method. Keep the registration in one place so upgrades are a one-line diff.
• Pin the package in composer.json, not composer.lock only. Since v1.0.2 exists to widen version support, use a caret constraint (^1.0) so future compatibility bumps arrive without ceremony, and let your lockfile hold the exact build.
• Gate everything. Wrap tool/card visibility in canSee() / authorize() against a policy or Gate. Nova tools are full pages with their own routes; relying on the sidebar hiding them is not authorization.
• Isolate the package behind your own thin wrapper when it exposes config or formatting logic. A small service class or Nova field subclass means a future breaking release is a one-file change instead of a grep across resources.
• Test the upgrade in CI with the same PHP image as production. The whole point of this release is version support; a CI matrix that includes your actual Nova major and PHP minor is the only way to catch a mismatch before deploy.
• Keep a short upgrade runbook in the repo (composer command, publish tags, cache clears, migration step). Compatibility releases land quietly, and a runbook makes them a two-minute task.

Gotchas and Tips

• "Added recent versions" does not mean "dropped old versions." Read the require block rather than assuming. If support was added but not removed, you can defer the upgrade; if constraints moved up, an old PHP runtime will now fail composer update with a confusing resolution error.
• Nova's own version constraint is the usual culprit. Conflicts almost always surface as laravel/nova dependency errors, not as errors naming this package. Run composer why-not laravel/nova <version> to see who is blocking.
• Clear compiled views and caches after upgrading. php artisan optimize:clear plus php artisan nova:publish resolves the majority of "the tool disappeared / assets 404" reports after a Nova-side bump.
• Asset compilation is separate from Composer. If the package ships a built JS bundle, a PHP-side upgrade will not rebuild it — check the release assets or run the package's build step if the UI looks stale.
• Config cache hides published config changes. vendor:publish --force does nothing visible until php artisan config:clear, which trips people up when they expect new defaults to appear immediately.
• Debugging visibility problems: check canSee() return values first, then route registration (php artisan route:list | grep nova), then the browser network tab for 403s. Nova swallows a lot of errors into a generic 403.
• Extension point worth knowing: most Nova packages expose a config file with a middleware or authorization key. If this one does, prefer extending that over overriding routes — it survives minor releases far better.
• Watch for a follow-up patch. Version-support releases often ship a v1.0.3 shortly after to fix an over-tight or under-tight constraint. If you hit a resolution conflict on v1.0.2, check for a newer tag before pinning workarounds.