Laraauth Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bladesync/laraauth
   

   Publish the package's configuration and views:

   php artisan vendor:publish --provider="Bladesync\LaraAuth\LaraAuthServiceProvider" --tag="config"
   php artisan vendor:publish --provider="Bladesync\LaraAuth\LaraAuthServiceProvider" --tag="views"
   

2. Configuration Update .env with your preferred auth driver (e.g., AUTH_DRIVER=database). Customize config/laraauth.php for:

   • Guard settings (e.g., guards.web.driver, guards.web.provider).
   • Registration/verification defaults (e.g., require_verification, redirects).

3. First Use Case: Quick Login/Registration Add the auth routes to routes/web.php:

   Route::auth(); // Default routes (login, register, logout, etc.)
   

   Run migrations:

   php artisan migrate
   

   Test by visiting /login or /register.

Implementation Patterns

Core Workflows

1. Customizing Auth Views Override default Blade views in resources/views/vendor/laraauth/ (e.g., auth/login.blade.php). Extend layouts by modifying resources/views/layouts/app.blade.php to include @yield('auth-content').

2. Extending User Model Extend App\Models\User with custom fields (e.g., profile_photo_path):

   use Bladesync\LaraAuth\Models\User as Authenticatable;
   
   class User extends Authenticatable {
       protected $fillable = ['name', 'email', 'password', 'role'];
   }
   

   Update config/laraauth.php to point to your extended model:

   'models' => [
       'user' => App\Models\User::class,
   ],
   

3. Role-Based Access Control (RBAC) Use middleware in app/Http/Kernel.php:

   protected $routeMiddleware = [
       'role' => \Bladesync\LaraAuth\Middleware\RoleMiddleware::class,
   ];
   

   Apply to routes:

   Route::middleware(['auth', 'role:admin'])->group(function () {
       // Admin-only routes
   });
   

4. Password Policies Customize policies in config/laraauth.php:

   'passwords' => [
       'min_length' => 12,
       'require_uppercase' => true,
       'require_lowercase' => true,
       'require_numbers' => true,
       'require_symbols' => true,
   ],
   

5. Socialite Integration Configure providers in config/laraauth.php:

   'social' => [
       'github' => [
           'client_id' => env('GITHUB_CLIENT_ID'),
           'client_secret' => env('GITHUB_CLIENT_SECRET'),
           'redirect' => env('GITHUB_REDIRECT_URI'),
       ],
   ],
   

   Add routes:

   Route::get('/login/github', [\Bladesync\LaraAuth\Controllers\AuthController::class, 'redirectToProvider'])->name('login.github');
   Route::get('/login/github/callback', [\Bladesync\LaraAuth\Controllers\AuthController::class, 'handleProviderCallback']);
   

Integration Tips

• Laravel Fortify Synergy: Use laraauth for Blade-based auth while leveraging Fortify for API auth in the same project.
• Event Listeners: Listen to auth events (e.g., Registered, LoggedOut) in EventServiceProvider:

  protected $listen = [
      \Bladesync\LaraAuth\Events\Registered::class => [
          \App\Listeners\SendWelcomeEmail::class,
      ],
  ];
  

• Testing: Use actingAs() in tests:

  $user = User::factory()->create();
  $this->actingAs($user)->get('/dashboard');
  

Gotchas and Tips

Pitfalls

1. Migration Conflicts If extending the users table, run:

   php artisan laraauth:migrate
   

   to avoid schema conflicts. Always back up your database first.

2. Caching Issues Clear config and view caches after changes:

   php artisan config:clear
   php artisan view:clear
   

3. Middleware Order Ensure auth middleware is placed before custom middleware (e.g., role) in route groups:

   Route::middleware(['auth', 'role:editor'])->group(...);
   

4. Session Driver If using database or redis for sessions, ensure SESSION_DRIVER in .env matches:

   SESSION_DRIVER=redis
   

Debugging

• Log Auth Events: Enable logging in config/laraauth.php:

  'logging' => [
      'enabled' => true,
      'channel' => 'single',
  ],
  

• Check Guard Configuration: Verify config/auth.php aligns with config/laraauth.php:

  'guards' => [
      'web' => [
          'driver' => 'session',
          'provider' => 'laraauth', // Must match config/laraauth.php
      ],
  ],
  

Extension Points

1. Custom Validation Rules Override validation logic by publishing and modifying:

   php artisan vendor:publish --tag="laraauth-validation"
   

   Edit app/Rules/CustomValidationRule.php.

2. Email Templates Customize notification emails by extending Bladesync\LaraAuth\Notifications\ResetPasswordNotification:

   namespace App\Notifications;
   
   use Bladesync\LaraAuth\Notifications\ResetPasswordNotification as BaseNotification;
   
   class ResetPasswordNotification extends BaseNotification {
       public function toMail($notifiable) {
           return (new MailMessage)
               ->subject('Custom Reset Link')
               ->line('Click here to reset your password:')
               ->action('Reset Password', url($this->tokenUrl()))
               ->line('This link will expire in 60 minutes.');
       }
   }
   

3. Two-Factor Auth (2FA) Integrate with laravel-notification-channels/two-factor-auth:

   use Bladesync\LaraAuth\Traits\TwoFactorAuthenticatable;
   
   class User extends Authenticatable {
       use TwoFactorAuthenticatable;
   }
   

   Update config/laraauth.php:

   'two_factor' => [
       'enabled' => true,
   ],
   

4. Rate Limiting Configure login attempts in config/laraauth.php:

   'throttle' => [
       'max_attempts' => 5,
       'decay_minutes' => 1,
   ],