Admin Bundle Laravel Package

Getting Started

First Steps

1. Installation Add the bundle via Composer:

   composer require aspl/admin-bundle
   

   Register the bundle in config/app.php under providers:

   Aspl\AdminBundle\AdminBundle::class,
   

   Publish assets and configurations:

   php artisan vendor:publish --provider="Aspl\AdminBundle\AdminBundle" --tag=config
   php artisan vendor:publish --provider="Aspl\AdminBundle\AdminBundle" --tag=assets
   

2. Basic Setup

   • Configure routes in routes/web.php:

     use Aspl\AdminBundle\Routing\AdminRouter;
     $adminRouter = new AdminRouter();
     $adminRouter->mapRoutes();
     

   • Run migrations (if applicable):

     php artisan migrate
     

3. First Use Case: Quick Admin Panel

   • Access the admin panel at /admin (default route).
   • Use the pre-built dashboard, CRUD interfaces, and widgets without manual setup.

Implementation Patterns

Core Workflows

1. CRUD Operations

   • Automatic CRUD Generation: Annotate entities with @ORM\Table and @ORM\Entity to auto-generate admin interfaces.
   • Customization: Override templates in resources/views/admin/ or extend controllers via traits:

     use Aspl\AdminBundle\Controller\AdminController;
     class CustomAdminController extends AdminController {
         // Override methods like index(), create(), etc.
     }
     

2. Widgets and Dashboards

   • Pre-built Widgets: Use widgets like StatsWidget, RecentActivityWidget in resources/views/admin/dashboard.html.twig.
   • Custom Widgets: Create new widgets by extending Aspl\AdminBundle\Widget\AbstractWidget:

     class MyCustomWidget extends AbstractWidget {
         public function render() { ... }
     }
     

3. Permissions and Roles

   • Role-Based Access: Define roles in config/admin.yml:

     roles:
         admin: [ALL]
         editor: [CREATE, EDIT, DELETE]
     

   • Middleware Integration: Protect routes with admin.auth middleware:

     Route::get('/admin/secure', function() { ... })->middleware('admin.auth');
     

4. Theming and Assets

   • Custom Themes: Override SCSS/Less in resources/assets/admin/ and compile with Laravel Mix.
   • Asset Management: Use admin_asset() helper for versioned assets:

     <link href="{{ admin_asset('css/admin.css') }}" rel="stylesheet">
     

5. Integration with Existing Code

   • Service Injection: Bind custom services to the admin bundle’s container:

     $this->container->set('my.service', function() { ... });
     

   • Event Listeners: Listen to admin events (e.g., admin.entity.created):

     Event::listen('admin.entity.created', function($entity) { ... });
     

Gotchas and Tips

Common Pitfalls

1. Route Conflicts

   • Issue: Default /admin route may clash with existing routes.
   • Fix: Customize the admin prefix in config/admin.yml:

     admin:
         prefix: '/backend'
     

2. Entity Auto-Generation Quirks

   • Issue: Not all Doctrine annotations are auto-detected.
   • Fix: Explicitly define admin options in your entity:

     /**
      * @ORM\Entity(repositoryClass="App\Repository\MyEntityRepository")
      * @Aspl\AdminBundle\Annotation\Admin(
      *     title="My Entity",
      *     list=[...],
      *     form=[...]
      * )
      */
     

3. Asset Loading Failures

   • Issue: Custom assets (CSS/JS) not loading.
   • Fix: Ensure admin_asset() helper is properly configured in AppServiceProvider:

     public function boot() {
         AdminBundle::setAssetPath(public_path('admin'));
     }
     

4. Permission System Overrides

   • Issue: Role checks bypassed unexpectedly.
   • Fix: Verify admin.auth middleware is correctly registered in Kernel.php:

     protected $routeMiddleware = [
         'admin.auth' => \Aspl\AdminBundle\Http\Middleware\AdminAuth::class,
     ];
     

5. Database Migrations

   • Issue: Bundle migrations fail due to missing tables.
   • Fix: Run migrations in the correct order:

     php artisan migrate --path=vendor/aspl/admin-bundle/src/Resources/migrations
     

Pro Tips

1. Debugging Admin Routes

   • Dump all registered admin routes:

     php artisan route:list --path=/admin
     

2. Extending the Bundle

   • Custom Controllers: Override the default AdminController by binding it in services.yml:

     services:
         aspl_admin.controller.admin:
             class: App\Controller\CustomAdminController
             tags: ['controller.service_arguments']
     

3. Performance Optimization

   • Lazy-Load Widgets: Use isVisible() in widgets to conditionally render:

     public function isVisible() {
         return $this->getUser()->hasRole('admin');
     }
     

4. Localization

   • Override translations in resources/lang/admin/ to support multiple languages.

5. Testing

   • Use AdminTestCase for testing admin routes:

     use Aspl\AdminBundle\Tests\AdminTestCase;
     class MyAdminTest extends AdminTestCase {
         public function testAdminDashboard() {
             $this->loginAsAdmin();
             $this->visit('/admin');
             // Assertions...
         }
     }