Navix Laravel Package

Getting Started

1. Install the package with Composer and run the installer:

   composer require <vendor>/navix
   php artisan navix:install
   

2. Look first at the generated routes/navix.php. This is the central place to define navigation batches and items using Navix’s fluent API.
3. Define a minimal first menu batch, for example a main navigation with a home link and one nested group. Check the generated file for the exact fluent method names exposed by your version.
4. Render it in a Blade layout via the navix() helper. Treat the returned value as a NavixCollection, not a plain array.
5. First useful use case: replace hard-coded header navigation with one main batch containing a nested “Products” group, icons, and optional badges.

Implementation Patterns

• Keep navigation definitions centralized. Define shared menus in routes/navix.php rather than scattering links across Blade templates. Use multiple named batches for different surfaces, such as main, footer, account, or admin.
• Use groups for nested menus. Model dropdowns and multi-level navigation with groups, then render recursively in a Blade component or partial. Keep the renderer recursive so nested items and future depth changes are handled consistently.
• Build reusable renderers. Create one Blade component, Livewire component, or custom UI adapter that accepts a NavixCollection and renders labels, icons, badges, URLs, and query parameters. This isolates your views from Navix’s fluent API.
• Use batches for context-specific menus. Resolve the appropriate batch at the layout or component boundary rather than conditionally branching inside every item definition.
• Use label search for command palettes and quick navigation. Navix can search by label, including nested items. Filter the collection, then pass the result to your UI. Normalize labels if your search UX is case-insensitive.
• Integrate with Livewire via computed properties. Return the relevant Navix batch from a computed property or small service method, then render it in the component. Avoid rebuilding menu definitions directly inside Livewire render methods.
• Handle active state in your UI layer. The package provides navigation data; your Blade/Livewire/custom component should compare the current request URL with item URLs and apply active classes.
• Use query parameters deliberately. Add query parameters for campaign tags, filters, or context. Check how existing query strings are merged before relying on them for URLs that already contain parameters.
• Wrap the helper in application code. For larger apps, create a NavigationService or Blade component API that calls navix() internally. This gives you one place to add authorization filtering, analytics attributes, or fallback behavior.

Gotchas and Tips

• Do not assume arrays. Navix returns a NavixCollection with getter and existence methods. Use those methods instead of array access, and check for optional properties such as icons or badges before rendering.
• Search is label-based. Nested label search is useful, but do not expect it to search URLs, badges, or custom metadata unless the package explicitly supports that. Filter other properties through collection methods or your own logic.
• Be careful with per-user menus in routes/navix.php. The generated file is best for static/shared navigation. For role- or permission-specific menus, define the batch closer to the request lifecycle or filter the collection using Laravel gates/policies before rendering.
• Clear caches after definition changes. If menu changes do not appear, run the usual Laravel cache-clearing commands and check whether route/config caching is involved in your deployment.
• Verify package discovery if navix() is missing. Run composer dump-autoload and confirm the service provider/helper is discovered. In unusual deployments, check the package’s installation docs for manual registration.
• Keep batch names stable. Multiple batches are powerful, but renaming a batch can silently break layouts or components that resolve it by name. Treat batch names as part of your UI contract.
• Watch URL and query-string encoding. When adding query parameters, confirm how Navix merges them with existing query strings. Test URLs that already contain ?, fragments, or encoded values.
• Use existence checks for optional UI. Badges, icons, and query parameters should be optional. Render conditionally so menu definitions can stay minimal without producing empty markup.
• Extension point: build your own navigation component. The cleanest extension path is to wrap navix() in a Blade/Livewire component and add active-state logic, permission checks, analytics, and custom markup there rather than modifying package files.