Nova Toolbar Tools Laravel Package

Getting Started

• Install with composer require gabelbart/nova-toolbar-tools. Because the package has essentially no adoption (0 stars, 0 dependents), don't trust the README alone — open src/ and the service provider first; that is the real documentation.
• Confirm what auto-discovery registers. In app/Providers/NovaServiceProvider.php, look at tools() and resources() — a toolbar package typically plugs into one or both. If nothing shows up in the Nova sidebar, dump Nova::availableTools(request()) to see whether the package's provider ran.
• Publish anything the package ships (config, migrations, assets) before first boot:

  php artisan vendor:publish --provider="Gabelbart\NovaToolbarTools\ToolbarToolsServiceProvider"
  php artisan config:clear && php artisan nova:publish
  

• First usable case: add a single toolbar tool that links to an internal Nova page (e.g. /resources/users?status=active) or an external dashboard URL, confirm it renders in Nova's nav/page header, then add a second item to verify ordering and grouping behavior before building anything real on it.

Implementation Patterns

• Toolbar tool = a nav entry / button. Create a class extending the package's base tool, implement name(), icon(), and either a url() or a component() for a custom view. Keep it thin — a label, an icon, a destination.
• Toolbar resources = shortcuts into resource screens. Use them for "quick create", "jump to filtered index", or admin-only resource links. Point the URL at Nova's existing index with a query string (/resources/orders?status=pending) instead of rebuilding filtering in the toolbar.
• Group by domain, not by type. One toolbar for "Support" (tickets, refunds, escalations), one for "Content" — this matches how Nova's sidebar already organizes tools and keeps the bar scannable.
• Authorization per item. Implement authorize() / canSee() on each tool and delegate to policies ($user->can('viewAny', Order::class)). Never rely on the destination resource's guard to hide the link — a visible link that 403s is worse than no link.
• Ordering. Prefer the package's priority/sort method if one exists; otherwise the order of entries in tools() is usually the render order. Keep the order intentional — recent/relevant first.
• Stateful actions go through controllers. If a toolbar button needs to do more than navigate (mark all read, trigger a sync), have the tool link to a small Nova tool page or a named route, and put the logic in a controller/action. Don't cram it into the tool's render().
• Localize labels. Wrap name() in __('toolbar.support'); these strings are user-facing on every page and are the easiest thing to retrofit later.
• Render-time data must be cheap. If a toolbar item shows a badge ("12 open tickets"), fetch it in a cached accessor — Nova renders the menu on every page load, so an un-cached count query multiplies across the whole admin.

Gotchas and Tips

• Low adoption means no safety net. No StackOverflow answers, few issues, and the GitLab repo (jacobfricke/nova-toolbar-tools) doesn't match the composer vendor (gabelbart/...). Verify you're pulling the repo you think you are, and read the tagged release you installed.
• Pin against your Nova major. Tools and resources break across Nova versions; check composer.json's laravel/nova constraint and lock the package version. Test after every Nova upgrade.
• Global render cost. Anything executed in a tool's render/name() runs on every Nova page. Cache counts, avoid queries in constructors, and don't instantiate heavy services in tools().
• Auto-discovery can silently fail. If the toolbar doesn't appear, check config/app.php discovery cache (php artisan package:discover), and confirm the provider is listed when config:cache is active — cached config hides new publishing/settings changes.
• Icons render blank, not error. Nova expects specific icon names/HTML; a typo gives you an empty space with no console warning. Copy icon strings from an existing Nova tool.
• Authorization vs. visibility. A missing authorize() exposes the link to everyone; a correct one hides it. Test with a non-admin user early — this is the most common toolbar bug.
• Asset staleness. After changing tool views or config, run php artisan nova:publish and rebuild assets; a stale public/vendor/nova masks UI changes and sends you debugging PHP that was never the problem.
• Vendor edits are a trap. If you need custom ordering, badges, or a different render, subclass the package's base tool and override the method rather than editing vendor/. With no maintainer traffic, you will eventually be patching this yourself.