Admin Ui Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require sylius/admin-ui
   

   Publish the default configuration:

   php artisan vendor:publish --provider="Sylius\AdminUi\AdminUiServiceProvider"
   

2. Basic Configuration Update config/admin-ui.php to define your admin routes and templates:

   'routes' => [
       'admin' => [
           'path' => '/admin',
           'prefix' => '',
       ],
   ],
   'templates' => [
       'layout' => 'admin::layouts/default',
       'dashboard' => 'admin::pages/dashboard',
   ],
   

3. First Use Case: Quick Admin Panel Register a route in routes/web.php:

   Route::prefix(config('admin-ui.routes.admin.path'))
        ->middleware(['web', 'auth', 'admin'])
        ->group(function () {
            require __DIR__ . '/admin.php';
        });
   

   Create a simple admin route file (routes/admin.php):

   Route::get('/', [AdminController::class, 'dashboard']);
   

4. Create a Controller Generate a basic controller:

   php artisan make:controller Admin/DashboardController
   

   Extend AdminController (if provided) or use a plain controller:

   namespace App\Http\Controllers\Admin;
   
   use Illuminate\Http\Request;
   
   class DashboardController extends Controller
   {
       public function dashboard()
       {
           return view('admin::pages/dashboard');
       }
   }
   

5. Blade Templates Place templates in resources/views/vendor/admin/ (e.g., dashboard.blade.php):

   @extends('admin::layouts.default')
   @section('content')
       <h1>Admin Dashboard</h1>
   @endsection
   

Implementation Patterns

1. Route Grouping

Leverage the package’s route configuration to group admin routes under a common prefix/middleware:

Route::prefix(config('admin-ui.routes.admin.path'))
     ->middleware(['web', 'auth', 'admin'])
     ->group(function () {
         // All admin routes here
     });

2. Template Inheritance

Use the provided layout (admin::layouts.default) to maintain consistency:

@extends('admin::layouts.default')

@section('title', 'My Admin Page')
@section('content')
    <!-- Dynamic content -->
@endsection

3. Dynamic Navigation

Extend the navigation partial (admin::partials/navigation.blade.php) to add custom links:

<ul class="nav">
    <li><a href="{{ route('admin.dashboard') }}">Dashboard</a></li>
    @if(auth()->user()->can('manage_products'))
        <li><a href="{{ route('admin.products.index') }}">Products</a></li>
    @endif
</ul>

4. Middleware Integration

Add custom middleware to the admin group:

Route::prefix(config('admin-ui.routes.admin.path'))
     ->middleware(['web', 'auth', 'admin', 'verified']) // Add 'verified' middleware
     ->group(...);

5. Asset Management

Use the package’s asset helpers (if provided) to load CSS/JS:

{{ admin_asset('css/admin.css') }}
{{ admin_script('js/admin.js') }}

6. Localization

Override language files in resources/lang/vendor/admin to customize translations.

Gotchas and Tips

Pitfalls

1. Route Conflicts Ensure admin-ui routes don’t clash with existing routes. Use unique prefixes or middleware.

2. Template Overrides If templates aren’t loading, verify the resources/views/vendor/admin/ directory exists and permissions are correct.

3. Middleware Missing Forgetting to add auth or custom middleware (e.g., admin) will expose routes publicly.

4. Configuration Overrides Publishing config (php artisan vendor:publish) is required for customization. Skipping this may lead to missing settings.

Debugging Tips

• Check Published Config:

  php artisan config:clear
  

  Then verify config/admin-ui.php exists.

• Route Debugging: Use php artisan route:list to confirm admin routes are registered.

• Template Debugging: Add @debug in Blade templates to inspect variables:

  @debug(config('admin-ui'))
  

Extension Points

1. Custom Layouts Override admin::layouts.default in resources/views/vendor/admin/layouts/default.blade.php.

2. Dynamic Content Blocks Use @stack and @push in layouts for modular content:

   @stack('scripts')
   

   @push('scripts')
       <script>...</script>
   @endpush
   

3. API Integration Combine with Laravel Sanctum/Passport for API-driven admin panels:

   Route::middleware(['auth:sanctum', 'admin'])->group(...);
   

4. Testing Use actingAs() in tests to simulate admin users:

   $this->actingAs($adminUser)->get('/admin')->assertStatus(200);
   

Performance Tips

• Cache Views: Enable Blade caching in config/view.php for production.
• Lazy-Load Assets: Defer non-critical JS/CSS loading in templates.