Auth Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require colbeh/auth
   

   Publish the package configuration and migrations:

   php artisan vendor:publish --provider="Colbeh\Auth\AuthServiceProvider" --tag="migrations"
   php artisan vendor:publish --provider="Colbeh\Auth\AuthServiceProvider" --tag="config"
   

   Run migrations:

   php artisan migrate
   

2. Configuration Update .env with your desired auth driver (e.g., database, ldap, or oauth). Modify config/auth.php to align with the package’s expected structure (e.g., providers and guards).

3. First Use Case: Basic Login Use the provided facade or service to authenticate:

   use Colbeh\Auth\Facades\Auth;
   
   $credentials = ['email' => '[email protected]', 'password' => 'password'];
   if (Auth::attempt($credentials)) {
       $user = Auth::user();
       // Redirect or proceed...
   }
   

4. Routes Register auth routes in routes/web.php:

   Route::auth(); // Uses package's default routes (login, register, logout)
   

Implementation Patterns

Core Workflows

1. Authentication

   • Facade Usage:

     Auth::login($user); // Manually log in a user
     Auth::logout();     // Log out current user
     Auth::attempt($credentials); // Attempt login
     

   • Middleware: Use auth or guest middleware (package-compatible) in routes/controllers:

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

2. Registration

   • Extend the RegisterController (if provided) or use the facade:

     $user = Auth::register([
         'name' => 'John Doe',
         'email' => '[email protected]',
         'password' => bcrypt('password'),
     ]);
     

3. Password Reset

   • Use the Password facade or leverage built-in routes:

     use Colbeh\Auth\Facades\Password;
     
     $response = Password::sendResetLink(['email' => '[email protected]']);
     

4. Custom Guards

   • Configure guards in config/auth.php:

     'guards' => [
         'api' => [
             'driver' => 'token',
             'provider' => 'users',
         ],
     ],
     

   • Use guards in code:

     Auth::guard('api')->attempt($credentials);
     

5. Session Handling

   • Regenerate session ID:

     Auth::regenerateSessionId();
     

   • Check auth status:

     if (Auth::check()) {
         // User is authenticated
     }
     

Integration Tips

1. Laravel Ecosystem

   • Works seamlessly with Laravel’s built-in auth features (e.g., Auth::user() returns a User model).
   • Customize user model by extending Colbeh\Auth\Models\User or binding your own model.

2. API Authentication

   • For API tokens, use Laravel’s Sanctum or Passport alongside this package. Configure the api guard to use token driver.

3. Social Logins (OAuth)

   • If the package supports OAuth, configure providers in config/services.php and use:

     Auth::loginUsingId($providerUserId);
     

4. Event Listeners

   • Listen to auth events (e.g., auth.login, auth.logout) via Event::listen or service providers.

5. Testing

   • Use Auth::actingAs($user) in tests to simulate authentication:

     $this->actingAs($user)->get('/profile');
     

Gotchas and Tips

Pitfalls

1. Migration Conflicts

   • The package’s migrations might conflict with Laravel’s default users table. Solution:
     • Rename the package’s table in config/auth.php or drop existing migrations before running php artisan migrate.

2. Deprecated Methods

   • The package may use older Laravel auth methods (e.g., Auth::once()). Solution:
     • Check the package’s README or source code for deprecated features. Update to modern Laravel auth patterns if needed.

3. No Built-in Views

   • The package likely lacks default Blade views (login/register). Solution:
     • Use Laravel’s default auth views or create custom ones in resources/views/auth.

4. LDAP/OAuth Limitations

   • If using LDAP or OAuth, ensure the package supports these drivers. Solution:
     • Verify configuration in config/auth.php and install required PHP extensions (e.g., php-ldap).

5. Session Driver Issues

   • If using database or redis session driver, ensure the session table is properly configured. Solution:
     • Run php artisan session:table and migrate if needed.

Debugging

1. Authentication Failures

   • Check config/auth.php for correct provider and guard settings.
   • Verify credentials in the database (e.g., hashed passwords):

     dd(Hash::check('plain-text', $user->password)); // Debug password hashing
     

2. Route Conflicts

   • If routes like /login conflict with existing routes, override them in routes/web.php:

     Route::get('/custom-login', [AuthController::class, 'showLoginForm'])->name('login');
     

3. Logging

   • Enable Laravel’s debug mode (APP_DEBUG=true in .env) and check logs in storage/logs/laravel.log for auth errors.

Extension Points

1. Custom User Model

   • Bind your user model in AuthServiceProvider:

     public function boot()
     {
         $this->app['auth']->extend('custom', function ($app) {
             return new CustomAuthGuard($app['auth']->createUserProvider('eloquent'));
         });
     }
     

2. Custom Auth Logic

   • Override the AuthManager or Guard implementations by publishing and modifying the package’s source files (located in vendor/colbeh/auth).

3. Adding Fields to Registration

   • Extend the registration form and User model:

     // In User model
     protected $fillable = ['name', 'email', 'password', 'phone'];
     
     // In RegisterController (if provided)
     public function validator(array $data)
     {
         return Validator::make($data, [
             'phone' => 'required|unique:users',
             // ...
         ]);
     }
     

4. Two-Factor Authentication (2FA)

   • If not supported, integrate Laravel’s two-factor package or implement custom logic using the package’s auth events.

5. Rate Limiting

   • Protect auth routes with Laravel’s throttle middleware:

     Route::post('/login', [AuthController::class, 'login'])->middleware('throttle:5,1');