Laravel 數據庫之：數據庫請求構建器

簡介

Laravel 的數據庫查詢構造器提供了一個方便的接口來創建及運行數據庫查詢語句。它能用來執行應用程序中的大部分數據庫操作，且能在所有被支持的數據庫系統中使用。

Laravel 的查詢構造器使用 PDO 參數綁定來保護你的應用程序免受 SQL 注入的攻擊。因此沒有必要清理作爲綁定傳遞的字符串。

獲取結果

從數據表中獲取所有的數據

你可以在 DB facade 上使用 table 方法開始查詢。這個 table 方法爲給定的表返回一個查詢構造器實例，允許你在查詢上鍊式調用更多的約束，最後使用 get 方法獲取最終結果：

<?php
namespace App\Http\Controllers;
use Illuminate\Support\Facades\DB;
use App\Http\Controllers\Controller;
class UserController extends Controller
{
    /**
     * 顯示所有應用程序用戶的列表
     *
     * @return Response
     */
    public function index()
    {
        $users = DB::table('users')->get();

        return view('user.index', ['users' => $users]);
    }
}

get 方法會返回一個包含 IlluminateSupportCollection 的結果，其中每個結果都是一個 PHP StdClass 對象的一個實例。你可以通過訪問字段作爲對象的屬性來訪問每列的值：

foreach ($users as $user) {
    echo $user->name;
}

從數據表中獲取單個列或行

如果你只需要從數據庫表中獲取一行數據，就使用 first 方法。這個方法將返回一個 StdClass 對象：

$user = DB::table('users')->where('name', 'John')->first();
echo $user->name;

如果你甚至不需要整行數據，就使用 value 方法從記錄中取出單個值。該方法將直接返回字段的值：

$email = DB::table('users')->where('name', 'John')->value('email');

獲取一列的值

如果你想要獲取包含單個字段值的集合，可以使用 pluck 方法。在下面的例子中，我們將取出 roles 表中 title 字段的集合：

$titles = DB::table('roles')->pluck('title');
foreach ($titles as $title) {
    echo $title;
}

你也可以在返回的集合中指定字段的自定義鍵值：

$roles = DB::table('roles')->pluck('title', 'name');
foreach ($roles as $name => $title) {
    echo $title;
}

結果分塊

如果你需要操作數千條數據庫記錄，可以考慮使用 chunk 方法。這個方法每次只取出一小塊結果傳遞給閉包處理，這對於編寫數千條記錄的 Artisan 命令而言是非常有用的。例如，一次處理整個 users 表中的 100 個記錄：

DB::table('users')->orderBy('id')->chunk(100, function ($users) {
    foreach ($users as $user) {
    }
});

你可以從閉包中返回 false 來阻止進一步的分塊的處理：

DB::table('users')->orderBy('id')->chunk(100, function ($users) {
    // Process the records...
    return false;
});

聚合

查詢構造器還提供了各種聚合方法，如 count、 max、 min、 avg 和 sum。你可以在創建查詢後調用其中的任意一個方法：

$users = DB::table('users')->count();
$price = DB::table('orders')->max('price');

當然，你也可以將這些方法和其它語句結合起來：

$price = DB::table('orders')
                ->where('finalized', 1)
                ->avg('price');

Selects

指定一個 Select 語句

你並不會總是想從數據表中選出所有的字段，這時可使用 select 方法自定義一個 select 語句來指定查詢的字段：

$users = DB::table('users')->select('name', 'email as user_email')->get();

distinct 方法允許你強制讓查詢返回不重複的結果：

$users = DB::table('users')->distinct()->get();

如果你已有一個查詢構造器實例，並且希望在現有的 select 語句中加入一個字段，則可以使用 addSelect 方法：

$query = DB::table('users')->select('name');
$users = $query->addSelect('age')->get();

原生表達式

有時候你可能需要在查詢中使用原生表達式，使用 DB::raw 方法可以創建原生表達式：

$users = DB::table('users')
                     ->select(DB::raw('count(*) as user_count, status'))
                     ->where('status', '<>', 1)
                     ->groupBy('status')
                     ->get();

{note} 原生表達式將會被當作字符串注入到查詢中，所以要小心避免創建 SQL 注入漏洞。

原生方法

可以使用以下的方法代替 DB::raw 將原生表達式插入查詢的各個部分。

selectRaw

selectRaw 方法可以用來代替 select(DB::raw(...))。這個方法的第二個參數接受一個可選的綁定參數的數組：

$orders = DB::table('orders')
                ->selectRaw('price * ? as price_with_tax', [1.0825])
                ->get();

whereRaw / orWhereRaw

可以使用 whereRaw 和 orWhereRaw 方法將原生的 where 語句注入到查詢中。這些方法接受一個可選的綁定數組作爲他們的第二個參數：

