Module Navigations Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require cvepdb-cms/module-navigations
   

   Publish the package configuration and migrations:

   php artisan vendor:publish --provider="Cvepdb\Navigations\NavigationsServiceProvider" --tag="config"
   php artisan vendor:publish --provider="Cvepdb\Navigations\NavigationsServiceProvider" --tag="migrations"
   php artisan migrate
   

2. Basic Usage Register the navigation service provider in config/app.php under providers:

   Cvepdb\Navigations\NavigationsServiceProvider::class,
   

3. First Navigation Define a navigation in a service provider (e.g., AppServiceProvider):

   use Cvepdb\Navigations\Facades\Navigation;
   
   public function boot()
   {
       Navigation::register('main', function () {
           return [
               'Home' => route('home'),
               'About' => route('about'),
               'Contact' => route('contact'),
           ];
       });
   }
   

4. Displaying Navigation Use the @navigation Blade directive in your layout file:

   @navigation('main')
   

Implementation Patterns

Dynamic Navigation Registration

Workflow:

1. Register navigations dynamically in a service provider or controller constructor.
2. Use closures to fetch navigation items from the database or other services:

   Navigation::register('admin', function () {
       return User::find(auth()->id())->getAdminNavigationItems();
   });
   

Conditional Navigation

Use Case: Show/hide navigation items based on user roles or other conditions.

Navigation::register('user', function () {
    $items = [
        'Dashboard' => route('dashboard'),
        'Profile' => route('profile'),
    ];

    if (auth()->user()->isAdmin()) {
        $items['Admin Panel'] = route('admin.dashboard');
    }

    return $items;
});

Nested Navigation

Structure:

Navigation::register('sidebar', function () {
    return [
        'Products' => [
            'All Products' => route('products.index'),
            'Categories' => route('products.categories'),
        ],
        'Orders' => route('orders.index'),
    ];
});

Blade Directives

Customization: Extend the @navigation directive to modify output:

Blade::directive('navigation', function ($expression) {
    return "<?php echo $nav = \\Cvepdb\\Navigations\\Facades\\Navigation::get($expression); ?>
            <ul class=\"custom-nav\">@foreach($nav as $key => $item)
                @if(is_array($item))
                    <li><a href=\"{{ $key }}\">{{ $item['title'] ?? $key }}</a>
                        <ul>@include('partials.subnav', ['items' => $item['items']])</ul>
                    </li>
                @else
                    <li><a href=\"{{ $item }}\">{{ $key }}</a></li>
                @endif
            @endforeach</ul>";
});

API Integration

Use Case: Expose navigation via API for SPAs or mobile apps.

Route::get('/api/navigation/{name}', function ($name) {
    return response()->json(Navigation::get($name));
});

Gotchas and Tips

Common Pitfalls

1. Registration Timing

   • Navigations registered in AppServiceProvider@boot may not be available during middleware execution. Use AppServiceProvider@register or a dedicated provider for early registration.

2. Caching Issues

   • If using cached views, clear the cache after registering new navigations:

     php artisan view:clear
     

3. Overwriting Navigations

   • The package does not automatically merge navigations. Use a unique name for each navigation to avoid overwrites.

Debugging

• Check Registered Navigations Dump all registered navigations in tinker:

  php artisan tinker
  >>> \Cvepdb\Navigations\Facades\Navigation::all()
  

• Verify Blade Output Use @dd(Navigation::get('main')) to inspect the raw navigation data before rendering.

Configuration Quirks

• Custom Storage Override the default storage (e.g., database, Redis) in config/navigations.php:

  'driver' => 'redis',
  'redis' => [
      'connection' => 'cache',
  ],
  

Extension Points

1. Custom Navigation Items Extend the Cvepdb\Navigations\Contracts\NavigationItem interface to add metadata:

   class ExtendedNavigationItem implements NavigationItem
   {
       public function getTitle(): string;
       public function getUrl(): string;
       public function isActive(): bool;
       public function getIcon(): ?string;
   }
   

2. Middleware Integration Dynamically register navigations based on middleware:

   Navigation::registerIf(
       'admin-nav',
       function () { return [...] },
       function ($request) {
           return $request->user()?->isAdmin();
       }
   );
   

3. Localization Support Add localization to navigation items:

   Navigation::register('main', function () {
       return [
           __('Home') => route('home'),
           __('About Us') => route('about'),
       ];
   });