Laravel when() 方法教學

在 Laravel 的 Eloquent 查詢中，通常我們會根據使用者輸入的條件來動態篩選資料，例如：

• 關鍵字搜尋（name）
• 範圍查詢（如 height）
• 特定條件（如 country_id）

Laravel 提供了 when() 方法，讓我們可以根據是否有提供值來決定是否加入某個查詢條件，避免不必要的 if 判斷。

1. when() 方法的基本語法

$query->when(條件, function ($q) {
    $q->where(條件);
});

• 條件：如果這個條件為 true，則執行 function 內的 where() 條件。
• $q（Query Builder）：代表當前的查詢物件。

2. when() 基本範例

傳統 if 判斷

$query = User::query();

if ($request->filled('keyword')) {
    $query->where('name', 'like', "%{$request->keyword}%");
}

$users = $query->get();

這種寫法雖然可以用，但如果有很多條件，if 會讓程式碼變得冗長。

使用 when() 優化

$query = User::query();

$query->when($request->input('keyword'), function ($q, $keyword) {
    $q->where('name', 'like', "%{$keyword}%");
});

$users = $query->get();

• 當 keyword 存在時，才會執行 where('name', 'like', "%{$keyword}%")。
• 當 keyword 沒有輸入時，這條查詢條件就不會被加進去。

這樣可以減少 if 判斷，使程式碼更簡潔。

3. 多個搜尋條件的 when() 應用

當有多個條件時，when() 可以幫助我們避免過多的 if 判斷。

搜尋「關鍵字 + 身高範圍 + 國籍」

$query = User::query();

// 關鍵字搜尋（姓名）
$query->when($request->input('keyword'), function ($q, $keyword) {
    $q->where('name', 'like', "%{$keyword}%");
});

// 身高範圍（最小身高）
$query->when($request->input('min_height'), function ($q, $min) {
    $q->where('height', '>=', $min);
});

// 身高範圍（最大身高）
$query->when($request->input('max_height'), function ($q, $max) {
    $q->where('height', '<=', $max);
});

// 根據國籍搜尋
$query->when($request->input('country_id'), function ($q, $countryId) {
    $q->where('country_id', $countryId);
});

$users = $query->get();

這樣，只有當對應的參數存在時，才會執行相應的 where() 條件，讓查詢更靈活！ 

4. when() 搭配 whereIn() 

如果 country_id 需要支援多選（多個國籍），可以使用 whereIn()：

$query->when($request->input('country_ids'), function ($q, $countryIds) {
    $q->whereIn('country_id', $countryIds);
});

5. when() 搭配 orWhere()

如果需要搜尋關鍵字可以匹配多個欄位（例如 name 或 email），可以這樣寫：

$query->when($request->input('keyword'), function ($q, $keyword) {
    $q->where('name', 'like', "%{$keyword}%")
      ->orWhere('email', 'like', "%{$keyword}%");
});

這樣，當 keyword 存在時，會搜尋 name 和 email 兩個欄位。 

6. when() 的第三個參數 

when() 也可以接受 第三個參數，這是一個 else 條件，當條件為 false 時執行：

$query->when($request->input('active'), function ($q) {
    $q->where('status', 'active');
}, function ($q) {
    $q->where('status', 'inactive');
});

這樣：

• 當 active 存在時，搜尋 status = active
• 當 active 不存在時，搜尋 status = inactive

總結

when() 方法是 Laravel 查詢時的強大工具，可以根據是否提供參數來決定是否加入條件。
透過 when()，可以讓查詢語法變得簡潔、可讀性更高。
可搭配 whereIn()、orWhere() 來實現更複雜的查詢邏輯。

如果你的查詢條件很多，推薦使用 when()，避免多個 if 判斷，讓程式碼更乾淨、更高效！