$orders = DB::table('orders')
                ->whereRaw('price > IF(state = "TX", ?, 100)', [200])
                ->get();

havingRaw / orHavingRaw

havingRaw 和 orHavingRaw 方法可用於將原生字符串設置爲 having 語句的值：

$orders = DB::table('orders')
                ->select('department', DB::raw('SUM(price) as total_sales'))
                ->groupBy('department')
                ->havingRaw('SUM(price) > 2500')
                ->get();

orderByRaw

orderByRaw 方法可用於將原生字符串設置爲 order by 語句的值：

$orders = DB::table('orders')
                ->orderByRaw('updated_at - created_at DESC')
                ->get();

Joins

Inner Join 語句

查詢構造器也可以編寫 join 語句。若要執行基本的「內連接」，你可以在查詢構造器實例上使用 join 方法。傳遞給 join 方法的第一個參數是你要需要連接的表的名稱，而其它參數則用來指定連接的字段約束。你還可以在單個查詢中連接多個數據表：

$users = DB::table('users')
            ->join('contacts', 'users.id', '=', 'contacts.user_id')
            ->join('orders', 'users.id', '=', 'orders.user_id')
            ->select('users.*', 'contacts.phone', 'orders.price')
            ->get();

Left Join 語句

如果你想用「左連接」來代替「內連接」，請使用 leftJoin 方法。leftJoin 方法的用法和 join 方法一樣：

$users = DB::table('users')
            ->leftJoin('posts', 'users.id', '=', 'posts.user_id')
            ->get();

Cross Join 語句

使用 crossJoin 方法和你想要交叉連接的表名來做「交叉連接」。交叉連接在第一個表和連接之間生成笛卡爾積：

$users = DB::table('sizes')
            ->crossJoin('colours')
            ->get();

高級 Join 語句

你也可以指定更高級的 join 語句。比如傳遞一個閉包作爲 join 方法的第二個參數。此閉包接收一個 JoinClause 對象，從而在其中指定 join 語句中指定約束：

DB::table('users')
        ->join('contacts', function ($join) {
            $join->on('users.id', '=', 'contacts.user_id')->orOn(...);
        })
        ->get();

如果你想要在連接上使用「where」風格的語句，可以在連接上使用 where 和 orWhere 方法。這些方法可以用來比較值和對應的字段：

DB::table('users')
        ->join('contacts', function ($join) {
            $join->on('users.id', '=', 'contacts.user_id')
                 ->where('contacts.user_id', '>', 5);
        })
        ->get();

Unions

查詢構造器還提供了將兩個查詢「合併」起來的快捷方式。例如，你可以先創建一個初始查詢，並使用 union 方法將它與第二個查詢進行合併：

$first = DB::table('users')
            ->whereNull('first_name');
$users = DB::table('users')
            ->whereNull('last_name')
            ->union($first)
            ->get();

{tip} 也可使用 unionAll 方法，它和 union 方法有着相同的用法。

Where 語句

簡單的 Where 語句

你可以在查詢構造器實例中使用 where 方法從而把 where 語句添加到查詢中。基本的 where 方法需要三個參數。第一個參數是字段的名稱，第二個參數是運算符，它可以是數據庫所支持的任何運算符。最後，第三個參數是要對字段進行評估的值。

例如，下面是一個要驗證「votes」字段的值等於 100 的查詢：

$users = DB::table('users')->where('votes', '=', 100)->get();

如果你只是想簡單的校驗某個字段等於指定的值，你可以直接將這個值作爲第二個參數傳遞給 where 方法：

$users = DB::table('users')->where('votes', 100)->get();

當然，在編寫 where 語句時，也可以使用其它各種數據庫支持的運算符：

$users = DB::table('users')
                ->where('votes', '>=', 100)
                ->get();
$users = DB::table('users')
                ->where('votes', '<>', 100)
                ->get();
$users = DB::table('users')
                ->where('name', 'like', 'T%')
                ->get();

你也可以傳遞條件數組給 where 函數：

$users = DB::table('users')->where([
    ['status', '=', '1'],
    ['subscribed', '<>', '1'],
])->get();

Or 語句

你可以一起鏈式調用 where，也可以在查詢添加中 or 語句。orWhere 方法接受與 where 方法相同的參數：

$users = DB::table('users')
                    ->where('votes', '>', 100)
                    ->orWhere('name', 'John')
                    ->get();

其它 Where 語句

whereBetween

whereBetween 方法用來驗證字段的值介於兩個值之間：

$users = DB::table('users')
                    ->whereBetween('votes', [1, 100])->get();

whereNotBetween

whereNotBetween 方法驗證字段的值不在兩個值之間：

$users = DB::table('users')
                    ->whereNotBetween('votes', [1, 100])
                    ->get();

whereIn / whereNotIn

whereIn 方法驗證字段的值在指定的數組內：

