Admin Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require capell-app/admin
   

   Publish the package assets and config:

   php artisan vendor:publish --provider="CapellApp\Admin\AdminServiceProvider" --tag="admin-config"
   php artisan vendor:publish --provider="CapellApp\Admin\AdminServiceProvider" --tag="admin-assets"
   

2. Register the Admin Panel Add the admin panel to your routes/web.php:

   use CapellApp\Admin\Facades\Admin;
   
   Admin::routes();
   

3. First Use Case: Basic CRUD Define a resource in a service provider or module:

   use CapellApp\Admin\Resources\Resource;
   
   Admin::resource('posts', \App\Models\Post::class)
       ->title('Posts')
       ->columns(['id', 'title', 'published_at'])
       ->editColumns(['title', 'content', 'published_at']);
   

4. Access the Admin Panel Visit /admin (or your configured route) and authenticate via Laravel’s default auth or a custom guard.

Implementation Patterns

1. Resource Workflows

• Dynamic Registration Register resources programmatically in a service provider’s boot() method:

  Admin::resource('users', \App\Models\User::class)
      ->title('Users')
      ->navigationGroup('System')
      ->navigationOrder(10);
  

• Customizing Forms/Tables Override default views or use Filament’s widgets:

  Admin::resource('posts')
      ->form(function (\CapellApp\Admin\Resources\Form $form) {
          $form->addComponents([
              \Filament\Forms\Components\RichEditor::make('content')->columnSpanFull(),
          ]);
      });
  

2. Editor Workflows

• Inline Editing Enable inline editing for tables:

  Admin::resource('posts')
      ->table(function (\CapellApp\Admin\Resources\Table $table) {
          $table->column('title')->editable();
      });
  

• Media Library Integration Attach a media manager to resources:

  Admin::resource('posts')
      ->form(function (\CapellApp\Admin\Resources\Form $form) {
          $form->addComponents([
              \Filament\Forms\Components\FileUpload::make('thumbnail')
                  ->image()
                  ->directory('post-thumbnails'),
          ]);
      });
  

3. Settings Management

• Global Settings Define settings in config/admin.php or via a dedicated resource:

  Admin::settings(function () {
      return \App\Admin\Settings::class;
  });
  

  Create a settings model:

  namespace App\Admin;
  
  use CapellApp\Admin\Settings\Contracts\Settings;
  
  class Settings implements Settings {
      public static function getTitle(): string {
          return 'Site Settings';
      }
  
      public function form(\Filament\Forms\Form $form): void {
          $form->schema([
              \Filament\Forms\Components\TextInput::make('site_name'),
          ]);
      }
  }
  

4. Extension Points

• Custom Pages Register custom admin pages:

  Admin::page('reports', \App\Admin\Pages\ReportsPage::class)
      ->title('Reports')
      ->icon('heroicon-o-chart-bar');
  

• Middleware & Policies Apply middleware to admin routes:

  Admin::middleware(['verified', 'can:manage-admin']);
  

  Use Filament’s built-in policies:

  Admin::resource('posts')->authorizeResourcePolicy(\App\Policies\PostPolicy::class);
  

5. Workflow Automation

• Actions & Bulk Actions Add custom actions to tables:

  Admin::resource('posts')
      ->table(function (\CapellApp\Admin\Resources\Table $table) {
          $table->actions([
              \CapellApp\Admin\Resources\Actions\EditAction::make(),
              \CapellApp\Admin\Resources\Actions\DeleteAction::make(),
          ]);
      });
  

• Event Listeners Listen to resource events (e.g., saved, deleted):

  Admin::resource('posts')->listen(function ($record) {
      event(new \App\Events\PostUpdated($record));
  });
  

Gotchas and Tips

Pitfalls

1. Route Conflicts

   • Ensure /admin doesn’t clash with existing routes. Use Admin::prefix('custom-admin') to override.

2. Authentication Bypass

   • Always configure a guard for the admin panel:

     Admin::authGuard('admin');
     

3. Resource Caching

   • Clear cached views after publishing assets:

     php artisan view:clear
     

4. Filament Version Mismatch

   • Ensure filament/filament is installed and compatible:

     composer require filament/filament:^3.0
     

5. Translation Issues

   • Publish translations if using non-English:

     php artisan vendor:publish --tag="admin-translations"
     

Debugging Tips

• Log Admin Events Enable debug mode in config/admin.php:

  'debug' => env('ADMIN_DEBUG', false),
  

  Check logs at storage/logs/laravel.log.

• Inspect Resource Definitions Dump registered resources:

  dd(\CapellApp\Admin\Facades\Admin::getResources());
  

• Disable JavaScript Errors For development, disable Filament’s JS validation:

  Admin::disableValidation();
  

Extension Points

1. Custom Widgets Extend Filament widgets for admin dashboards:

   Admin::dashboard(function (\CapellApp\Admin\Dashboard $dashboard) {
       $dashboard->widget(\App\Widgets\StatsOverview::class);
   });
   

2. API Endpoints Expose admin resources via API:

   Admin::resource('posts')->apiResource();
   

3. Theming Override default styles by publishing assets and extending:

   /* resources/css/admin/custom.css */
   .filament-admin {
       --color-primary: #2563eb;
   }
   

4. Multi-Tenancy Use Filament’s tenant middleware:

   Admin::middleware(['tenant']);
   

5. Localization Override translations in resources/lang/vendor/admin/...:

   'resources' => [
       'posts' => [
           'title' => 'Blog Entries',
       ],
   ],
   

Performance Quirks

• Eager Load Relationships Optimize resource queries:

  Admin::resource('posts')->query(function ($query) {
      return $query->with(['author', 'category']);
  });
  

• Lazy Load Assets Disable unnecessary JS/CSS:

  Admin::disableAssets(['unnecessary-widget']);
  

• Database Indexing Ensure id and created_at columns are indexed for large datasets.