Platform Admin Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require digitalstate/platform-admin-bundle
   

   Add to config/app.php under ExtraBundles:

   'extra-bundles' => [
       DigitalState\PlatformAdminBundle\PlatformAdminBundle::class,
   ],
   

2. Publish Assets & Config

   php artisan vendor:publish --provider="DigitalState\PlatformAdminBundle\PlatformAdminBundle" --tag="config"
   php artisan vendor:publish --provider="DigitalState\PlatformAdminBundle\PlatformAdminBundle" --tag="assets"
   

3. First Use Case: Basic Admin Dashboard

   • Extend the base AdminController:

     use DigitalState\PlatformAdminBundle\Controller\AdminController;
     
     class MyAdminController extends AdminController
     {
         public function index()
         {
             return $this->render('admin/dashboard.html.twig');
         }
     }
     

   • Register route in routes/admin.php:

     Route::get('/', 'MyAdminController@index')->name('admin.dashboard');
     

Implementation Patterns

Core Workflows

1. Role-Based Access Control (RBAC)

   • Use the built-in PermissionManager to define roles:

     $this->permissionManager->addRole('admin', ['create_user', 'edit_user']);
     

   • Protect routes with middleware:

     Route::middleware(['admin', 'role:admin'])->group(function () {
         // Admin-only routes
     });
     

2. CRUD Operations

   • Leverage the AdminCrudController trait for boilerplate:

     use DigitalState\PlatformAdminBundle\Traits\AdminCrudController;
     
     class UserAdminController extends AdminController
     {
         use AdminCrudController;
     
         protected $model = \App\Models\User::class;
         protected $columns = ['id', 'name', 'email'];
     }
     

3. Customizing Views

   • Override Twig templates in resources/views/admin/.
   • Extend base layouts via admin_layout.html.twig.

4. API Integration

   • Use the AdminApiController for RESTful endpoints:

     class ApiUserController extends AdminApiController
     {
         public function index()
         {
             return $this->respondWithCollection($this->model::all());
         }
     }
     

Integration Tips

• Authentication: Pair with digitalstate/auth-bundle for seamless login.
• Localization: Extend translations/admin.en.yml for multi-language support.
• Asset Management: Use admin_asset() helper for versioned JS/CSS:

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

Gotchas and Tips

Common Pitfalls

1. Middleware Conflicts

   • Ensure admin middleware is registered after web middleware in app/Http/Kernel.php:

     protected $middlewareGroups = [
         'web' => [
             // ...
             \DigitalState\PlatformAdminBundle\Http\Middleware\AdminMiddleware::class,
         ],
     ];
     

2. Route Caching

   • Clear routes after adding new admin routes:

     php artisan route:clear
     

3. Permission Caching

   • Clear cached permissions when roles change:

     $this->permissionManager->clearCache();
     

Debugging Tips

• Enable Debug Mode: Set ADMIN_DEBUG=true in .env to log permission denials.
• Check Logs: Inspect storage/logs/admin.log for RBAC errors.

Extension Points

1. Custom Permissions

   • Extend PermissionManager via events:

     event(new \DigitalState\PlatformAdminBundle\Events\PermissionRegistered($permission));
     

2. Dynamic Menus

   • Override admin_menu.html.twig to inject dynamic items:

     {% block admin_menu_items %}
         {{ parent() }}
         <li>{{ link_to_route('admin.custom_route', 'Custom') }}</li>
     {% endblock %}
     

3. API Rate Limiting

   • Apply throttle:admin middleware to API routes:

     Route::middleware(['throttle:admin'])->group(function () {
         // Rate-limited endpoints
     });