Filament Auth Ui Enhancer Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require diogogpinto/filament-auth-ui-enhancer
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="Diogogpinto\FilamentAuthUIEnhancer\FilamentAuthUIEnhancerServiceProvider" --tag="config"
   

2. Register the Plugin: In your PanelServiceProvider (or AppServiceProvider if no panel provider exists), add:

   use Diogogpinto\FilamentAuthUIEnhancer\FilamentAuthUIEnhancerPlugin;
   
   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               FilamentAuthUIEnhancerPlugin::make(),
           ]);
   }
   

3. First Use Case: Replace the default login page with a custom design by overriding the default views:

   • Copy the default views from vendor/diogogpinto/filament-auth-ui-enhancer/resources/views to resources/views/vendor/filament-auth-ui-enhancer.
   • Customize the copied views (e.g., auth/login.blade.php) to match your brand.

Where to Look First

• Config File: config/filament-auth-ui-enhancer.php (if published) for global settings like default colors, logos, or social auth buttons.
• Blade Views: Override the default views in resources/views/vendor/filament-auth-ui-enhancer for UI customization.
• Plugin Documentation: Check the GitHub README for feature-specific examples (e.g., social auth, captcha, or animations).

Implementation Patterns

1. Customizing Auth Pages

• Override Views: Copy the default views (e.g., login, register, forgot-password) from the package to your project’s resources/views/vendor/filament-auth-ui-enhancer directory. Modify them to fit your design system. Example:

  <!-- resources/views/vendor/filament-auth-ui-enhancer/auth/login.blade.php -->
  <x-filament-auth-ui-enhancer::auth-section>
      <x-slot name="logo">
          <img src="{{ asset('images/custom-logo.svg') }}" alt="Logo">
      </x-slot>
      <x-slot name="description">
          Welcome to our platform!
      </x-slot>
      <!-- Custom form fields or sections -->
  </x-x-filament-auth-ui-enhancer::auth-section>
  

• Dynamic Content: Use Blade slots to inject dynamic content (e.g., logos, descriptions, or CTAs):

  <x-filament-auth-ui-enhancer::auth-section>
      <x-slot name="logo">
          {{ $logo ?? '' }}
      </x-slot>
  </x-filament-auth-ui-enhancer::auth-section>
  

2. Extending Functionality

• Social Auth Buttons: Enable and configure social auth (e.g., Google, GitHub) via the config:

  // config/filament-auth-ui-enhancer.php
  'social_auth' => [
      'google' => [
          'enabled' => true,
          'client_id' => env('GOOGLE_CLIENT_ID'),
          'client_secret' => env('GOOGLE_CLIENT_SECRET'),
      ],
      'github' => [
          'enabled' => false,
      ],
  ],
  

  Customize the buttons in the overridden views:

  @if(config('filament-auth-ui-enhancer.social_auth.google.enabled'))
      <x-filament-auth-ui-enhancer::social-auth-button
          provider="google"
          label="Sign in with Google"
      />
  @endif
  

• Animations/Transitions: Leverage built-in animations by extending the default views with Tailwind CSS classes or custom JS:

  <div class="animate-fade-in">
      <!-- Form content -->
  </div>
  

3. Integration with Filament Features

• Localization: Override language files in resources/lang/vendor/filament-auth-ui-enhancer to customize labels or messages.

• Dark Mode: Ensure your custom views support Filament’s dark mode by using Tailwind’s dark: variants or the @filamentThemes directive:

  <div class="dark:text-white">
      <!-- Content -->
  </div>
  

• Form Validation: Extend the default validation logic by publishing and modifying the AuthServiceProvider or using Filament’s form components:

  use Filament\Forms\Components\TextInput;
  
  public function registerLoginForm(): array
  {
      return [
          TextInput::make('email')
              ->email()
              ->required()
              ->label('Custom Email Label'),
      ];
  }
  

4. Workflow: Full Customization

1. Publish Assets:

   php artisan vendor:publish --tag="filament-auth-ui-enhancer-views"
   

2. Customize Views: Edit the published views in resources/views/vendor/filament-auth-ui-enhancer.
3. Configure Features: Update config/filament-auth-ui-enhancer.php for social auth, captcha, or other settings.
4. Test Locally: Verify the auth flows (login, register, forgot password) in a local Filament panel.
5. Deploy: Push changes to production and validate the UI/UX.

Gotchas and Tips

Pitfalls

1. View Override Conflicts:

   • Issue: Forgetting to copy the default views before customization can lead to missing templates or errors.
   • Fix: Always publish the views first:

     php artisan vendor:publish --tag="filament-auth-ui-enhancer-views"
     

2. Cached Assets:

   • Issue: Changes to Blade views or Tailwind classes may not reflect due to caching.
   • Fix: Clear Filament’s view cache:

     php artisan filament:cache:clear
     

     Or disable caching in config/filament.php during development:

     'cache' => false,
     

3. Social Auth Misconfiguration:

   • Issue: Social auth buttons appear but fail silently due to missing environment variables.
   • Fix: Verify .env variables (e.g., GOOGLE_CLIENT_ID) and check the package logs:

     tail -f storage/logs/laravel.log
     

4. Theme Inconsistencies:

   • Issue: Custom views don’t adapt to Filament’s dark mode or theme colors.
   • Fix: Use Filament’s theme variables in your CSS/Blade:

     <div style="color: {{ filament()->getThemeColor('primary') }}">
         <!-- Content -->
     </div>
     

Debugging Tips

1. Log Social Auth Errors: Add debug logs in your AuthServiceProvider or use Laravel’s logging:

   try {
       $user = Socialite::driver('google')->user();
   } catch (\Exception $e) {
       \Log::error('Social Auth Error: ' . $e->getMessage());
   }
   

2. Inspect Blade Output: Use @dump or {{ dd() }} in custom views to debug dynamic content:

   @dump($this->getAuthPageData())
   

3. Check Plugin Events: Listen for plugin events to debug initialization:

   use Diogogpinto\FilamentAuthUIEnhancer\Events\AuthUIEnhancerInitialized;
   
   AuthUIEnhancerInitialized::listen(function ($plugin) {
       \Log::info('Plugin initialized:', [$plugin->getConfig()]);
   });
   

Extension Points

1. Custom Auth Pages:

   • Create entirely new auth layouts by extending the plugin’s base components:

     <x-filament-auth-ui-enhancer::base-layout>
         <!-- Custom content -->
     </x-filament-auth-ui-enhancer::base-layout>
     

2. Dynamic Config: Override the config dynamically in your PanelServiceProvider:

   FilamentAuthUIEnhancerPlugin::make()
       ->config([
           'logo' => asset('images/custom-logo.png'),
           'social_auth' => [
               'google' => ['enabled' => false],
           ],
       ]),
   

3. Add Custom Fields: Extend the default forms by publishing and modifying the form components:

   php artisan vendor:publish --tag="filament-auth-ui-enhancer-forms"
   

   Then customize resources/views/vendor/filament-auth-ui-enhancer/forms/login.blade.php.

4. Localization: Add custom language files for unsupported locales:

   mkdir -p resources/lang/pt/vendor/filament-auth-ui-enhancer
   

   Create auth.php with your translations.

Pro Tips

1. Use Filament’s Icons: Leverage Filament’s icon system in your