> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Socialite for Discord

> 以 Laravel Socialite 實作 Discord OAuth2 認證的驅動程式套件。

## 概覽

[revolution/socialite-discord](https://github.com/invokable/socialite-discord) 是能讓 Laravel Socialite 使用 Discord OAuth2 認證的驅動程式套件。

Laravel Socialite 內建的 provider 並未包含 Discord。只要安裝這個套件，就可以透過 `Socialite::driver('discord')` 為你的應用程式加入 Discord 登入。

<Info>
  關於 Laravel Socialite 本身的使用方式，請參閱 [Socialite 指南](/zh-TW/socialite)。
</Info>

## 安裝

```shell theme={null}
composer require revolution/socialite-discord
```

## 設定

### 在 Discord Developer Portal 註冊應用程式

在 [Discord Developer Portal](https://discord.com/developers/applications) 建立應用程式，並從 **OAuth2** 區段取得 Client ID 與 Client Secret。請在 **Redirects** 加入回呼 URL（例如：`https://example.com/auth/discord/callback`）。

### config/services.php

```php theme={null}
'discord' => [
    'client_id'     => env('DISCORD_CLIENT_ID'),
    'client_secret' => env('DISCORD_CLIENT_SECRET'),
    'redirect'      => env('DISCORD_REDIRECT'),
],
```

### .env

```dotenv theme={null}
DISCORD_CLIENT_ID=your-client-id
DISCORD_CLIENT_SECRET=your-client-secret
DISCORD_REDIRECT=https://example.com/auth/discord/callback
```

## 基本用法

<Steps>
  <Step title="定義路由">
    在 `routes/web.php` 加入兩條路由，分別用於重新導向與回呼。

    ```php theme={null}
    use App\Http\Controllers\SocialiteController;

    Route::get('auth/discord', [SocialiteController::class, 'login']);
    Route::get('auth/discord/callback', [SocialiteController::class, 'callback']);
    ```
  </Step>

  <Step title="建立控制器">
    ```php theme={null}
    <?php

    namespace App\Http\Controllers;

    use Laravel\Socialite\Facades\Socialite;

    class SocialiteController extends Controller
    {
        public function login()
        {
            return Socialite::driver('discord')->redirect();
        }

        public function callback()
        {
            $discordUser = Socialite::driver('discord')->user();

            // $discordUser->getId()        Discord 使用者 ID
            // $discordUser->getName()      使用者名稱
            // $discordUser->getEmail()     電子郵件（需要 email scope）
            // $discordUser->getAvatar()    頭像 URL
            // $discordUser->token          access token

            $user = \App\Models\User::updateOrCreate(
                ['discord_id' => $discordUser->getId()],
                ['name' => $discordUser->getName()]
            );

            \Illuminate\Support\Facades\Auth::login($user);

            return redirect('/dashboard');
        }
    }
    ```
  </Step>
</Steps>

## Scope 設定

Discord OAuth2 以 scope 指定要取得的權限。預設 scope 僅為 `identify`。

```php theme={null}
public function login()
{
    return Socialite::driver('discord')
                    ->setScopes(['identify', 'email', 'guilds', 'guilds.join'])
                    ->redirect();
}
```

主要 scope 一覽：

| Scope         | 可取得的資訊              |
| ------------- | ------------------- |
| `identify`    | 使用者 ID、使用者名稱、頭像（預設） |
| `email`       | 電子郵件                |
| `guilds`      | 已加入的伺服器清單           |
| `guilds.join` | 將使用者加入伺服器的權限        |

<Tip>
  所有 scope 請參閱 [Discord OAuth2 文件](https://discord.com/developers/docs/topics/oauth2#shared-resources-oauth2-scopes)。
</Tip>

## 使用者的儲存與登入

在回呼路由中取得使用者資訊，儲存到資料庫再登入的典型實作範例：

```php theme={null}
use App\Models\User;
use Illuminate\Support\Facades\Auth;
use Laravel\Socialite\Facades\Socialite;

public function callback()
{
    $discordUser = Socialite::driver('discord')->user();

    $user = User::updateOrCreate(
        ['discord_id' => $discordUser->getId()],
        [
            'name'          => $discordUser->getName(),
            'email'         => $discordUser->getEmail(),
            'discord_token' => $discordUser->token,
        ]
    );

    Auth::login($user);

    return redirect('/dashboard');
}
```

<Warning>
  取得 `email` 需要 `email` scope。若未指定 scope，`getEmail()` 可能會回傳 `null`。
</Warning>

## 與其他 Socialite 驅動程式的比較

本套件採用 `Socialite::extend()` 這種正規做法實作，因此可以用與內建 provider 完全相同的 API 使用。關於自訂 provider 的機制與 `Socialite::extend()` 的細節，請參閱 [Socialite 指南](/zh-TW/socialite)。

<Info>
  最新資訊請參閱 [GitHub 儲存庫](https://github.com/invokable/socialite-discord)。
</Info>


## Related topics

- [Laravel Socialite（社群認證）](/zh-TW/socialite.md)
- [我的包](/zh-CN/packages/index.md)
- [Laravel Notification for Discord(Webhook)](/zh-TW/packages/laravel-notification-discord-webhook.md)
- [Socialite - Laravel Bluesky](/zh-TW/packages/laravel-bluesky/socialite.md)
- [Envoy](/zh-TW/envoy.md)