Laravel 郵件整合套件

📬 Gmail 操作套件：dacastro4/laravel-gmail

套件簡介

dacastro4/laravel-gmail 是一個封裝 Gmail API 的 Laravel 套件，支援以下功能：

  • 整合 Gmail 功能到 Laravel 專案
  • 讀取 / 發送 Gmail 郵件
  • 管理標籤
  • 搜尋郵件
  • 使用 Laravel 的服務提供者與設定檔方式進行整合
  • 管理 OAuth2 認證流程

安裝套件

composer require dacastro4/laravel-gmail

設定 Gmail API

  1. 前往 Google 開發者控制台
  2. 建立專案並啟用 Gmail API
  3. 建立 OAuth 2.0 憑證，取得 client_id、client_secret 與 redirect_uri

設定 Laravel 專案

1. 在 config/services.php 中加入：

'gmail' => [
    'client_id' => env('GMAIL_CLIENT_ID'),
    'client_secret' => env('GMAIL_CLIENT_SECRET'),
    'redirect' => env('GMAIL_REDIRECT_URI'),
],

2. 在 .env 中新增：

GMAIL_CLIENT_ID=your-client-id
GMAIL_CLIENT_SECRET=your-client-secret
GMAIL_REDIRECT_URI=https://your-app.com/gmail/callback

設定授權流程

建立控制器

php artisan make:controller GmailController

控制器方法範例

use LaravelGmail;

public function requestGmailAuthorization()
{
    LaravelGmail::getClient()->setApprovalPrompt('force');
    return LaravelGmail::redirect();
}

public function handleGmailCallback()
{
    LaravelGmail::makeToken();
    // 令牌已保存，可開始操作 Gmail
}

路由設定

Route::get('gmail/auth', [GmailController::class, 'requestGmailAuthorization']);
Route::get('gmail/callback', [GmailController::class, 'handleGmailCallback']);

錯誤處理

⚠️ OAuth token 無法刷新

錯誤訊息：

refresh token must be passed in or set as part of setAccessToken

解法：刪除 /storage/app/gmail/tokens/gmail-json.json 檔案內容（或清空 tokens 陣列）。

⚠️ 無法使用 CC 寄送

錯誤訊息：

Symfony\Component\Mime\Email::cc(): Argument #1 must be of type Symfony\Component\Mime\Address|string, array given

說明：從 v6.1 開始預設使用 Symfony Mail，而非 SwiftMailer。
解法：如遇相容性問題可降版至 v6.0： 

composer require dacastro4/laravel-gmail:^6.0

📥 郵件記錄與排程套件：stackkit/laravel-database-emails

套件簡介

stackkit/laravel-database-emails 是用於將發送的郵件儲存在資料庫中的 Laravel 套件，支援以下功能：

  • 將所有寄送的郵件存入資料庫
  • 方便開發測試，避免寄出實體郵件
  • 可重新發送記錄過的郵件
  • 可排程延遲寄送
  • 支援 Laravel 的 Mailable、附件、HTML、收件人等完整功能

安裝套件

composer require stackkit/laravel-database-emails

發布設定檔

php artisan vendor:publish --tag=laravel-database-emails-config

資料表遷移

php artisan migrate

使用範例

建立一封郵件

use Stackkit\LaravelDatabaseEmails\Email;

Email::compose()
    ->label('welcome')
    ->recipient('[email protected]')
    ->subject('這是一封測試郵件')
    ->view('emails.welcome')
    ->variables(['name' => '約翰·道'])
    ->send();

多收件人

Email::compose()
    ->recipient(['[email protected]', '[email protected]']);

CC / BCC

Email::compose()
    ->cc(['[email protected]', '[email protected]'])
    ->bcc(['[email protected]', '[email protected]']);

使用 Mailable 寄送

Email::compose()
    ->mailable(new \App\Mail\OrderShipped())
    ->send();

附加檔案 / 內存附件

Email::compose()
    ->attach('/path/to/file');

Email::compose()
    ->attachData('<p>內容</p>', 'test.html');

自定義寄件人

Email::compose()
    ->from('[email protected]', '系統通知');

延遲寄送

Email::compose()
    ->later('+2 hours'); // 或 Carbon::now()->addMinutes(30)

📌 備註：這兩個套件用途不同，laravel-gmail 側重於操作 Gmail 郵件（OAuth 與 Gmail API），而 laravel-database-emails 側重於記錄郵件發送與測試階段的非寄送模式，建議依需求選擇使用。