Admin Panel Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require besharatnia/admin-panel
   

   Publish the package assets and config:

   php artisan vendor:publish --provider="Besharatnia\AdminPanel\AdminPanelServiceProvider"
   

2. Configuration

   • Update .env with:

     ADMIN_PANEL_ENABLED=true
     ADMIN_PANEL_PREFIX=admin
     

   • Publish the config file (config/admin-panel.php) and adjust RTL/LTR settings, menu structure, and branding.

3. First Use Case

   • Define a basic admin route in routes/web.php:

     Route::group(['prefix' => config('admin-panel.prefix'), 'middleware' => ['web', 'auth']], function () {
         \Besharatnia\AdminPanel\Facades\AdminPanel::routes();
     });
     

   • Create a simple admin controller:

     namespace App\Http\Controllers\Admin;
     
     use Besharatnia\AdminPanel\AdminController;
     
     class DashboardController extends AdminController
     {
         public function index()
         {
             return view('admin.dashboard');
         }
     }
     

   • Register the route in config/admin-panel.php under menu:

     'menu' => [
         [
             'name' => 'Dashboard',
             'icon' => 'fa fa-dashboard',
             'route' => 'admin.dashboard',
         ],
     ],
     

   • Create a view at resources/views/admin/dashboard.blade.php.

Implementation Patterns

Workflows

1. Menu Management

   • Dynamically add/remove menu items via the menu config array or middleware:

     // In a middleware or service provider
     AdminPanel::setMenu([
         ['name' => 'Users', 'route' => 'admin.users.index'],
     ]);
     

   • Use the AdminPanel::menu() helper to render the menu in custom views.

2. Authentication

   • Extend the default auth by adding middleware to the ADMIN_PANEL_MIDDLEWARE config:

     'middleware' => ['auth', 'verified', 'role:admin'],
     

   • Override the login view by publishing and modifying resources/views/vendor/admin-panel/auth/login.blade.php.

3. Views and Layouts

   • Override the default layout (resources/views/vendor/admin-panel/layouts/app.blade.php) for global changes.
   • Use @include('admin-panel::partials.header') to embed package partials (e.g., header, sidebar).

4. RTL/LTR Support

   • Toggle RTL in config/admin-panel.php:

     'rtl' => env('ADMIN_PANEL_RTL', false),
     

   • Apply RTL-specific CSS/JS via the AdminPanel::direction() helper in Blade:

     @if(AdminPanel::direction() === 'rtl')
         <link rel="stylesheet" href="{{ asset('css/rtl.css') }}">
     @endif
     

5. CRUD Operations

   • Leverage the AdminController base class for common admin logic (e.g., authorization, breadcrumbs):

     use Besharatnia\AdminPanel\AdminController;
     
     class UserController extends AdminController
     {
         public function __construct()
         {
             parent::__construct();
             $this->middleware('can:manage-users');
         }
     }
     

6. Asset Management

   • Add custom CSS/JS via the AdminPanel::assets() helper:

     @AdminPanel::assets()
         <link rel="stylesheet" href="{{ asset('css/admin-custom.css') }}">
     @endAdminPanel
     

Gotchas and Tips

Pitfalls

1. Route Conflicts

   • Ensure ADMIN_PANEL_PREFIX doesn’t clash with existing routes. Test with:

     php artisan route:list | grep admin
     

2. Middleware Order

   • Place AdminPanel middleware after auth in app/Http/Kernel.php to avoid bypassing auth checks:

     'admin' => [
         \Besharatnia\AdminPanel\Middleware\AdminPanelMiddleware::class,
     ],
     

3. Asset Loading

   • If assets (CSS/JS) fail to load, verify the public_path() in config/admin-panel.php and clear cached views:

     php artisan view:clear
     

4. RTL Quirks

   • Some third-party plugins may not fully support RTL. Test thoroughly and override styles if needed:

     /* Override RTL-specific issues */
     .rtl .some-class { direction: ltr !important; }
     

5. Deprecated Features

   • The package is last updated in 2021. Avoid relying on undocumented features or assume backward compatibility with newer Laravel versions (e.g., 10.x).

6. Menu Caching

   • Menu items defined in config/admin-panel.php are cached. Clear config cache after changes:

     php artisan config:clear
     

Debugging Tips

1. Enable Debug Mode

   • Set APP_DEBUG=true in .env to surface template errors or missing views.

2. Log Admin Events

   • Extend the AdminPanelServiceProvider to log admin panel usage:

     public function boot()
     {
         AdminPanel::on('menu.render', function ($menu) {
             \Log::debug('Admin menu rendered', ['menu' => $menu]);
         });
     }
     

3. Inspect Middleware

   • Use php artisan route:list to verify middleware is applied to admin routes.

4. Check Published Files

   • After publishing, verify files exist in:
     • resources/views/vendor/admin-panel/
     • public/vendor/admin-panel/

Extension Points

1. Custom Views

   • Override any published view (e.g., resources/views/vendor/admin-panel/layouts/app.blade.php) for full control.

2. Dynamic Menu Items

   • Fetch menu items from a database and merge them with the config:

     $menu = AdminPanel::menu();
     $menu = array_merge($menu, DB::table('admin_menu')->get()->toArray());
     AdminPanel::setMenu($menu);
     

3. Event Listeners

   • Listen for admin panel events (e.g., menu.render, auth.attempt) in EventServiceProvider:

     protected $listen = [
         'Besharatnia\AdminPanel\Events\MenuRendering' => [
             'App\Listeners\LogAdminMenu',
         ],
     ];
     

4. Localization

   • Extend language files in resources/lang/vendor/admin-panel/ to customize labels or messages.

5. API Integration

   • Use the package’s auth system for API routes by sharing middleware:

     Route::middleware(['admin'])->group(function () {
         Route::apiResource('admin/users', UserController::class);
     });