Laravel Auth Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require joe-404/laravel-auth
   php artisan auth:install
   

   • Automatically installs Sanctum, Socialite, and Spatie Permissions.

2. User Model: Add traits to app/Models/User.php:

   use HasApiTokens, HasRoles, Notifiable, SoftDeletes, HasAccountStatus;
   

3. Environment: Set .env variables (minimal):

   AUTH_MODE=both
   AUTH_VERIFICATION_METHOD=both
   MAIL_MAILER=smtp
   MAIL_FROM_ADDRESS=hello@yourapp.com
   

4. First Use Case: Test registration flow:

   curl -X POST http://localhost/auth/register -H "Content-Type: application/json" -d '{"email":"test@example.com"}'
   

   Follow with OTP verification and completion.

Implementation Patterns

Core Workflows

1. Registration Flow:

   • Step 1: Submit email → receive temp_token (OTP + magic link).
   • Step 2: Verify OTP → receive completion_token.
   • Step 3: Set password → create user + issue tokens.

2. Login/Logout:

   • Use /auth/login (password) or /auth/social/google/redirect (OAuth).
   • Logout via /auth/logout (current session) or /auth/logout/all (all sessions).

3. Password Management:

   • Forgot password: /auth/password/forgot → OTP → /auth/password/reset/confirm.
   • Change password (authenticated): /auth/password/change.

4. API Tokens:

   • List/create/revoke tokens via /auth/api-tokens (user-scoped) or /auth/admin/api-tokens (admin).

5. Account Status:

   • Admins manage user status via /auth/admin/users/{id}/status.
   • Users self-deactivate via /auth/account/deactivate.

Integration Tips

• Frontend Agnostic: All endpoints return JSON; no frontend coupling.
• Config-Driven: Customize behavior via config/auth_system.php (e.g., disable OTP, enforce 2FA).
• Events: Extend workflows via events (e.g., AccountRegistered, PasswordReset).
• Real-Time: Use Reverb for instant verification (e.g., magic links).
• Audit Logs: Track account status changes via deleted_accounts table.

Example: Customizing Registration

Override default fields in config/auth_system.php:

'registration' => [
    'fields' => [
        'email' => true,
        'name' => true,
        'phone' => false, // Disable phone field
        'terms_accepted' => true,
    ],
],

Gotchas and Tips

Pitfalls

1. OTP/Magic Link Expiry:

   • Default expiry: 10 minutes (configurable via AUTH_VERIFICATION_EXPIRY_MINUTES).
   • Resend OTPs with /auth/email/resend-verification.

2. Session Management:

   • Sanctum sessions are revoked on logout but not automatically cleaned up. Run php artisan sanctum:prune periodically.

3. Account Deletion:

   • Grace Period: Default 30 days. Users can auto-restore by logging in.
   • Hard Deletion: If hard_delete_after_grace=true, the users row is permanently deleted after grace. Ensure deleted_accounts table retains audit data.

4. Google OAuth:

   • Redirect URI must match config/services/google.callback (default: http://localhost/auth/social/google/callback).
   • Test locally with AUTH_SOCIAL_GOOGLE_ENABLED=true in .env.

5. Unique Columns:

   • If null_uniques_after_grace=true, unique fields (e.g., email) are nulled post-grace. Ensure your app handles this (e.g., no duplicate emails).

Debugging

• Logs: Enable AUTH_DEBUG=true in .env for verbose logging.
• Events: Listen to AccountDeleted or AccountRestored for custom logic:

  Event::listen(AccountDeleted::class, function ($event) {
      // Custom logic (e.g., notify admins)
  });
  

• Queue Workers: Run php artisan queue:work to process deferred tasks (e.g., purge worker).

Extension Points

1. Custom Verification: Override Joe404\LaravelAuth\Contracts\VerificationService to add SMS/phone verification.

2. Email Templates: Publish and override templates:

   php artisan vendor:publish --tag=laravel-auth-views
   

   Edit resources/views/vendor/laravel-auth/emails/otp.blade.php.

3. Account Status Middleware: Use auth.active middleware to restrict access:

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

4. Referral Codes: Enable via config:

   'referrals' => [
       'enabled' => true,
       'field' => 'referral_code',
   ],
   

   Add to registration fields and track via ReferralCreated event.

Config Quirks

• AUTH_MODE:
  • web: Session-based auth (cookies).
  • api: Token-based (Sanctum).
  • both: Hybrid (default).
• AUTH_VERIFICATION_METHOD:
  • otp: One-time password.
  • magic: Magic links.
  • both: Both (default).
• Redis: Required for token storage and rate limiting. Use predis or phpredis.

Performance

• Rate Limiting: Enabled by default (e.g., 5 login attempts/minute). Adjust via AUTH_RATE_LIMIT.
• Queue Jobs: Heavy operations (e.g., email sending) are queued. Ensure your queue worker is running.