Base Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require laravel-admin/base
   php artisan vendor:publish --tag=admin-config
   php artisan migrate
   

   Add to config/app.php:

   LaravelAdmin\Base\BaseServiceProvider::class,
   

2. Middleware Register in app/Http/Kernel.php:

   'auth.admin' => \LaravelAdmin\Base\Middleware\AuthenticateAdminUser::class,
   

3. Environment Define ADMIN_URL in .env (e.g., admin.yourdomain.com) or use a subdirectory prefix (e.g., admin).

4. First Use Case

   • Visit /admin/login (or ADMIN_URL/login).
   • Authenticate with a user marked as an admin (via the role field added to users table).
   • Access the default dashboard or configure routes (see Implementation Patterns).

Implementation Patterns

Core Workflows

1. Role-Based Access

   • Assign roles via users table (role column).
   • Configure allowed roles in config/admin.php under roles:

     'roles' => ['admin', 'editor', 'viewer'],
     

   • Restrict login via canLogin:

     'canLogin' => ['admin', 'editor'],
     

2. Route Grouping

   • Define admin routes in routes/admin.php (created automatically after publishing config).
   • Use the admin middleware group:

     Route::middleware(['auth.admin'])->group(function () {
         Route::get('/dashboard', 'DashboardController@index');
     });
     

   • Customize route prefix/domain in config/admin.php:

     'routeGroup' => [
         'domain' => env('ADMIN_URL', null),
         'prefix' => env('ADMIN_PREFIX', 'admin'),
     ],
     

3. Middleware Integration

   • Extend default middleware (e.g., add rate-limiting):

     'routeMiddleware' => [
         'auth.admin' => \App\Http\Middleware\AdminAuth::class,
         'throttle.admin' => \Illuminate\Routing\Middleware\ThrottleRequests::class,
     ],
     

   • Register custom middleware in app/Http/Kernel.php.

4. Dashboard Customization

   • Override the default dashboard by publishing views:

     php artisan vendor:publish --tag=admin-views
     

   • Modify resources/views/vendor/admin/dashboard.blade.php.

5. Authentication Logic

   • Extend the AuthenticateAdminUser middleware to add custom logic (e.g., 2FA):

     namespace App\Http\Middleware;
     use LaravelAdmin\Base\Middleware\AuthenticateAdminUser as BaseMiddleware;
     
     class AdminAuth extends BaseMiddleware {
         protected function authenticate() {
             // Custom logic here
             return parent::authenticate();
         }
     }
     

Gotchas and Tips

Pitfalls

1. Migration Conflicts

   • The package adds a role column to the users table. If you’ve customized the users table, merge migrations manually or use:

     php artisan migrate --pretend
     

     to preview changes.

2. Route Caching

   • Clear route cache after modifying routes/admin.php or config/admin.php:

     php artisan route:clear
     

3. Middleware Overrides

   • If extending AuthenticateAdminUser, ensure the parent class’s logic (e.g., role checks) is preserved. Avoid overriding handle() entirely unless necessary.

4. Alpha State Risks

   • Test thoroughly in staging. The package may introduce breaking changes between releases.

5. CSRF on Admin Routes

   • Admin routes may not inherit Laravel’s default CSRF protection. Add @csrf manually to forms or configure middleware:

     'routeMiddleware' => [
         'auth.admin' => \App\Http\Middleware\EncryptCookies::class,
         \App\Http\Middleware\VerifyCsrfToken::class,
     ],
     

Debugging Tips

1. Route Debugging

   • Use php artisan route:list --path=admin to inspect admin routes.
   • Check for conflicts with existing routes (e.g., admin/login vs. auth/login).

2. Middleware Debugging

   • Temporarily disable middleware in Kernel.php to isolate issues:

     protected $routeMiddleware = [
         'auth.admin' => function () { return null; }, // Bypass
     ];
     

3. Configuration Overrides

   • Use config(['admin.routeGroup.prefix' => 'custom-prefix']) in AppServiceProvider@boot() for runtime changes.

4. View Debugging

   • Override views in resources/views/vendor/admin/ to inspect rendered output.

Extension Points

1. Custom Controllers

   • Create controllers in app/Http/Controllers/Admin/ and reference them in routes/admin.php.

2. API Endpoints

   • Combine with Laravel Sanctum/Passport for admin API access:

     Route::middleware(['auth:api', 'auth.admin'])->get('/api/admin/data', ...);
     

3. Multi-Tenancy

   • Extend the AuthenticateAdminUser middleware to support tenant-aware admin access:

     public function handle($request, Closure $next) {
         $tenant = Tenant::find($request->tenant_id);
         auth()->setUser($tenant->adminUser());
         return $next($request);
     }
     

4. Audit Logging

   • Hook into the auth.admin middleware to log admin actions:

     public function handle($request, Closure $next) {
         event(new AdminLogin($request->user()));
         return $next($request);
     }
     

5. Theming

   • Override Bootstrap assets by publishing:

     php artisan vendor:publish --tag=admin-assets
     

   • Customize resources/views/vendor/admin/partials/head.blade.php.