# Social Login Module Usage Instructions

> The `feat/user-social-login` branch introduces OAuth-based Single Sign-On (SSO) capabilities using **Laravel Socialite**. Integrated directly with the base branch, it provides a frictionless registration and login experience for users via Google and Facebook.

---

## Table of Contents

1. [Module Overview](#1-module-overview)
2. [What You Inherit](#2-what-you-inherit)
3. [Deep Dive: Features & Functionality](#3-deep-dive-features--functionality)
4. [File Paths & Architecture](#4-file-paths--architecture)
5. [Step-by-Step Usage Guide](#5-step-by-step-usage-guide)

---

## 1. Module Overview

This module enables users to bypass traditional email/password registration by authenticating through third-party providers (Google and Facebook). It securely fetches user profiles from these providers, maps them to local `User` accounts, and maintains a dedicated table to link multiple social identities to a single user.

---

## 2. What You Inherit

By merging with the **Base** branch, this feature inherits:
- **Authentication Flows:** Hooks natively into the default `auth:user` guard.
- **Blade UI Architecture:** A new reusable component (`<x-common.auth.social-buttons>`) is introduced. It seamlessly integrates into the base auth layouts (Login/Register screens).

---

## 3. Deep Dive: Features & Functionality

- **Smart Dynamic Buttons:**
  The `<x-common.auth.social-buttons>` Blade component is environment-aware. It checks if the `client_id` and `client_secret` are set in `.env` for Google or Facebook. If they are missing, the buttons hide automatically, preventing broken login links in production.
- **Automatic Account Creation:**
  When a user logs in via a social provider for the first time, the system parses their `name` (splitting it into `first_name` and `last_name`), captures their `email`, generates a secure random password, and provisions a new account instantly.
- **Secure Account Linking:**
  If an existing user (who registered via email/password) tries to log in using Google, the system detects the matching email, logs them in, and securely links their Google `provider_id` to their account via the `user_social_accounts` table.
- **Error Handling:**
  If a social account (like an unverified Facebook account) does not return an email address, the system catches it, blocks the login, and flashes a secure error message prompting the user to use an alternative method.

---

## 4. File Paths & Architecture

Here are the key structural areas introduced:

### Core Configuration
- **`config/services.php`**: Updated to include configuration blocks for `google` and `facebook`.
- **`composer.json`**: Requires the `laravel/socialite` package.

### Controllers & Models
- **`app/Http/Controllers/SocialAuthController.php`**: The engine driving the Socialite redirect and callback processes. Handles the "User create or link" business logic.
- **`app/Models/UserSocialAccount.php`**: An Eloquent model representing the new table.
- **`app/Models/User.php`**: Updated to include a `hasMany` relationship (`socialAccounts()`).

### Database
- **`database/migrations/*_create_user_social_accounts_table.php`**: Creates the pivot table storing `provider`, `provider_id`, `token`, and `refresh_token`.

### Views & Routes
- **`resources/views/components/common/auth/social-buttons.blade.php`**: The reusable UI component rendering the Google and Facebook SVG buttons.
- **`routes/user.php`**: Adds the `{provider}/redirect` and `{provider}/callback` endpoints.

---

## 5. Step-by-Step Usage Guide

### 1. Database Setup
Run the migrations to create the `user_social_accounts` table:
```bash
php artisan migrate
```

### 2. Environment Configuration
To enable the social buttons on the frontend, you must populate your `.env` file with the OAuth credentials obtained from the Google Cloud Console and Facebook Developer Portal.

```env
# Google OAuth
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"
GOOGLE_REDIRECT_URI="${APP_URL}/account/auth/google/callback"

# Facebook OAuth
FACEBOOK_CLIENT_ID="your-facebook-client-id"
FACEBOOK_CLIENT_SECRET="your-facebook-client-secret"
FACEBOOK_REDIRECT_URI="${APP_URL}/account/auth/facebook/callback"
```

### 3. Frontend Integration
The social buttons component can be dropped into any auth view (e.g., `login.blade.php` or `register.blade.php`):
```html
<x-common.auth.social-buttons :topDivider="true" />
```
*(Note: If the environment variables are empty, this component will output nothing).*

### 4. Testing
- Go to your application's login page. The Google and Facebook buttons should now be visible.
- Click **Continue with Google**.
- Authenticate on Google's consent screen.
- You will be redirected back to the app and instantly logged into the User Dashboard.