Admin Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require creonit/admin-bundle
   

   Add to config/app.php under providers:

   Creonit\AdminBundle\AdminBundle::class,
   

   Publish the bundle's assets and config:

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

2. Basic Configuration Edit config/admin.php to define your admin routes and middleware:

   'routes' => [
       'prefix' => 'admin',
       'middleware' => ['web', 'auth.admin'], // Custom middleware required
   ],
   

3. First Use Case: CRUD Controller Generate a scaffolded controller for a model (e.g., User):

   php artisan admin:make:controller User --model=App\Models\User
   

   This creates a controller with index, create, store, edit, update, destroy methods pre-configured.

Implementation Patterns

Core Workflows

1. Dynamic Admin Panels Use the @adminPanel directive in Blade templates to render admin-specific layouts:

   @adminPanel
       <div class="admin-header">Dashboard</div>
       @yield('admin_content')
   @endadminPanel
   

2. Model Integration Extend Creonit\AdminBundle\Controller\AbstractAdminController for custom logic:

   class UserAdminController extends AbstractAdminController
   {
       protected $model = User::class;
   
       public function index()
       {
           $users = $this->model::paginate(10);
           return view('admin.users.index', compact('users'));
       }
   }
   

3. Form Handling Leverage the bundle’s form helpers for admin-specific fields:

   $form = $this->createFormBuilder($user)
       ->add('name', TextType::class, ['admin_label' => 'Full Name'])
       ->add('email', EmailType::class, ['admin_hint' => 'Required'])
       ->getForm();
   

4. Access Control Use the canAccess method to restrict routes:

   public function destroy($id)
   {
       if (!$this->canAccess('delete_user')) {
           abort(403);
       }
       // Delete logic...
   }
   

5. Asset Management Override default assets by publishing and extending:

   php artisan vendor:publish --provider="Creonit\AdminBundle\AdminBundle" --tag=public
   

   Then extend resources/admin/scss/admin.scss.

Integration Tips

• Laravel Mix/Vite: Configure admin-specific JS/CSS builds in webpack.mix.js:

  mix.js('resources/admin/js/admin.js', 'public/admin/js')
     .sass('resources/admin/scss/admin.scss', 'public/admin/css');
  

• Authentication: Pair with spatie/laravel-permission for role-based access:

  // In AdminBundle config
  'middleware' => ['web', 'auth', 'permission:admin-access'],
  

• Localization: Override translations in resources/lang/vendor/admin.
• API Integration: Use the bundle’s AdminResponse for consistent JSON responses:

  return new AdminResponse(['success' => true, 'data' => $users]);
  

Gotchas and Tips

Pitfalls

1. Middleware Dependency

   • The bundle expects auth.admin middleware (not included). Implement it via:

     Route::middleware('auth.admin', function ($request, $next) {
         if (!auth()->user()->isAdmin()) abort(403);
         return $next($request);
     });
     

2. Asset Paths

   • Hardcoded paths in the bundle may require overrides. Extend via:

     // config/admin.php
     'assets' => [
         'css' => 'admin/css/custom.css',
         'js'  => 'admin/js/custom.js',
     ],
     

3. Form Validation

   • Custom validation rules may conflict with admin-specific rules. Use:

     $this->validate($request, [
         'field' => 'required|admin_rule:custom_rule',
     ]);
     

     Define admin_rule in AppServiceProvider.

4. Route Caching

   • Clear routes after adding admin routes:

     php artisan route:clear
     

5. Deprecated Methods

   • The bundle is outdated (last release 2020). Check for deprecated methods like:

     // Avoid if present
     $this->admin()->getModel(); // Use $this->model directly
     

Debugging Tips

• Route Debugging: Dump admin routes with:

  php artisan route:list --path=admin
  

• View Debugging: Enable Blade debugging in .env:

  DEBUG_BLADE=true
  

• Form Errors: Log form errors to storage/logs/laravel.log:

  \Log::error('Admin form errors:', $form->getErrors());
  

Extension Points

1. Custom Directives Extend Blade directives in AppServiceProvider:

   Blade::directive('adminPanel', function ($expression) {
       return "<?php echo Creonit\AdminBundle\Blade\AdminPanel::render($expression); ?>";
   });
   

2. Event Listeners Listen to admin events (e.g., admin.user.created):

   event(new AdminUserCreated($user));
   

   Register in EventServiceProvider.

3. Service Providers Bind custom services to the bundle’s container:

   $this->app->bind('admin.custom_service', function () {
       return new CustomAdminService();
   });
   

4. Database Observers Extend model observers for admin-specific logic:

   User::observe(AdminUserObserver::class);
   

5. API Resources Create custom admin API resources:

   class AdminUserResource extends JsonResource
   {
       public function toArray($request)
       {
           return [
               'id' => $this->id,
               'name' => $this->name,
               'admin_meta' => $this->adminMeta(),
           ];
       }
   }