$users = DB::table('users')
                    ->whereIn('id', [1, 2, 3])
                    ->get();

whereNotIn 方法驗證字段的值不在指定的數組內：

$users = DB::table('users')
                    ->whereNotIn('id', [1, 2, 3])
                    ->get();

whereNull / whereNotNull

whereNull 方法驗證字段的值爲 NULL：

$users = DB::table('users')
                    ->whereNull('updated_at')
                    ->get();

whereNotNull 方法驗證字段的值不爲 NULL：

$users = DB::table('users')
                    ->whereNotNull('updated_at')
                    ->get();

whereDate / whereMonth / whereDay / whereYear / whereTime

whereDate 方法用於比較字段的值和日期：

$users = DB::table('users')
                ->whereDate('created_at', '2016-12-31')
                ->get();

whereMonth 方法用於比較字段的值與一年的特定月份：

$users = DB::table('users')
                ->whereMonth('created_at', '12')
                ->get();

whereDay 方法用於比較字段的值與特定的一個月的某一天：

$users = DB::table('users')
                ->whereDay('created_at', '31')
                ->get();

whereYear 方法用於比較字段的值與特定年份：

$users = DB::table('users')
                ->whereYear('created_at', '2016')
                ->get();

whereTime 方法用於比較字段的值與特定的時間：

$users = DB::table('users')
                ->whereTime('created_at', '=', '11:20')
                ->get();

whereColumn

whereColumn 方法用於驗證兩個字段是否相等：

$users = DB::table('users')
                ->whereColumn('first_name', 'last_name')
                ->get();

還可以將比較運算符傳遞給該方法：

$users = DB::table('users')
                ->whereColumn('updated_at', '>', 'created_at')
                ->get();

whereColumn 方法也可以傳遞一個包含多個條件的數組。這些條件將使用 and 運算符進行連接：

$users = DB::table('users')
                ->whereColumn([
                    ['first_name', '=', 'last_name'],
                    ['updated_at', '>', 'created_at']
                ])->get();

參數分組
有時你可能需要創建更高級的 where 語句，例如「where exists」或者嵌套的參數分組。Laravel 的查詢構造器也能夠處理這些。下面有一個括號內的分組約束的示例：

DB::table('users')
            ->where('name', '=', 'John')
            ->orWhere(function ($query) {
                $query->where('votes', '>', 100)
                      ->where('title', '<>', 'Admin');
            })
            ->get();

在上面例子中將閉包傳遞到 orWhere 方法中，指示查詢構造器開始一個約束分組。此閉包接收一個查詢構造器實例，你可以用它來設置應包含在括號組中的約束。上面的例子會產生下面的 SQL：

select * from users where name = 'John' or (votes > 100 and title <> 'Admin')

Where Exists 語句

whereExists 方法允許你編寫 where exists SQL 語句。此方法接受一個閉包參數，此閉包要接收一個查詢構造器實例，讓你可以定義放在「exists」語句中的查詢：

DB::table('users')
            ->whereExists(function ($query) {
                $query->select(DB::raw(1))
                      ->from('orders')
                      ->whereRaw('orders.user_id = users.id');
            })
            ->get();

上述的查詢將生成以下 SQL：

select * from users
where exists (
    select 1 from orders where orders.user_id = users.id
)

JSON where 語句

Laravel 也支持查詢 JSON 類型的字段（僅在對 JSON 類型支持的數據庫上）。目前，本特性僅支持 MySQL 5.7+ 和 Postgres數據庫。可以使用 -> 運算符來查詢 JSON 列數據：

$users = DB::table('users')
                ->where('options->language', 'en')
                ->get();
$users = DB::table('users')
                ->where('preferences->dining->meal', 'salad')
                ->get();

Ordering, Grouping, Limit, & Offset

orderBy

orderBy 方法允許你根據指定字段對查詢結果進行排序。orderBy 方法的第一個參數是你想要用來排序的字段，而第二個參數控制排序的方向，可以是 asc 或 desc：

$users = DB::table('users')
                ->orderBy('name', 'desc')
                ->get();

latest / oldest

latest 和 oldest 方法允許你輕鬆地按日期對查詢結果排序。默認情況下是對 created_at 字段進行排序。或者，你可以傳遞你想要排序的字段名稱：

$user = DB::table('users')
                ->latest()
                ->first();

inRandomOrder

inRandomOrder 方法可以將查詢結果隨機排序。例如，你可以使用這個方法獲取一個隨機用戶：

$randomUser = DB::table('users')
                ->inRandomOrder()
                ->first();

groupBy / having

groupBy 和 having 方法可用來對查詢結果進行分組。having 方法的用法和 where 方法類似：

$users = DB::table('users')
                ->groupBy('account_id')
                ->having('account_id', '>', 100)
                ->get();

