Auth Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require componist/auth
   php artisan vendor:publish --tag=componist.auth.publish.config
   php artisan migrate
   

2. User Model Update Extend your User model with the required trait and interface:

   use Componist\Auth\Traits\AddComponistAuthentication;
   use Componist\Auth\Contracts\TwoFactorAuthenticatable;
   
   class User extends Authenticatable implements TwoFactorAuthenticatable
   {
       use AddComponistAuthentication;
       // ...
   }
   

3. First Use Case Add the Livewire component to your login view:

   <x-componist-auth::login />
   

   The package provides pre-built UI for:

   • Login (login)
   • Registration (register)
   • Password Reset (password-reset)
   • Email Verification (verify-email)
   • 2FA Setup (two-factor-setup)

Where to Look First

• Configuration: config/componist_auth.php (published via vendor:publish).
• Components: resources/views/vendor/componist-auth/ (customizable Blade templates).
• Livewire Components: app/Http/Livewire/ (generated by the package).
• Middleware: app/Http/Middleware/ (check for Componist\Auth\Http\Middleware\*).

Implementation Patterns

Core Workflows

1. Authentication Flow

   • Use <x-componist-auth::login /> for login with built-in rate limiting.
   • Customize the form by extending the Livewire component:

     php artisan make:livewire CustomLogin extends Componist\Auth\Livewire\Login
     

     Override methods like rules() or messages() in the new class.

2. Registration with 2FA

   • Enable 2FA in config ('features' => ['two_factor' => true]).
   • The registration flow automatically includes 2FA setup if enabled.

3. Password Reset

   • Trigger via <x-componist-auth::password-reset />.
   • Customize the email template by publishing views:

     php artisan vendor:publish --tag=componist.auth.publish.views
     

4. Email Verification

   • Extend the MustVerifyEmail trait in your User model.
   • Use <x-componist-auth::verify-email /> for the verification UI.

5. Session Hardening

   • Leverage built-in middleware (Componist\Auth\Http\Middleware\EnsureEmailIsVerified or Componist\Auth\Http\Middleware\CheckTwoFactor).
   • Add to app/Http/Kernel.php:

     'web' => [
         \Componist\Auth\Http\Middleware\EnsureEmailIsVerified::class,
         // ...
     ],
     

Integration Tips

• Feature Flags Toggle features via config (e.g., 'features' => ['registration' => false] to disable registration).
• Custom Validation Extend Livewire components to add custom rules:

  protected function rules()
  {
      return array_merge(parent::rules(), [
          'custom_field' => 'required|string',
      ]);
  }
  

• Localization Publish language files:

  php artisan vendor:publish --tag=componist.auth.publish.lang
  

  Override translations in resources/lang/.
• Testing Use the provided test helpers:

  $this->actingAs($user)->login(); // Custom helper (if provided)
  $this->actingAs($user)->verifyEmail();
  

Gotchas and Tips

Pitfalls

1. Migration Conflicts

   • The package adds columns (two_factor_code, two_factor_expires_at, last_login) to the users table.
   • Fix: Run php artisan migrate --pretend first to check for conflicts, or manually merge migrations if needed.

2. Caching Issues

   • Livewire components may cache incorrectly if the Componist\Auth\Livewire\* classes are not autoloaded.
   • Fix: Clear config and view caches:

     php artisan config:clear
     php artisan view:clear
     

3. 2FA Session Expiry

   • The two_factor_expires_at field uses a TTL (Time-To-Live) for 2FA codes.
   • Gotcha: If this expires during testing, regenerate the code via:

     $user->generateTwoFactorCode();
     

4. Middleware Order

   • Ensure EnsureEmailIsVerified and CheckTwoFactor middleware are placed after auth middleware in Kernel.php:

     'web' => [
         \Illuminate\Auth\Middleware\Authenticate::class,
         \Componist\Auth\Http\Middleware\EnsureEmailIsVerified::class,
         \Componist\Auth\Http\Middleware\CheckTwoFactor::class,
     ],
     

Debugging

1. Livewire Errors

   • Check the Livewire logs in storage/logs/livewire.log.
   • Enable debug mode in config/componist_auth.php:

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

2. Rate Limiting

   • Default rate limits are defined in config/componist_auth.php under rate_limits.
   • Override globally or per component by extending the Livewire class.

3. Email Verification Tokens

   • Tokens are stored in the personal_access_tokens table. If verification fails:
     • Regenerate the token:

       $user->sendEmailVerificationNotification();
       

     • Check the verified_at column in the users table.

Extension Points

1. Custom Livewire Components

   • Extend any Livewire component (e.g., Login, Register) to add custom logic:

     php artisan make:livewire CustomRegister extends Componist\Auth\Livewire\Register
     

   • Override methods like updated(), rules(), or messages().

2. Custom Views

   • Publish and override Blade templates:

     php artisan vendor:publish --tag=componist.auth.publish.views
     

   • Modify files in resources/views/vendor/componist-auth/.

3. Custom Notifications

   • Extend the default notifications (e.g., VerifyEmail, ResetPassword) by binding your own:

     use Componist\Auth\Notifications\VerifyEmail as ComponistVerifyEmail;
     
     class VerifyEmail extends ComponistVerifyEmail
     {
         public function toMail($notifiable)
         {
             // Customize email content
             return (new MailMessage)
                 ->subject('Custom Verification Subject')
                 ->line('Custom verification line.');
         }
     }
     

   • Bind the notification in AuthServiceProvider:

     public function boot()
     {
         $this->app->bind(
             \Illuminate\Auth\Notifications\VerifyEmail::class,
             CustomVerifyEmail::class
         );
     }
     

4. Feature Flag Logic

   • Dynamically enable/disable features via config or runtime:

     if (config('componist_auth.features.registration')) {
         // Enable registration logic
     }
     

   • Override feature checks in your extended Livewire components.

5. Session Hardening

   • Customize session security settings in config/componist_auth.php:

     'session' => [
         'secure' => env('SESSION_SECURE_COOKIE', true),
         'http_only' => true,
         'same_site' => 'lax',
     ],