Sidebar Laravel Package

Getting Started

Minimal Steps

1. Installation Run composer require shopper/sidebar and publish the config with:

   php artisan vendor:publish --provider="Shopper\Sidebar\SidebarServiceProvider" --tag="sidebar-config"
   

2. Middleware Setup Add the middleware to your web group in bootstrap/app.php (Laravel 11+):

   ->withMiddleware(function (Middleware $middleware) {
       $middleware->appendToGroup('web', \Shopper\Sidebar\Middleware\ResolveSidebars::class);
   });
   

   Or wrap routes in a group:

   Route::middleware(['web', \Shopper\Sidebar\Middleware\ResolveSidebars::class])->group(...);
   

3. First Use Case Define a sidebar in a controller or service:

   use Shopper\Sidebar\Facades\Sidebar;
   
   public function showDashboard() {
       Sidebar::set('dashboard', [
           ['type' => 'link', 'url' => '/dashboard', 'label' => 'Dashboard'],
           ['type' => 'divider'],
           ['type' => 'link', 'url' => '/settings', 'label' => 'Settings'],
       ]);
       return view('dashboard');
   }
   

   Render it in a Blade view:

   @include('sidebar::sidebar')
   

Implementation Patterns

Core Workflows

1. Dynamic Sidebar Management Use the Sidebar facade to conditionally build sidebars:

   if (auth()->user()->isAdmin()) {
       Sidebar::set('admin', [
           ['type' => 'link', 'url' => '/admin/users', 'label' => 'Users'],
       ]);
   }
   

2. Reusable Sidebar Components Create a service class to encapsulate sidebar logic:

   class SidebarBuilder {
       public function buildAdminSidebar() {
           return [
               ['type' => 'header', 'label' => 'Admin Panel'],
               ['type' => 'link', 'url' => '/admin', 'label' => 'Home'],
           ];
       }
   }
   

   Call it in a controller:

   Sidebar::set('admin', (new SidebarBuilder())->buildAdminSidebar());
   

3. View Integration Extend the default sidebar view by publishing and customizing:

   php artisan vendor:publish --tag="sidebar-views"
   

   Override resources/views/vendor/sidebar/sidebar.blade.php to add custom classes or logic.

4. API-Driven Sidebars Fetch sidebar items from an API or database:

   $sidebarItems = SidebarItem::where('user_id', auth()->id())->get();
   Sidebar::set('user', $sidebarItems->map(fn ($item) => [
       'type' => 'link',
       'url' => $item->url,
       'label' => $item->label,
   ]));
   

Integration Tips

• Laravel Mix/Vite: Use the width and breakpoint config values in your CSS/JS for responsive design.
• Authentication: Combine with Laravel’s auth middleware to show/hide sidebars:

  Route::middleware(['auth', \Shopper\Sidebar\Middleware\ResolveSidebars::class])->group(...);
  

• Caching: Enable user-based caching for personalized sidebars:

  'cache' => [
      'method' => 'user-based',
      'duration' => 3600, // 1 hour
  ],
  

Gotchas and Tips

Pitfalls

1. Middleware Order Matters Place ResolveSidebars after web middleware to ensure the request is fully processed (e.g., auth checks) before resolving sidebars. ❌ Wrong:

   ->middleware([\Shopper\Sidebar\Middleware\ResolveSidebars::class, 'auth'])
   

   ✅ Correct:

   ->middleware(['web', 'auth', \Shopper\Sidebar\Middleware\ResolveSidebars::class])
   

2. Caching Conflicts If using user-based caching, ensure auth()->user() is available when the sidebar is resolved. Test with:

   php artisan sidebar:clear-cache
   

3. View Override Pitfalls Forgetting to clear cached views after publishing custom views may result in stale output. Run:

   php artisan view:clear
   

4. Type Validation The package expects strict item types (e.g., 'type' => 'link'). Invalid types may silently fail. Validate with:

   $validTypes = ['link', 'header', 'divider', 'dropdown'];
   if (!in_array($item['type'], $validTypes)) {
       throw new \InvalidArgumentException("Invalid sidebar type: {$item['type']}");
   }
   

Debugging

• Check Resolved Sidebars Dump the resolved sidebars in a middleware or controller:

  dd(\Shopper\Sidebar\Facades\Sidebar::getAll());
  

• Log Sidebar Errors Add a custom middleware to log sidebar-related exceptions:

  public function handle($request, Closure $next) {
      try {
          return $next($request);
      } catch (\Shopper\Sidebar\Exceptions\SidebarException $e) {
          \Log::error('Sidebar error: ' . $e->getMessage());
          throw $e;
      }
  }
  

Extension Points

1. Custom Sidebar Items Extend the package by creating a custom item type. Override the SidebarServiceProvider:

   public function register() {
       $this->app->extend('sidebar', function ($sidebar) {
           $sidebar->addType('custom', function ($item) {
               return view('sidebar.custom', ['item' => $item]);
           });
           return $sidebar;
       });
   }
   

2. Database Backend Replace the default storage with a database-backed solution by binding a custom SidebarRepository:

   $this->app->bind(\Shopper\Sidebar\Contracts\SidebarRepository::class, function () {
       return new DatabaseSidebarRepository();
   });
   

3. Event-Based Sidebars Trigger sidebar updates via events (e.g., after user login):

   event(new \App\Events\UserLoggedIn(auth()->user()));
   

   Listen for the event and update sidebars:

   \App\Events\UserLoggedIn::class => function () {
       Sidebar::set('user', [...]);
   }
   

4. Localization Support Add localized labels to sidebar items dynamically:

   Sidebar::set('dashboard', [
       ['type' => 'link', 'url' => '/dashboard', 'label' => __('sidebar.dashboard')],
   ]);