在 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
判斷,讓程式碼更乾淨、更高效!