Multisource Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require an3/multisource
   

   Publish the config file:

   php artisan vendor:publish --provider="An3\Multisource\MultisourceServiceProvider"
   

2. Configure Sources Edit config/multisource.php to define your login sources (e.g., email, username, phone):

   'sources' => [
       'email' => 'email',
       'username' => 'username',
       'phone' => 'phone',
   ],
   

3. Extend User Model Ensure your User model implements An3\Multisource\Contracts\MultisourceUser:

   use An3\Multisource\Contracts\MultisourceUser;
   
   class User extends Authenticatable implements MultisourceUser
   {
       // ...
   }
   

4. First Use Case: Login Replace Auth::attempt() with the package’s method:

   use An3\Multisource\Facades\Multisource;
   
   $credentials = ['username' => 'john_doe', 'password' => 'secret'];
   if (Multisource::attempt($credentials)) {
       // Authenticated
   }
   

Implementation Patterns

1. Dynamic Source Handling

• Workflow: Let users log in via any configured source without modifying logic.

  $credentials = ['phone' => '+1234567890', 'password' => 'password123'];
  if (Multisource::attempt($credentials)) {
      // Works for email/username/phone if configured
  }
  

2. Custom Validation Rules

• Extend Validation: Add rules to app/Providers/AppServiceProvider:

  use An3\Multisource\Multisource;
  
  public function boot()
  {
      Multisource::extend('phone', function ($source, $value) {
          return Validator::make(['phone' => $value], [
              'phone' => 'required|digits:10|starts_with:1',
          ])->passes();
      });
  }
  

3. Integration with Existing Auth

• Replace Auth::attempt: Override app/Providers/AuthServiceProvider:

  protected function authenticate()
  {
      return Multisource::attempt($this->credentials);
  }
  

4. API Authentication

• Sanctum/Passport: Works seamlessly with Laravel’s token-based auth:

  $token = Multisource::attempt($credentials)
      ? Auth::user()->createToken('API Token')->plainTextToken
      : null;
  

5. Fallback Logic

• Prioritize Sources: Configure fallback order in config/multisource.php:

  'fallback' => ['email', 'username', 'phone'],
  

Gotchas and Tips

Pitfalls

1. Missing MultisourceUser Contract

   • Symptom: Class User does not implement MultisourceUser.
   • Fix: Ensure your User model implements An3\Multisource\Contracts\MultisourceUser.

2. Case-Sensitive Sources

   • Symptom: Login fails for Phone but works for phone.
   • Fix: Normalize keys in config/multisource.php:

     'sources' => [
         'phone' => 'phone', // Must match DB column exactly
     ],
     

3. Validation Short-Circuiting

   • Symptom: Custom validation rules aren’t triggered.
   • Fix: Ensure extend() is called before Multisource::attempt().

4. Password Hashing Mismatch

   • Symptom: Hash::check() fails silently.
   • Fix: Verify password column in users table uses Laravel’s bcrypt hashing.

Debugging Tips

• Log Failed Attempts:

  Multisource::attempt($credentials, function ($source, $value) {
      \Log::debug("Failed login for $source: $value");
  });
  

• Check Config:

  php artisan config:clear
  

  Then verify config/multisource.php is loaded.

Extension Points

1. Custom Guards Override MultisourceGuard in app/Providers/AuthServiceProvider:

   Multisource::guard(function ($app) {
       return new CustomMultisourceGuard($app['auth']->createUserProvider());
   });
   

2. Dynamic Source Discovery Fetch sources from a DB table:

   Multisource::setSources(function () {
       return Source::all()->pluck('key')->toArray();
   });
   

3. Rate Limiting Integrate with Laravel’s throttle middleware:

   Route::post('/login', function () {
       return Multisource::attempt(request()->only(['source', 'value', 'password']))
           ? response()->json(['success' => true])
           : response()->json(['error' => 'Invalid credentials'], 429);
   })->middleware('throttle:5,1');