可以將多個參數傳遞給 groupBy 方法，按多個字段進行分組：

$users = DB::table('users')
                ->groupBy('first_name', 'status')
                ->having('account_id', '>', 100)
                ->get();

對於更高級的語句，請參閱 havingRaw 方法。

skip / take

可以使用 skip 和 take 方法來限制從查詢返回的結果數量或跳過查詢中給定數量的結果：

$users = DB::table('users')->skip(10)->take(5)->get();

或者，你也可以使用 limit 和 offset 方法：

$users = DB::table('users')
                ->offset(10)
                ->limit(5)
                ->get();

條件語句

有時你可能想要子句只適用於某個情況爲真時才執行查詢。例如，如果給定的輸入值出現在傳入請求中時，你可能想要判斷它能達成某個 where 語句，你可以使用 when 方法來完成此操作：

$role = $request->input('role');
$users = DB::table('users')
                ->when($role, function ($query) use ($role) {
                    return $query->where('role_id', $role);
                })
                ->get();

只有當 when 方法的第一個參數爲 true 時，閉包裏的 where 語句纔會執行。如果第一個參數是 false，這個閉包將不會被執行。

你可以將另一個閉包當作第三個參數傳遞給 when 方法。如果第一個參數的值爲 false 時，這個閉包將執行。爲了說明如何使用此功能，我們將使用它配置查詢的默認排序：

$sortBy = null;
$users = DB::table('users')
                ->when($sortBy, function ($query) use ($sortBy) {
                    return $query->orderBy($sortBy);
                }, function ($query) {
                    return $query->orderBy('name');
                })
                ->get();

Inserts

查詢構造器也提供了將記錄插入數據庫表的 insert 方法。insert 方法接受一個字段名和值的數組作爲參數：

DB::table('users')->insert(
    ['email' => '[email protected]', 'votes' => 0]
);

你還可以在 insert 中傳入一個嵌套數組向表中插入多條記錄。每個數組代表要插入表中的行：

DB::table('users')->insert([
    ['email' => '[email protected]', 'votes' => 0],
    ['email' => '[email protected]', 'votes' => 0]
]);

自增 ID

若數據表存在自增的 ID，則可以使用 insertGetId 方法來插入記錄然後獲取其 ID：

$id = DB::table('users')->insertGetId(
    ['email' => '[email protected]', 'votes' => 0]
);

{note} 當使用 PostgreSQL 時，insertGetId 方法將默認把 id 作爲自動遞增字段的名稱。若你要從不同「順序」來獲取 ID，則可以將字段名稱作爲第二個參數傳遞給 insertGetId 方法。

Updates

當然，除了在數據庫中插入記錄外，你也可以使用 update 來更新已存在的記錄。update 方法和 insert 方法一樣，接受包含要更新的字段及值的數組。你可以使用 where 語句來約束 update 的查詢：

DB::table('users')
            ->where('id', 1)
            ->update(['votes' => 1]);

更新 JSON 字段

更新 JSON 字段時，應該使用 -> 語法來訪問 JSON 對象中的相應鍵。此操作只能在支持 JSON 字段的數據庫上操作：

DB::table('users')
            ->where('id', 1)
            ->update(['options->enabled' => true]);

自增 & 自減

查詢構造器還爲給定字段的遞增或遞減提供了方便的方法。此方法提供了一個比手動編寫 update 語句更具表達力且更精練的接口。

這兩個方法都必須接收至少一個參數——要修改的字段。可以選擇傳遞第二個參數來控制字段遞增或遞減的量：

DB::table('users')->increment('votes');
DB::table('users')->increment('votes', 5);
DB::table('users')->decrement('votes');
DB::table('users')->decrement('votes', 5);

你也可以在操作過程中指定要更新的字段：

DB::table('users')->increment('votes', 1, ['name' => 'John']);

Deletes

查詢構造器也可使用 delete 方法從數據表中刪除記錄。在調用 delete 方法前，還可以通過添加 where 語句來約束 delete 語句：

DB::table('users')->delete();
DB::table('users')->where('votes', '>', 100)->delete();

如果你需要清空表，你可以使用 truncate 方法，這將刪除所有行，並重置自動遞增 ID 爲零：

DB::table('users')->truncate();

悲觀鎖

查詢構造器也包含一些可以幫助你在 select 語句上實現「悲觀鎖定」的函數。若要在查詢中使用「共享鎖」，可以使用 sharedLock 方法。共享鎖可以防止選中的行被篡改，直到事務被提交爲止：

DB::table('users')->where('votes', '>', 100)->sharedLock()->get();

或者，你也可以使用 lockForUpdate 方法。使用「更新」鎖可避免行被其它共享鎖修改或選取：

DB::table('users')->where('votes', '>', 100)->lockForUpdate()->get();

php Laravel 數據庫之：數據庫請求構建器