Laravel Frontdoor Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require daikazu/laravel-frontdoor
   

   Publish the config:

   php artisan vendor:publish --provider="Daikazu\Frontdoor\FrontdoorServiceProvider" --tag="config"
   

2. Configure: Update .env with your mail driver (e.g., MAIL_MAILER=smtp) and configure config/frontdoor.php:

   'driver' => env('FRONTDOOR_DRIVER', 'testing'), // Use 'testing' for dev, 'email' for production
   'code_length' => 6,
   'code_expiry' => 10, // minutes
   

3. First Use Case: Trigger a login flow in a controller:

   use Daikazu\Frontdoor\Facades\Frontdoor;
   
   public function login()
   {
       $email = request()->input('email');
       Frontdoor::sendCode($email); // Sends OTP via email
       return response()->json(['message' => 'Code sent']);
   }
   

Where to Look First

• Config File: config/frontdoor.php (customize drivers, code settings).
• Facades: Daikazu\Frontdoor\Facades\Frontdoor (core methods like sendCode(), verifyCode()).
• Testing Driver: Useful for local/dev testing without emails.

Implementation Patterns

Core Workflow

1. Initiate Login:

   Frontdoor::sendCode($userEmail); // Triggers email dispatch
   

   • Uses Laravel’s mail system (configured in .env).
   • Stores code in cache (key: frontdoor:{email}).

2. Verify Code:

   $isValid = Frontdoor::verifyCode($email, $userSubmittedCode);
   if ($isValid) {
       // Authenticate user (session-based)
       auth()->loginUsingId($userId); // Manually handle if not using built-in auth
   }
   

3. Custom Account Providers: Extend Daikazu\Frontdoor\Contracts\AccountProvider:

   class CustomProvider implements AccountProvider {
       public function getUserByEmail(string $email): ?User {
           return User::where('email', $email)->first(); // Custom logic
       }
   }
   

   Register in config/frontdoor.php:

   'providers' => [
       'default' => \App\Providers\CustomProvider::class,
   ],
   

Integration Tips

• Laravel Auth Integration: Use middleware to protect routes:

  Route::middleware(['auth', 'verified'])->group(function () {
      // Protected routes
  });
  

  Override auth() logic in app/Providers/AuthServiceProvider.php to use Frontdoor::verifyCode().

• Rate Limiting: Add rate limiting to sendCode() calls (e.g., via throttle middleware):

  Route::post('/login', [LoginController::class, 'sendCode'])
      ->middleware('throttle:5,1'); // 5 requests per minute
  

• Testing: Use the testing driver in .env:

  FRONTDOOR_DRIVER=testing
  

  Mock emails with:

  $this->artisan('frontdoor:flush'); // Clear cached codes
  

Gotchas and Tips

Pitfalls

1. Cache Expiry:

   • Codes expire after code_expiry minutes (default: 10). Ensure users submit codes promptly.
   • Debug: Check cache with Artisan::call('cache:table'); (if using database cache).

2. Email Delivery:

   • Testing Driver: Does not send emails; verify with Frontdoor::testing()->assertCodeSent($email).
   • Production: Ensure MAIL_* env vars are correct. Test with a real email first.

3. Session Handling:

   • Frontdoor does not auto-create sessions. Ensure SESSION_DRIVER=file (or another driver) is set in .env.
   • Session data (e.g., auth.user) must be manually set after verifyCode().

4. Email Validation:

   • The package does not validate email formats. Add validation in your controller:

     $request->validate(['email' => 'required|email']);
     

Debugging

• Log Codes: Enable debug mode in config/frontdoor.php:

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

  Logs codes to storage/logs/laravel.log.

• Clear Cache: Flush codes manually:

  php artisan frontdoor:flush
  

  Or via facade:

  Frontdoor::flushCodes();
  

Extension Points

1. Custom Drivers: Create a driver by implementing Daikazu\Frontdoor\Contracts\CodeSender:

   class SlackSender implements CodeSender {
       public function send(string $email, string $code): void {
           // Send via Slack API
       }
   }
   

   Register in config/frontdoor.php:

   'drivers' => [
       'slack' => \App\Services\SlackSender::class,
   ],
   

2. Code Generation: Override the default random code generator:

   Frontdoor::setCodeGenerator(function () {
       return Str::random(6); // Custom logic
   });
   

3. Event Listeners: Listen for code events (e.g., CodeSent, CodeVerified) in EventServiceProvider:

   protected $listen = [
       \Daikazu\Frontdoor\Events\CodeSent::class => [
           \App\Listeners\LogCodeSent::class,
       ],
   ];
   

Config Quirks

• Driver Priority: The driver key in config is case-sensitive. Use 'testing' (not 'Testing').
• Session Driver: Frontdoor relies on Laravel’s session. If using API routes, ensure SANCTUM_STATEFUL_DOMAINS or SESSION_DOMAIN is configured for session persistence.