Auth Laravel Package

Getting Started

First Steps

1. Installation

   composer require squarenetmedia/auth
   

   Publish the package’s assets and config:

   php artisan vendor:publish --provider="SquareNetMedia\Auth\AuthServiceProvider" --tag="auth-views"
   php artisan vendor:publish --provider="SquareNetMedia\Auth\AuthServiceProvider" --tag="auth-config"
   

2. Configuration

   • Review config/auth.php (published by the package) for customization (e.g., redirect paths, guard settings).
   • Ensure your User model extends SquareNetMedia\Auth\Models\User (or implements SquareNetMedia\Auth\Contracts\Authenticatable).

3. First Use Case: Basic Registration

   • Add the registration route in routes/web.php:

     Route::get('/register', [\SquareNetMedia\Auth\Controllers\AuthController::class, 'showRegistrationForm'])->name('register');
     Route::post('/register', [\SquareNetMedia\Auth\Controllers\AuthController::class, 'register']);
     

   • Use the provided Blade views (published to resources/views/vendor/auth) or extend them.

Implementation Patterns

Core Workflows

1. Authentication Stack

   • The package integrates with Laravel’s built-in Auth facade but provides pre-built controllers (AuthController) and middleware (auth, guest).
   • Extend SquareNetMedia\Auth\Controllers\AuthController to customize logic (e.g., override validateLogin for custom rules).

2. Registration Customization

   • Validation: Extend the register method or use form requests:

     use SquareNetMedia\Auth\Requests\RegisterRequest;
     

   • User Creation: Override createUser() in a service or controller to add custom fields:

     protected function createUser(array $data) {
         return User::create([
             ...$data,
             'custom_field' => $data['custom_field'] ?? null,
         ]);
     }
     

3. Password Reset

   • Use the built-in PasswordResetController or extend it:

     Route::post('/password/reset', [\SquareNetMedia\Auth\Controllers\PasswordResetController::class, 'sendResetLink']);
     

4. Blade Components

   • Leverage @auth, @guest, and @authenticate directives in Blade templates.
   • Extend views by copying resources/views/vendor/auth to resources/views/auth and modifying.

5. API Authentication

   • The package includes Sanctum support out-of-the-box. Enable it in config/auth.php:

     'api' => [
         'driver' => 'sanctum',
         'provider' => 'users',
     ],
     

Integration Tips

• Database Migrations: The package includes a users table migration. If you’ve already migrated, skip or modify it.
• Testing: Use the AuthTestCase trait for testing auth flows:

  use SquareNetMedia\Auth\Tests\AuthTestCase;
  
  class ExampleTest extends AuthTestCase {
      public function test_registration() { ... }
  }
  

• Social Logins: Integrate with Laravel Socialite by extending the AuthController and adding routes for providers (e.g., Google, GitHub).

Gotchas and Tips

Pitfalls

1. Middleware Conflicts

   • If using custom middleware, ensure it doesn’t override the package’s auth middleware. Check app/Http/Kernel.php for conflicts.

2. View Overrides

   • Forgetting to publish views (--tag="auth-views") will break Blade rendering. Always publish assets first.

3. Sanctum API Tokens

   • If using Sanctum, ensure the api guard is properly configured in config/auth.php. Missing this will cause 401 errors on API routes.

4. Password Reset Tokens

   • The package uses Laravel’s default token expiration (60 minutes). Customize in App\Providers\AppServiceProvider:

     use Illuminate\Auth\Notifications\ResetPassword;
     ResetPassword::createUrlUsing(...);
     

5. User Model Binding

   • The package assumes your User model implements SquareNetMedia\Auth\Contracts\Authenticatable. If not, override the resolveUser() method in the AuthServiceProvider.

Debugging Tips

• Log Authentication Events Enable Laravel’s auth logging in config/auth.php:

  'log_attempts' => env('AUTH_LOG_ATTEMPTS', true),
  

• Check Token Expiry For Sanctum, verify token expiry in .env:

  SANCTUM_EXPIRE=PT1H  # 1 hour
  

• Validate Email Verification If using email verification, ensure the verified column exists in the users table and the VerifyEmail trait is applied to your User model.

Extension Points

1. Custom Guards Add a new guard in config/auth.php:

   'guards' => [
       'admin' => [
           'driver' => 'session',
           'provider' => 'admins',
       ],
   ],
   

   Then create a custom provider and guard.

2. Two-Factor Auth (2FA) Integrate with Laravel’s two-factor package and extend the AuthController to handle 2FA flows.

3. Role-Based Access Use middleware like role:admin by extending the package’s middleware or integrating with a package like spatie/laravel-permission.

4. Custom User Fields Extend the User model and update the registration form/request:

   // app/Http/Requests/CustomRegisterRequest.php
   public function rules() {
       return [
           'name' => 'required|string',
           'email' => 'required|email',
           'custom_field' => 'required|string',
       ];
   }