Bartender Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require directorytree/bartender
   php artisan vendor:publish --provider="DirectoryTree\Bartender\BartenderServiceProvider"
   php artisan migrate
   

2. Register Routes:

   // routes/web.php
   use DirectoryTree\Bartender\Facades\Bartender;
   Bartender::routes();
   

3. Configure Providers: Update config/services.php with provider-specific redirect URLs (e.g., 'redirect' => '/auth/google/callback').

4. Enable Providers:

   // app/Providers/AppServiceProvider.php
   Bartender::serve('google'); // Add other providers (e.g., 'microsoft')
   

5. First Use Case: Add login links in a Blade template:

   <a href="{{ route('auth.driver.redirect', 'google') }}">Login with Google</a>
   

Implementation Patterns

Core Workflow

1. Redirect Flow:

   • User clicks a provider link (e.g., /auth/google/redirect).
   • Bartender triggers Socialite’s redirect() for the provider.
   • Provider redirects back to /auth/google/callback.

2. Callback Handling:

   • Bartender processes the OAuth response via callback().
   • Default logic:
     • Finds or creates a user (via ProviderRepository).
     • Stores provider tokens (if StoresProviderTokens is implemented).
     • Redirects to a success route (customizable via ProviderRedirector).

3. User Management:

   • Soft Deletes: Restores trashed users on login (configurable via ProviderRepository).
   • Email Verification: Auto-verifies emails if email_verified_at is missing.
   • Token Storage: Encrypts provider_access_token/provider_refresh_token if StoresProviderTokens is implemented.

Integration Tips

• Custom Providers: Extend UserProviderHandler to modify scopes or logic per provider (e.g., Microsoft’s Mail.ReadWrite scope).

  Bartender::serve('microsoft', MicrosoftUserHandler::class);
  

• User Resolution: Override ProviderRepository to customize user lookup/creation logic (e.g., multi-provider merging).

  $this->app->bind(ProviderRepository::class, CustomUserProviderRepository::class);
  

• Post-Auth Actions: Use ProviderRedirector to handle redirects/flash messages (e.g., session regeneration for security).

  public function userAuthenticated($user, $socialite, $driver) {
      Auth::login($user);
      Session::regenerate();
      return redirect()->route('dashboard');
  }
  

• Token Management: For APIs, store tokens in a separate table (e.g., oauth_tokens) and link via provider_id.

Gotchas and Tips

Pitfalls

1. Missing Provider Setup:

   • Error: Driver [X] not supported.
   • Fix: Ensure the provider is registered with Socialite (e.g., Socialite::driver('google')) and Bartender::serve('google') is called.

2. Route Requirements:

   • Error: Routing requirement for "driver" cannot be empty.
   • Fix: Verify Bartender::routes() is called in web.php and providers are served in AppServiceProvider.

3. Token Storage:

   • Issue: Tokens not saved despite StoresProviderTokens.
   • Fix: Run migrations and ensure $hidden/$casts in User model are configured:

     protected $hidden = ['provider_access_token', 'provider_refresh_token'];
     protected function casts(): array { return ['provider_access_token' => 'encrypted']; }
     

4. Soft Deletes:

   • Behavior: Users are restored on login by default.
   • Override: Implement custom exists()/updateOrCreate() in ProviderRepository to change logic.

5. Email Verification:

   • Behavior: Auto-verifies emails if email_verified_at is null.
   • Disable: Skip in updateOrCreate() if not needed.

Debugging Tips

• Log Provider Data: Dump Socialite user data in ProviderRepository to debug mismatches:

  dd($user->getEmail(), $user->getId());
  

• Test Redirects: Use php artisan route:list to verify /auth/{driver}/redirect and /auth/{driver}/callback routes exist.

• Token Issues: Check provider_access_token/provider_refresh_token in the DB or use Tinker:

  php artisan tinker
  >>> $user = App\Models\User::find(1);
  >>> dd($user->provider_access_token);
  

Extension Points

1. Custom Handlers:

   • Extend UserProviderHandler for provider-specific logic (e.g., custom scopes).
   • Example: Add scopes() before redirect() in redirect() method.

2. Repository Swaps:

   • Override ProviderRepository to:
     • Merge accounts from multiple providers.
     • Add custom attributes (e.g., provider_avatar_url).
     • Skip email verification.

3. Redirect Logic:

   • Customize ProviderRedirector for:
     • Role-based redirects (e.g., admins to /admin).
     • Multi-factor auth (MFA) prompts.
     • Localization (e.g., with('locale', $user->locale)).

4. Token Management:

   • For long-lived tokens, implement a TokenManager to refresh tokens silently:

     public function refreshToken(User $user, string $driver) {
         $provider = Socialite::driver($driver)->user();
         $user->forceFill(['provider_refresh_token' => $provider->token])->save();
     }
     

Configuration Quirks

• Migration Skipping: Delete 2024_10_27_131354_add_provider_token_columns_to_users_table.php if tokens aren’t needed (but ensure StoresProviderTokens isn’t implemented).

• User Model Namespace: Set custom User model in AuthServiceProvider if not in App\Models:

  Bartender::setUserModel(\App\User::class);
  

• Hashing: Bartender uses Laravel’s Hash::make() (not bcrypt). Override in ProviderRepository if needed:

  $user->password = Hash::make('default_password');