データベース：クエリビルダ

イントロダクション
データベースクエリの実行
Select文
Raw式
Join
Union
基本的なWhere句
高度なWhere句
順序、グループ化、Limit、Offset
条件節
Insert文
- Upsert
Update文
- JSONカラムの更新
- インクリメントとデクリメント
Delete文
悲観的ロック
デバッグ

イントロダクション

Laravelのデータベースクエリビルダは、データベースクエリを作成および実行するための便利で流暢なインターフェイスを提供します。アプリケーションのほとんどのデータベース操作を実行するために使用でき、Laravelがサポートするすべてのデータベースシステムで完全に機能します。

LaravelのクエリビルダはPDOのパラメータ結合を使用して、アプリケーションをSQLインジェクション攻撃から保護します。クエリビルダに渡す文字列をクエリのバインディングとしてクリーンにしたり、サニタイズしたりする必要はありません。

PDOはカラム名のバインディングをサポートしていません。したがって、「order by」カラムを含め、クエリで参照されるカラム名をユーザー入力に決定させるべきではありません。

データベースクエリの実行

テーブルからすべての行を取得

クエリを開始するには、DBファサードが提供するtableメソッドを使用します。tableメソッドは、指定されたテーブルの流暢なクエリビルダインスタンスを返し、クエリにさらに制約をチェーンし、最後にgetメソッドを使用してクエリの結果を取得できます。

 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use Illuminate\Support\Facades\DB;
 6use Illuminate\View\View;
 7 
 8class UserController extends Controller
 9{
10    /**
11     * Show a list of all of the application's users.
12     */
13    public function index(): View
14    {
15        $users = DB::table('users')->get();
16 
17        return view('user.index', ['users' => $users]);
18    }
19}

<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\DB;
use Illuminate\View\View;

class UserController extends Controller
{
    /**
     * Show a list of all of the application's users.
     */
    public function index(): View
    {
        $users = DB::table('users')->get();

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

getメソッドは、クエリの結果を含むIlluminate\Support\Collectionインスタンスを返します。各結果はPHPのstdClassオブジェクトのインスタンスです。各カラムの値には、オブジェクトのプロパティとしてカラムにアクセスすることでアクセスできます。

1use Illuminate\Support\Facades\DB;
2 
3$users = DB::table('users')->get();
4 
5foreach ($users as $user) {
6    echo $user->name;
7}

use Illuminate\Support\Facades\DB;

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

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

Laravelコレクションは、データをマッピングしたりリデュースしたりするための非常に強力なメソッドをさまざまに提供しています。Laravelコレクションの詳細は、コレクションのドキュメントを確認してください。

テーブルから単一の行／カラムを取得

データベーステーブルから単一の行を取得するだけでよい場合は、DBファサードのfirstメソッドを使用します。このメソッドは単一のstdClassオブジェクトを返します。

1$user = DB::table('users')->where('name', 'John')->first();
2 
3return $user->email;

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

return $user->email;

データベーステーブルから単一の行を取得したいが、一致する行が見つからない場合にIlluminate\Database\RecordNotFoundExceptionを投げたい場合は、firstOrFailメソッドを使用します。RecordNotFoundExceptionがキャッチされない場合、404 HTTPレスポンスが自動的にクライアントに送り返されます。

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

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

行全体が必要ない場合は、valueメソッドを使用してレコードから単一の値を抽出できます。このメソッドは、カラムの値を直接返します。

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

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

idカラムの値で単一の行を取得するには、findメソッドを使用します。

1$user = DB::table('users')->find(3);

$user = DB::table('users')->find(3);

カラム値のリストを取得

単一のカラムの値を含むIlluminate\Support\Collectionインスタンスを取得したい場合は、pluckメソッドを使用します。この例では、ユーザーの肩書きのコレクションを取得します。

1use Illuminate\Support\Facades\DB;
2 
3$titles = DB::table('users')->pluck('title');
4 
5foreach ($titles as $title) {
6    echo $title;
7}

use Illuminate\Support\Facades\DB;

$titles = DB::table('users')->pluck('title');

foreach ($titles as $title) {
    echo $title;
}

pluckメソッドに2番目の引数を指定することで、結果のコレクションがキーとして使用するカラムを指定できます。

1$titles = DB::table('users')->pluck('title', 'name');
2 
3foreach ($titles as $name => $title) {
4    echo $title;
5}

$titles = DB::table('users')->pluck('title', 'name');

foreach ($titles as $name => $title) {
    echo $title;
}

結果のチャンク化

何千ものデータベースレコードを扱う必要がある場合は、DBファサードが提供するchunkメソッドの使用を検討してください。このメソッドは、一度に少量の結果のチャンクを取得し、各チャンクを処理用のクロージャに渡します。たとえば、usersテーブル全体を一度に100レコードずつのチャンクで取得してみましょう。

1use Illuminate\Support\Collection;
2use Illuminate\Support\Facades\DB;
3 
4DB::table('users')->orderBy('id')->chunk(100, function (Collection $users) {
5    foreach ($users as $user) {
6        // ...
7    }
8});

use Illuminate\Support\Collection;
use Illuminate\Support\Facades\DB;

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

クロージャからfalseを返すことで、それ以降のチャンクの処理を停止できます。

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

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

    return false;
});

結果をチャンク化しながらデータベースレコードを更新している場合、チャンクの結果が予期しない方法で変わる可能性があります。チャンク化しながら取得したレコードを更新する予定がある場合は、代わりにchunkByIdメソッドを使用するのが常に最善です。このメソッドは、レコードの主キーに基づいて結果を自動的にページ分割します。

1DB::table('users')->where('active', false)
2    ->chunkById(100, function (Collection $users) {
3        foreach ($users as $user) {
4            DB::table('users')
5                ->where('id', $user->id)
6                ->update(['active' => true]);
7        }
8    });

DB::table('users')->where('active', false)
    ->chunkById(100, function (Collection $users) {
        foreach ($users as $user) {
            DB::table('users')
                ->where('id', $user->id)
                ->update(['active' => true]);
        }
    });

chunkByIdおよびlazyByIdメソッドは、実行されるクエリに独自の「where」条件を追加するため、通常は独自の条件をクロージャ内で論理的にグループ化する必要があります。

1DB::table('users')->where(function ($query) {
2    $query->where('credits', 1)->orWhere('credits', 2);
3})->chunkById(100, function (Collection $users) {
4    foreach ($users as $user) {
5        DB::table('users')
6            ->where('id', $user->id)
7            ->update(['credits' => 3]);
8    }
9});

DB::table('users')->where(function ($query) {
    $query->where('credits', 1)->orWhere('credits', 2);
})->chunkById(100, function (Collection $users) {
    foreach ($users as $user) {
        DB::table('users')
            ->where('id', $user->id)
            ->update(['credits' => 3]);
    }
});

チャンクのコールバック内でレコードを更新または削除する場合、主キーまたは外部キーへの変更がチャンククエリに影響を与える可能性があります。これにより、レコードがチャンク化された結果に含まれなくなる可能性があります。

結果の遅延ストリーミング

lazyメソッドは、クエリをチャンクで実行するという点でchunkメソッドと同様に機能します。ただし、各チャンクをコールバックに渡す代わりに、lazy()メソッドはLazyCollectionを返し、これにより結果を単一のストリームとして操作できます。

1use Illuminate\Support\Facades\DB;
2 
3DB::table('users')->orderBy('id')->lazy()->each(function (object $user) {
4    // ...
5});

use Illuminate\Support\Facades\DB;

DB::table('users')->orderBy('id')->lazy()->each(function (object $user) {
    // ...
});

繰り返しになりますが、取得したレコードを反復処理しながら更新する予定がある場合は、代わりにlazyByIdまたはlazyByIdDescメソッドを使用するのが最善です。これらのメソッドは、レコードの主キーに基づいて結果を自動的にページ分割します。

1DB::table('users')->where('active', false)
2    ->lazyById()->each(function (object $user) {
3        DB::table('users')
4            ->where('id', $user->id)
5            ->update(['active' => true]);
6    });

DB::table('users')->where('active', false)
    ->lazyById()->each(function (object $user) {
        DB::table('users')
            ->where('id', $user->id)
            ->update(['active' => true]);
    });

レコードを反復処理しながら更新または削除する場合、主キーまたは外部キーへの変更がチャンククエリに影響を与える可能性があります。これにより、レコードが結果に含まれなくなる可能性があります。

集計

クエリビルダは、count、max、min、avg、sumなどの集計値を取得するためのさまざまなメソッドも提供しています。クエリを構築した後に、これらのメソッドのいずれかを呼び出すことができます。

1use Illuminate\Support\Facades\DB;
2 
3$users = DB::table('users')->count();
4 
5$price = DB::table('orders')->max('price');

use Illuminate\Support\Facades\DB;

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

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

もちろん、これらのメソッドを他の句と組み合わせて、集計値の計算方法を微調整することもできます。

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

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

レコードが存在するかどうかの判断

クエリの制約に一致するレコードが存在するかどうかを判断するためにcountメソッドを使用する代わりに、existsメソッドとdoesntExistメソッドを使用できます。

1if (DB::table('orders')->where('finalized', 1)->exists()) {
2    // ...
3}
4 
5if (DB::table('orders')->where('finalized', 1)->doesntExist()) {
6    // ...
7}

if (DB::table('orders')->where('finalized', 1)->exists()) {
    // ...
}

if (DB::table('orders')->where('finalized', 1)->doesntExist()) {
    // ...
}

Select文

Select句の指定

常にデータベーステーブルからすべてのカラムを選択したいとは限りません。selectメソッドを使用して、クエリにカスタムの「select」句を指定できます。

1use Illuminate\Support\Facades\DB;
2 
3$users = DB::table('users')
4    ->select('name', 'email as user_email')
5    ->get();

use Illuminate\Support\Facades\DB;

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

distinctメソッドを使用すると、クエリに重複しない結果を強制的に返させることができます。

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

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

すでにクエリビルダインスタンスがあり、その既存のselect句にカラムを追加したい場合は、addSelectメソッドを使用できます。

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

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

$users = $query->addSelect('age')->get();

Raw式

クエリに任意の文字列を挿入する必要がある場合があります。生の文字列表現を作成するには、DBファサードが提供するrawメソッドを使用します。

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

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

raw文は文字列としてクエリに注入されるため、SQLインジェクションの脆弱性を作成しないように細心の注意を払う必要があります。

Rawメソッド

DB::rawメソッドを使用する代わりに、以下のメソッドを使用してクエリのさまざまな部分にraw式を挿入することもできます。Laravelは、raw式を使用するクエリがSQLインジェクションの脆弱性から保護されていることを保証できないことを忘れないでください。

`selectRaw`

selectRawメソッドはaddSelect(DB::raw(/* ... */))の代わりに使用できます。このメソッドは、2番目の引数としてオプションのバインディングの配列を受け入れます。

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

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

`whereRaw / orWhereRaw`

whereRawメソッドとorWhereRawメソッドは、クエリにrawの「where」句を注入するために使用できます。これらのメソッドは、2番目の引数としてオプションのバインディングの配列を受け入れます。

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

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

`havingRaw / orHavingRaw`

havingRawメソッドとorHavingRawメソッドは、「having」句の値としてraw文字列を提供するために使用できます。これらのメソッドは、2番目の引数としてオプションのバインディングの配列を受け入れます。

1$orders = DB::table('orders')
2    ->select('department', DB::raw('SUM(price) as total_sales'))
3    ->groupBy('department')
4    ->havingRaw('SUM(price) > ?', [2500])
5    ->get();

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

`orderByRaw`

orderByRawメソッドは、「order by」句の値としてraw文字列を提供するために使用できます。

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

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

`groupByRaw`

groupByRawメソッドは、group by句の値としてraw文字列を提供するために使用できます。

1$orders = DB::table('orders')
2    ->select('city', 'state')
3    ->groupByRaw('city, state')
4    ->get();

$orders = DB::table('orders')
    ->select('city', 'state')
    ->groupByRaw('city, state')
    ->get();

Join

Inner Join句

クエリビルダは、クエリにjoin句を追加するためにも使用できます。基本的な「inner join」を実行するには、クエリビルダインスタンスでjoinメソッドを使用します。joinメソッドに渡される最初の引数は、結合する必要のあるテーブルの名前であり、残りの引数は結合のカラム制約を指定します。単一のクエリで複数のテーブルを結合することもできます。

1use Illuminate\Support\Facades\DB;
2 
3$users = DB::table('users')
4    ->join('contacts', 'users.id', '=', 'contacts.user_id')
5    ->join('orders', 'users.id', '=', 'orders.user_id')
6    ->select('users.*', 'contacts.phone', 'orders.price')
7    ->get();

use Illuminate\Support\Facades\DB;

$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 / Right Join句

「inner join」の代わりに「left join」または「right join」を実行したい場合は、leftJoinメソッドまたはrightJoinメソッドを使用します。これらのメソッドは、joinメソッドと同じシグネチャを持っています。

1$users = DB::table('users')
2    ->leftJoin('posts', 'users.id', '=', 'posts.user_id')
3    ->get();
4 
5$users = DB::table('users')
6    ->rightJoin('posts', 'users.id', '=', 'posts.user_id')
7    ->get();

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

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

Cross Join句

crossJoinメソッドを使用して「cross join」を実行できます。クロスジョインは、最初のテーブルと結合されたテーブルの間のデカルト積を生成します。

1$sizes = DB::table('sizes')
2    ->crossJoin('colors')
3    ->get();

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

高度なJoin句

より高度なjoin句を指定することもできます。開始するには、joinメソッドの2番目の引数としてクロージャを渡します。クロージャはIlluminate\Database\Query\JoinClauseインスタンスを受け取り、これにより「join」句の制約を指定できます。

1DB::table('users')
2    ->join('contacts', function (JoinClause $join) {
3        $join->on('users.id', '=', 'contacts.user_id')->orOn(/* ... */);
4    })
5    ->get();

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

結合で「where」句を使用したい場合は、JoinClauseインスタンスが提供するwhereメソッドとorWhereメソッドを使用できます。2つのカラムを比較する代わりに、これらのメソッドはカラムを値と比較します。

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

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

joinSub、leftJoinSub、およびrightJoinSubメソッドを使用して、クエリをサブクエリに結合できます。これらの各メソッドは3つの引数を受け取ります：サブクエリ、そのテーブルエイリアス、および関連するカラムを定義するクロージャです。この例では、各ユーザーレコードにユーザーの最新の公開ブログ投稿のcreated_atタイムスタンプも含まれるユーザーのコレクションを取得します。

1$latestPosts = DB::table('posts')
2    ->select('user_id', DB::raw('MAX(created_at) as last_post_created_at'))
3    ->where('is_published', true)
4    ->groupBy('user_id');
5 
6$users = DB::table('users')
7    ->joinSub($latestPosts, 'latest_posts', function (JoinClause $join) {
8        $join->on('users.id', '=', 'latest_posts.user_id');
9    })->get();

$latestPosts = DB::table('posts')
    ->select('user_id', DB::raw('MAX(created_at) as last_post_created_at'))
    ->where('is_published', true)
    ->groupBy('user_id');

$users = DB::table('users')
    ->joinSub($latestPosts, 'latest_posts', function (JoinClause $join) {
        $join->on('users.id', '=', 'latest_posts.user_id');
    })->get();

ラテラルJoin

ラテラルジョインは現在、PostgreSQL、MySQL >= 8.0.14、およびSQL Serverでサポートされています。

joinLateralメソッドとleftJoinLateralメソッドを使用して、サブクエリとの「ラテラルジョイン」を実行できます。これらの各メソッドは2つの引数を受け取ります：サブクエリとそのテーブルエイリアスです。結合条件は、指定されたサブクエリのwhere句内で指定する必要があります。ラテラルジョインは各行に対して評価され、サブクエリ外のカラムを参照できます。

この例では、ユーザーのコレクションと、そのユーザーの最新の3つのブログ投稿を取得します。各ユーザーは結果セットに最大3行を生成できます：最新のブログ投稿ごとに1行です。結合条件は、サブクエリ内のwhereColumn句で指定され、現在のユーザー行を参照します。

1$latestPosts = DB::table('posts')
2    ->select('id as post_id', 'title as post_title', 'created_at as post_created_at')
3    ->whereColumn('user_id', 'users.id')
4    ->orderBy('created_at', 'desc')
5    ->limit(3);
6 
7$users = DB::table('users')
8    ->joinLateral($latestPosts, 'latest_posts')
9    ->get();

$latestPosts = DB::table('posts')
    ->select('id as post_id', 'title as post_title', 'created_at as post_created_at')
    ->whereColumn('user_id', 'users.id')
    ->orderBy('created_at', 'desc')
    ->limit(3);

$users = DB::table('users')
    ->joinLateral($latestPosts, 'latest_posts')
    ->get();

Union

クエリビルダは、2つ以上のクエリを「union」するための便利なメソッドも提供しています。たとえば、最初のクエリを作成し、unionメソッドを使用してそれをより多くのクエリと結合できます。

1use Illuminate\Support\Facades\DB;
2 
3$first = DB::table('users')
4    ->whereNull('first_name');
5 
6$users = DB::table('users')
7    ->whereNull('last_name')
8    ->union($first)
9    ->get();

use Illuminate\Support\Facades\DB;

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

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

unionメソッドに加えて、クエリビルダはunionAllメソッドを提供します。unionAllメソッドを使用して結合されたクエリでは、重複した結果は削除されません。unionAllメソッドは、unionメソッドと同じメソッドシグネチャを持っています。

基本的なWhere句

Where句

クエリビルダのwhereメソッドを使用して、クエリに「where」句を追加できます。whereメソッドへの最も基本的な呼び出しには3つの引数が必要です。最初の引数はカラムの名前です。2番目の引数は演算子で、データベースがサポートする任意の演算子を指定できます。3番目の引数は、カラムの値と比較する値です。

たとえば、次のクエリは、votesカラムの値が100に等しく、ageカラムの値が35より大きいユーザーを取得します。

1$users = DB::table('users')
2    ->where('votes', '=', 100)
3    ->where('age', '>', 35)
4    ->get();

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

便宜上、カラムが特定の値と=であることを確認したい場合は、その値をwhereメソッドの2番目の引数として渡すことができます。Laravelは、=演算子を使用したいと想定します。

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

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

前述のとおり、データベースシステムでサポートされている任意の演算子を使用できます。

 1$users = DB::table('users')
 2    ->where('votes', '>=', 100)
 3    ->get();
 4 
 5$users = DB::table('users')
 6    ->where('votes', '<>', 100)
 7    ->get();
 8 
 9$users = DB::table('users')
10    ->where('name', 'like', 'T%')
11    ->get();

$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関数に条件の配列を渡すこともできます。配列の各要素は、通常whereメソッドに渡される3つの引数を含む配列である必要があります。

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

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

MySQLとMariaDBは、文字列と数値の比較で文字列を整数に自動的に型キャストします。このプロセスでは、非数値文字列は0に変換され、予期しない結果につながる可能性があります。たとえば、テーブルに値がaaaのsecretカラムがあり、User::where('secret', 0)を実行すると、その行が返されます。これを避けるために、クエリで使用する前にすべての値が適切な型にキャストされていることを確認してください。

Or Where句

クエリビルダのwhereメソッドへの呼び出しをチェーンする場合、「where」句はand演算子を使用して結合されます。ただし、orWhereメソッドを使用してor演算子で句をクエリに結合できます。orWhereメソッドは、whereメソッドと同じ引数を受け入れます。

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

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

「or」条件を括弧でグループ化する必要がある場合は、orWhereメソッドの最初の引数としてクロージャを渡すことができます。

1$users = DB::table('users')
2    ->where('votes', '>', 100)
3    ->orWhere(function (Builder $query) {
4        $query->where('name', 'Abigail')
5            ->where('votes', '>', 50);
6        })
7    ->get();

$users = DB::table('users')
    ->where('votes', '>', 100)
    ->orWhere(function (Builder $query) {
        $query->where('name', 'Abigail')
            ->where('votes', '>', 50);
        })
    ->get();

上記の例は、次のSQLを生成します。

1select * from users where votes > 100 or (name = 'Abigail' and votes > 50)

select * from users where votes > 100 or (name = 'Abigail' and votes > 50)

グローバルスコープが適用されたときの予期しない動作を避けるために、常にorWhere呼び出しをグループ化する必要があります。

Where Not句

whereNotメソッドとorWhereNotメソッドは、指定されたクエリ制約のグループを否定するために使用できます。たとえば、次のクエリは、クリアランス中であるか、価格が10未満の製品を除外します。

1$products = DB::table('products')
2    ->whereNot(function (Builder $query) {
3        $query->where('clearance', true)
4            ->orWhere('price', '<', 10);
5        })
6    ->get();

$products = DB::table('products')
    ->whereNot(function (Builder $query) {
        $query->where('clearance', true)
            ->orWhere('price', '<', 10);
        })
    ->get();

Where Any／All／None句

複数のカラムに同じクエリ制約を適用する必要がある場合があります。たとえば、指定されたリスト内のいずれかのカラムが特定の値とLIKEであるすべてのレコードを取得したい場合があります。これはwhereAnyメソッドを使用して実現できます。

1$users = DB::table('users')
2    ->where('active', true)
3    ->whereAny([
4        'name',
5        'email',
6        'phone',
7    ], 'like', 'Example%')
8    ->get();

$users = DB::table('users')
    ->where('active', true)
    ->whereAny([
        'name',
        'email',
        'phone',
    ], 'like', 'Example%')
    ->get();

上記のクエリは、次のSQLになります。

1SELECT *
2FROM users
3WHERE active = true AND (
4    name LIKE 'Example%' OR
5    email LIKE 'Example%' OR
6    phone LIKE 'Example%'
7)

SELECT *
FROM users
WHERE active = true AND (
    name LIKE 'Example%' OR
    email LIKE 'Example%' OR
    phone LIKE 'Example%'
)

同様に、whereAllメソッドを使用して、指定されたすべてのカラムが特定の制約に一致するレコードを取得できます。

1$posts = DB::table('posts')
2    ->where('published', true)
3    ->whereAll([
4        'title',
5        'content',
6    ], 'like', '%Laravel%')
7    ->get();

$posts = DB::table('posts')
    ->where('published', true)
    ->whereAll([
        'title',
        'content',
    ], 'like', '%Laravel%')
    ->get();

上記のクエリは、次のSQLになります。

1SELECT *
2FROM posts
3WHERE published = true AND (
4    title LIKE '%Laravel%' AND
5    content LIKE '%Laravel%'
6)

SELECT *
FROM posts
WHERE published = true AND (
    title LIKE '%Laravel%' AND
    content LIKE '%Laravel%'
)

whereNoneメソッドを使用して、指定されたどのカラムも特定の制約に一致しないレコードを取得できます。

1$posts = DB::table('albums')
2    ->where('published', true)
3    ->whereNone([
4        'title',
5        'lyrics',
6        'tags',
7    ], 'like', '%explicit%')
8    ->get();

$posts = DB::table('albums')
    ->where('published', true)
    ->whereNone([
        'title',
        'lyrics',
        'tags',
    ], 'like', '%explicit%')
    ->get();

上記のクエリは、次のSQLになります。

1SELECT *
2FROM albums
3WHERE published = true AND NOT (
4    title LIKE '%explicit%' OR
5    lyrics LIKE '%explicit%' OR
6    tags LIKE '%explicit%'
7)

SELECT *
FROM albums
WHERE published = true AND NOT (
    title LIKE '%explicit%' OR
    lyrics LIKE '%explicit%' OR
    tags LIKE '%explicit%'
)

JSON Where句

Laravelは、JSONカラムタイプをサポートするデータベースでJSONカラムタイプのクエリもサポートしています。現在、これにはMariaDB 10.3+、MySQL 8.0+、PostgreSQL 12.0+、SQL Server 2017+、およびSQLite 3.39.0+が含まれます。JSONカラムをクエリするには、->演算子を使用します。

1$users = DB::table('users')
2    ->where('preferences->dining->meal', 'salad')
3    ->get();

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

whereJsonContainsを使用してJSON配列をクエリできます。

1$users = DB::table('users')
2    ->whereJsonContains('options->languages', 'en')
3    ->get();

$users = DB::table('users')
    ->whereJsonContains('options->languages', 'en')
    ->get();

アプリケーションがMariaDB、MySQL、またはPostgreSQLデータベースを使用している場合、whereJsonContainsメソッドに値の配列を渡すことができます。

1$users = DB::table('users')
2    ->whereJsonContains('options->languages', ['en', 'de'])
3    ->get();

$users = DB::table('users')
    ->whereJsonContains('options->languages', ['en', 'de'])
    ->get();

whereJsonLengthメソッドを使用して、JSON配列をその長さでクエリできます。

1$users = DB::table('users')
2    ->whereJsonLength('options->languages', 0)
3    ->get();
4 
5$users = DB::table('users')
6    ->whereJsonLength('options->languages', '>', 1)
7    ->get();

$users = DB::table('users')
    ->whereJsonLength('options->languages', 0)
    ->get();

$users = DB::table('users')
    ->whereJsonLength('options->languages', '>', 1)
    ->get();

追加のWhere句

whereLike / orWhereLike / whereNotLike / orWhereNotLike

whereLikeメソッドを使用すると、パターンマッチングのためにクエリに「LIKE」句を追加できます。これらのメソッドは、大文字と小文字の区別を切り替える機能を備えた、データベースに依存しない方法で文字列マッチングクエリを実行する方法を提供します。デフォルトでは、文字列マッチングは大文字と小文字を区別しません。

1$users = DB::table('users')
2    ->whereLike('name', '%John%')
3    ->get();

$users = DB::table('users')
    ->whereLike('name', '%John%')
    ->get();

caseSensitive引数を介して大文字と小文字を区別する検索を有効にできます。

1$users = DB::table('users')
2    ->whereLike('name', '%John%', caseSensitive: true)
3    ->get();

$users = DB::table('users')
    ->whereLike('name', '%John%', caseSensitive: true)
    ->get();

orWhereLikeメソッドを使用すると、LIKE条件を持つ「or」句を追加できます。

1$users = DB::table('users')
2    ->where('votes', '>', 100)
3    ->orWhereLike('name', '%John%')
4    ->get();

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

whereNotLikeメソッドを使用すると、クエリに「NOT LIKE」句を追加できます。

1$users = DB::table('users')
2    ->whereNotLike('name', '%John%')
3    ->get();

$users = DB::table('users')
    ->whereNotLike('name', '%John%')
    ->get();

同様に、orWhereNotLikeを使用して、NOT LIKE条件を持つ「or」句を追加できます。

1$users = DB::table('users')
2    ->where('votes', '>', 100)
3    ->orWhereNotLike('name', '%John%')
4    ->get();

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

whereLikeの大文字小文字を区別する検索オプションは、現在SQL Serverではサポートされていません。

whereIn / whereNotIn / orWhereIn / orWhereNotIn

whereInメソッドは、指定されたカラムの値が指定された配列に含まれていることを検証します。

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

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

whereNotInメソッドは、指定されたカラムの値が指定された配列に含まれていないことを検証します。

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

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

whereInメソッドの2番目の引数としてクエリオブジェクトを提供することもできます。

1$activeUsers = DB::table('users')->select('id')->where('is_active', 1);
2 
3$users = DB::table('comments')
4    ->whereIn('user_id', $activeUsers)
5    ->get();

$activeUsers = DB::table('users')->select('id')->where('is_active', 1);

$users = DB::table('comments')
    ->whereIn('user_id', $activeUsers)
    ->get();

上記の例は、次のSQLを生成します。

1select * from comments where user_id in (
2    select id
3    from users
4    where is_active = 1
5)

select * from comments where user_id in (
    select id
    from users
    where is_active = 1
)

クエリに大量の整数バインディングの配列を追加している場合、whereIntegerInRawまたはwhereIntegerNotInRawメソッドを使用すると、メモリ使用量を大幅に削減できます。

whereBetween / orWhereBetween

whereBetweenメソッドは、カラムの値が2つの値の間にあることを検証します。

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

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

whereNotBetween / orWhereNotBetween

whereNotBetweenメソッドは、カラムの値が2つの値の範囲外にあることを検証します。

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

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

whereBetweenColumns / whereNotBetweenColumns / orWhereBetweenColumns / orWhereNotBetweenColumns

whereBetweenColumnsメソッドは、カラムの値が同じテーブル行の2つのカラムの2つの値の間にあることを検証します。

1$patients = DB::table('patients')
2    ->whereBetweenColumns('weight', ['minimum_allowed_weight', 'maximum_allowed_weight'])
3    ->get();

$patients = DB::table('patients')
    ->whereBetweenColumns('weight', ['minimum_allowed_weight', 'maximum_allowed_weight'])
    ->get();

whereNotBetweenColumnsメソッドは、カラムの値が同じテーブル行の2つのカラムの2つの値の範囲外にあることを検証します。

1$patients = DB::table('patients')
2    ->whereNotBetweenColumns('weight', ['minimum_allowed_weight', 'maximum_allowed_weight'])
3    ->get();

$patients = DB::table('patients')
    ->whereNotBetweenColumns('weight', ['minimum_allowed_weight', 'maximum_allowed_weight'])
    ->get();

whereNull / whereNotNull / orWhereNull / orWhereNotNull

whereNullメソッドは、指定されたカラムの値がNULLであることを検証します。

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

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

whereNotNullメソッドは、カラムの値がNULLでないことを検証します。

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

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

whereDate / whereMonth / whereDay / whereYear / whereTime

whereDateメソッドは、カラムの値を日付と比較するために使用できます。

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

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

whereMonthメソッドは、カラムの値を特定の月と比較するために使用できます。

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

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

whereDayメソッドは、カラムの値を月の特定の日と比較するために使用できます。

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

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

whereYearメソッドは、カラムの値を特定の年と比較するために使用できます。

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

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

whereTimeメソッドは、カラムの値を特定の時間と比較するために使用できます。

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

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

wherePast / whereFuture / whereToday / whereBeforeToday / whereAfterToday

wherePastメソッドとwhereFutureメソッドは、カラムの値が過去か未来かを判断するために使用できます。

1$invoices = DB::table('invoices')
2    ->wherePast('due_at')
3    ->get();
4 
5$invoices = DB::table('invoices')
6    ->whereFuture('due_at')
7    ->get();

$invoices = DB::table('invoices')
    ->wherePast('due_at')
    ->get();

$invoices = DB::table('invoices')
    ->whereFuture('due_at')
    ->get();

whereNowOrPastメソッドとwhereNowOrFutureメソッドは、カラムの値が現在の日時を含めて過去か未来かを判断するために使用できます。

1$invoices = DB::table('invoices')
2    ->whereNowOrPast('due_at')
3    ->get();
4 
5$invoices = DB::table('invoices')
6    ->whereNowOrFuture('due_at')
7    ->get();

$invoices = DB::table('invoices')
    ->whereNowOrPast('due_at')
    ->get();

$invoices = DB::table('invoices')
    ->whereNowOrFuture('due_at')
    ->get();

whereToday、whereBeforeToday、whereAfterTodayメソッドは、カラムの値が今日、今日より前、今日より後であるかをそれぞれ判断するために使用できます。

 1$invoices = DB::table('invoices')
 2    ->whereToday('due_at')
 3    ->get();
 4 
 5$invoices = DB::table('invoices')
 6    ->whereBeforeToday('due_at')
 7    ->get();
 8 
 9$invoices = DB::table('invoices')
10    ->whereAfterToday('due_at')
11    ->get();

$invoices = DB::table('invoices')
    ->whereToday('due_at')
    ->get();

$invoices = DB::table('invoices')
    ->whereBeforeToday('due_at')
    ->get();

$invoices = DB::table('invoices')
    ->whereAfterToday('due_at')
    ->get();

同様に、whereTodayOrBeforeメソッドとwhereTodayOrAfterメソッドは、カラムの値が今日の日付を含めて今日より前か後かを判断するために使用できます。

1$invoices = DB::table('invoices')
2    ->whereTodayOrBefore('due_at')
3    ->get();
4 
5$invoices = DB::table('invoices')
6    ->whereTodayOrAfter('due_at')
7    ->get();

$invoices = DB::table('invoices')
    ->whereTodayOrBefore('due_at')
    ->get();

$invoices = DB::table('invoices')
    ->whereTodayOrAfter('due_at')
    ->get();

whereColumn / orWhereColumn

whereColumnメソッドは、2つのカラムが等しいことを検証するために使用できます。

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

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

whereColumnメソッドに比較演算子を渡すこともできます。

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

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

whereColumnメソッドにカラム比較の配列を渡すこともできます。これらの条件はand演算子を使用して結合されます。

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

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

論理的なグループ化

クエリの目的の論理的グループ化を達成するために、いくつかの「where」句を括弧でグループ化する必要がある場合があります。実際、予期しないクエリの動作を避けるために、orWhereメソッドへの呼び出しは通常、常に括弧でグループ化する必要があります。これを達成するには、whereメソッドにクロージャを渡します。

1$users = DB::table('users')
2    ->where('name', '=', 'John')
3    ->where(function (Builder $query) {
4        $query->where('votes', '>', 100)
5            ->orWhere('title', '=', 'Admin');
6    })
7    ->get();

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

ご覧のとおり、whereメソッドにクロージャを渡すと、クエリビルダに制約グループを開始するように指示します。クロージャはクエリビルダインスタンスを受け取り、これを使用して括弧グループ内に含めるべき制約を設定できます。上記の例は、次のSQLを生成します。

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

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

グローバルスコープが適用されたときの予期しない動作を避けるために、常にorWhere呼び出しをグループ化する必要があります。

高度なWhere句

Where Exists句

whereExistsメソッドを使用すると、「where exists」SQL句を記述できます。whereExistsメソッドはクロージャを受け入れ、これによりクエリビルダインスタンスが渡され、「exists」句内に配置するクエリを定義できます。

1$users = DB::table('users')
2    ->whereExists(function (Builder $query) {
3        $query->select(DB::raw(1))
4            ->from('orders')
5            ->whereColumn('orders.user_id', 'users.id');
6    })
7    ->get();

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

あるいは、クロージャの代わりにクエリオブジェクトをwhereExistsメソッドに提供することもできます。

1$orders = DB::table('orders')
2    ->select(DB::raw(1))
3    ->whereColumn('orders.user_id', 'users.id');
4 
5$users = DB::table('users')
6    ->whereExists($orders)
7    ->get();

$orders = DB::table('orders')
    ->select(DB::raw(1))
    ->whereColumn('orders.user_id', 'users.id');

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

上記の両方の例は、次のSQLを生成します。

1select * from users
2where exists (
3    select 1
4    from orders
5    where orders.user_id = users.id
6)

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

サブクエリWhere句

サブクエリの結果を特定の値と比較する「where」句を構築する必要がある場合があります。これは、whereメソッドにクロージャと値を渡すことで実現できます。たとえば、次のクエリは、特定のタイプの最近の「会員」を持つすべてのユーザーを取得します。

 1use App\Models\User;
 2use Illuminate\Database\Query\Builder;
 3 
 4$users = User::where(function (Builder $query) {
 5    $query->select('type')
 6        ->from('membership')
 7        ->whereColumn('membership.user_id', 'users.id')
 8        ->orderByDesc('membership.start_date')
 9        ->limit(1);
10}, 'Pro')->get();

use App\Models\User;
use Illuminate\Database\Query\Builder;

$users = User::where(function (Builder $query) {
    $query->select('type')
        ->from('membership')
        ->whereColumn('membership.user_id', 'users.id')
        ->orderByDesc('membership.start_date')
        ->limit(1);
}, 'Pro')->get();

または、カラムをサブクエリの結果と比較する「where」句を構築する必要がある場合があります。これは、whereメソッドにカラム、演算子、およびクロージャを渡すことで実現できます。たとえば、次のクエリは、金額が平均未満のすべての収入レコードを取得します。

1use App\Models\Income;
2use Illuminate\Database\Query\Builder;
3 
4$incomes = Income::where('amount', '<', function (Builder $query) {
5    $query->selectRaw('avg(i.amount)')->from('incomes as i');
6})->get();

use App\Models\Income;
use Illuminate\Database\Query\Builder;

$incomes = Income::where('amount', '<', function (Builder $query) {
    $query->selectRaw('avg(i.amount)')->from('incomes as i');
})->get();

全文検索Where句

全文検索Where句は現在、MariaDB、MySQL、およびPostgreSQLでサポートされています。

whereFullTextメソッドとorWhereFullTextメソッドは、全文検索インデックスを持つカラムのクエリに全文検索「where」句を追加するために使用できます。これらのメソッドは、Laravelによって基盤となるデータベースシステムの適切なSQLに変換されます。たとえば、MariaDBまたはMySQLを利用するアプリケーションでは、MATCH AGAINST句が生成されます。

1$users = DB::table('users')
2    ->whereFullText('bio', 'web developer')
3    ->get();

$users = DB::table('users')
    ->whereFullText('bio', 'web developer')
    ->get();

順序、グループ化、Limit、Offset

順序指定

orderByメソッド

orderByメソッドを使用すると、クエリの結果を指定されたカラムでソートできます。orderByメソッドが受け入れる最初の引数はソートしたいカラムで、2番目の引数はソートの方向を決定し、ascまたはdescのいずれかを指定できます。

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

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

複数のカラムでソートするには、必要に応じてorderByを複数回呼び出すだけです。

1$users = DB::table('users')
2    ->orderBy('name', 'desc')
3    ->orderBy('email', 'asc')
4    ->get();

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

latestメソッドとoldestメソッド

latestメソッドとoldestメソッドを使用すると、結果を日付で簡単に順序付けできます。デフォルトでは、結果はテーブルのcreated_atカラムで順序付けられます。または、ソートしたいカラム名を渡すこともできます。

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

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

ランダムな順序付け

inRandomOrderメソッドを使用して、クエリ結果をランダムにソートできます。たとえば、このメソッドを使用してランダムなユーザーを取得できます。

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

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

既存の順序付けの削除

reorderメソッドは、クエリに以前に適用されたすべての「order by」句を削除します。

1$query = DB::table('users')->orderBy('name');
2 
3$unorderedUsers = $query->reorder()->get();

$query = DB::table('users')->orderBy('name');

$unorderedUsers = $query->reorder()->get();

reorderメソッドを呼び出すときにカラムと方向を渡すことで、すべての既存の「order by」句を削除し、クエリにまったく新しい順序を適用できます。

1$query = DB::table('users')->orderBy('name');
2 
3$usersOrderedByEmail = $query->reorder('email', 'desc')->get();

$query = DB::table('users')->orderBy('name');

$usersOrderedByEmail = $query->reorder('email', 'desc')->get();

グループ化

groupByメソッドとhavingメソッド

ご想像のとおり、groupByメソッドとhavingメソッドを使用してクエリ結果をグループ化できます。havingメソッドのシグネチャはwhereメソッドのシグネチャに似ています。

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

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

havingBetweenメソッドを使用して、指定された範囲内の結果をフィルタリングできます。

1$report = DB::table('orders')
2    ->selectRaw('count(id) as number_of_orders, customer_id')
3    ->groupBy('customer_id')
4    ->havingBetween('number_of_orders', [5, 15])
5    ->get();

$report = DB::table('orders')
    ->selectRaw('count(id) as number_of_orders, customer_id')
    ->groupBy('customer_id')
    ->havingBetween('number_of_orders', [5, 15])
    ->get();

groupByメソッドに複数の引数を渡して、複数のカラムでグループ化できます。

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

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

より高度なhaving文を構築するには、havingRawメソッドを参照してください。

LimitとOffset

skipメソッドとtakeメソッド

skipメソッドとtakeメソッドを使用して、クエリから返される結果の数を制限したり、クエリ内の指定された数の結果をスキップしたりできます。

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

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

あるいは、limitメソッドとoffsetメソッドを使用することもできます。これらのメソッドは、それぞれtakeメソッドとskipメソッドと機能的に同等です。

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

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

条件節

特定のクエリ句を別の条件に基づいてクエリに適用したい場合があります。たとえば、受信HTTPリクエストに特定の入力値が存在する場合にのみwhere文を適用したい場合があります。これはwhenメソッドを使用して実現できます。

1$role = $request->input('role');
2 
3$users = DB::table('users')
4    ->when($role, function (Builder $query, string $role) {
5        $query->where('role_id', $role);
6    })
7    ->get();

$role = $request->input('role');

$users = DB::table('users')
    ->when($role, function (Builder $query, string $role) {
        $query->where('role_id', $role);
    })
    ->get();

whenメソッドは、最初の引数がtrueの場合にのみ指定されたクロージャを実行します。最初の引数がfalseの場合、クロージャは実行されません。したがって、上記の例では、whenメソッドに渡されたクロージャは、受信リクエストにroleフィールドが存在し、trueと評価された場合にのみ呼び出されます。

whenメソッドの3番目の引数として別のクロージャを渡すことができます。このクロージャは、最初の引数がfalseと評価された場合にのみ実行されます。この機能の使用方法を説明するために、クエリのデフォルトの順序付けを構成するために使用します。

1$sortByVotes = $request->boolean('sort_by_votes');
2 
3$users = DB::table('users')
4    ->when($sortByVotes, function (Builder $query, bool $sortByVotes) {
5        $query->orderBy('votes');
6    }, function (Builder $query) {
7        $query->orderBy('name');
8    })
9    ->get();

$sortByVotes = $request->boolean('sort_by_votes');

$users = DB::table('users')
    ->when($sortByVotes, function (Builder $query, bool $sortByVotes) {
        $query->orderBy('votes');
    }, function (Builder $query) {
        $query->orderBy('name');
    })
    ->get();

Insert文

クエリビルダは、データベーステーブルにレコードを挿入するために使用できるinsertメソッドも提供しています。insertメソッドは、カラム名と値の配列を受け入れます。

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

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

配列の配列を渡すことで、一度に複数のレコードを挿入できます。各配列は、テーブルに挿入されるべきレコードを表します。

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

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

insertOrIgnoreメソッドは、データベースにレコードを挿入する際のエラーを無視します。このメソッドを使用する場合、重複レコードエラーは無視され、データベースエンジンによっては他のタイプのエラーも無視される可能性があることに注意してください。たとえば、insertOrIgnoreはMySQLの厳格モードをバイパスします。

1DB::table('users')->insertOrIgnore([
2    ['id' => 1, 'email' => '[email protected]'],
3    ['id' => 2, 'email' => '[email protected]'],
4]);

DB::table('users')->insertOrIgnore([
    ['id' => 1, 'email' => '[email protected]'],
    ['id' => 2, 'email' => '[email protected]'],
]);

insertUsingメソッドは、サブクエリを使用して挿入すべきデータを決定しながら、新しいレコードをテーブルに挿入します。

1DB::table('pruned_users')->insertUsing([
2    'id', 'name', 'email', 'email_verified_at'
3], DB::table('users')->select(
4    'id', 'name', 'email', 'email_verified_at'
5)->where('updated_at', '<=', now()->subMonth()));

DB::table('pruned_users')->insertUsing([
    'id', 'name', 'email', 'email_verified_at'
], DB::table('users')->select(
    'id', 'name', 'email', 'email_verified_at'
)->where('updated_at', '<=', now()->subMonth()));

自動インクリメントID

テーブルに自動インクリメントIDがある場合は、insertGetIdメソッドを使用してレコードを挿入し、その後IDを取得します。

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

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

PostgreSQLを使用する場合、insertGetIdメソッドは自動インクリメントカラムの名前がidであることを期待します。別の「シーケンス」からIDを取得したい場合は、insertGetIdメソッドの2番目のパラメータとしてカラム名を渡すことができます。

Upsert

upsertメソッドは、存在しないレコードを挿入し、すでに存在するレコードを指定した新しい値で更新します。メソッドの最初の引数は挿入または更新する値で構成され、2番目の引数は関連テーブル内のレコードを一意に識別するカラムをリストします。メソッドの3番目で最後の引数は、データベースに一致するレコードがすでに存在する場合に更新されるべきカラムの配列です。

1DB::table('flights')->upsert(
2    [
3        ['departure' => 'Oakland', 'destination' => 'San Diego', 'price' => 99],
4        ['departure' => 'Chicago', 'destination' => 'New York', 'price' => 150]
5    ],
6    ['departure', 'destination'],
7    ['price']
8);

DB::table('flights')->upsert(
    [
        ['departure' => 'Oakland', 'destination' => 'San Diego', 'price' => 99],
        ['departure' => 'Chicago', 'destination' => 'New York', 'price' => 150]
    ],
    ['departure', 'destination'],
    ['price']
);

上記の例では、Laravelは2つのレコードの挿入を試みます。同じdepartureカラムとdestinationカラムの値を持つレコードがすでに存在する場合、Laravelはそのレコードのpriceカラムを更新します。

SQL Serverを除くすべてのデータベースでは、upsertメソッドの2番目の引数のカラムに「primary」または「unique」インデックスが必要です。さらに、MariaDBおよびMySQLデータベースドライバは、upsertメソッドの2番目の引数を無視し、常にテーブルの「primary」および「unique」インデックスを使用して既存のレコードを検出します。

Update文

クエリビルダは、データベースへのレコードの挿入に加えて、updateメソッドを使用して既存のレコードを更新することもできます。updateメソッドは、insertメソッドと同様に、更新するカラムを示すカラムと値のペアの配列を受け入れます。updateメソッドは影響を受けた行数を返します。where句を使用してupdateクエリを制約できます。

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

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

更新または挿入

データベース内の既存のレコードを更新したり、一致するレコードが存在しない場合に作成したりしたい場合があります。このシナリオでは、updateOrInsertメソッドを使用できます。updateOrInsertメソッドは2つの引数を受け入れます：レコードを見つけるための条件の配列と、更新するカラムを示すカラムと値のペアの配列です。

updateOrInsertメソッドは、最初の引数のカラムと値のペアを使用して一致するデータベースレコードを見つけようとします。レコードが存在する場合、2番目の引数の値で更新されます。レコードが見つからない場合、両方の引数のマージされた属性で新しいレコードが挿入されます。

1DB::table('users')
2    ->updateOrInsert(
3        ['email' => '[email protected]', 'name' => 'John'],
4        ['votes' => '2']
5    );

DB::table('users')
    ->updateOrInsert(
        ['email' => '[email protected]', 'name' => 'John'],
        ['votes' => '2']
    );

updateOrInsertメソッドにクロージャを提供して、一致するレコードの存在に基づいてデータベースに更新または挿入される属性をカスタマイズできます。

 1DB::table('users')->updateOrInsert(
 2    ['user_id' => $user_id],
 3    fn ($exists) => $exists ? [
 4        'name' => $data['name'],
 5        'email' => $data['email'],
 6    ] : [
 7        'name' => $data['name'],
 8        'email' => $data['email'],
 9        'marketable' => true,
10    ],
11);

DB::table('users')->updateOrInsert(
    ['user_id' => $user_id],
    fn ($exists) => $exists ? [
        'name' => $data['name'],
        'email' => $data['email'],
    ] : [
        'name' => $data['name'],
        'email' => $data['email'],
        'marketable' => true,
    ],
);

JSONカラムの更新

JSONカラムを更新する場合は、->構文を使用してJSONオブジェクトの適切なキーを更新する必要があります。この操作はMariaDB 10.3+、MySQL 5.7+、およびPostgreSQL 9.5+でサポートされています。

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

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

インクリメントとデクリメント

クエリビルダは、指定されたカラムの値をインクリメントまたはデクリメントするための便利なメソッドも提供しています。これらのメソッドは両方とも少なくとも1つの引数を受け入れます：変更するカラムです。2番目の引数を指定して、カラムをインクリメントまたはデクリメントする量を指定できます。

1DB::table('users')->increment('votes');
2 
3DB::table('users')->increment('votes', 5);
4 
5DB::table('users')->decrement('votes');
6 
7DB::table('users')->decrement('votes', 5);

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

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

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

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

必要に応じて、インクリメントまたはデクリメント操作中に更新する追加のカラムを指定することもできます。

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

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

さらに、incrementEachメソッドとdecrementEachメソッドを使用して、一度に複数のカラムをインクリメントまたはデクリメントできます。

1DB::table('users')->incrementEach([
2    'votes' => 5,
3    'balance' => 100,
4]);

DB::table('users')->incrementEach([
    'votes' => 5,
    'balance' => 100,
]);

Delete文

クエリビルダのdeleteメソッドは、テーブルからレコードを削除するために使用できます。deleteメソッドは影響を受けた行数を返します。deleteメソッドを呼び出す前に「where」句を追加することで、delete文を制約できます。

1$deleted = DB::table('users')->delete();
2 
3$deleted = DB::table('users')->where('votes', '>', 100)->delete();

$deleted = DB::table('users')->delete();

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

悲観的ロック

クエリビルダには、select文を実行するときに「悲観的ロック」を実現するのに役立ついくつかの関数も含まれています。「共有ロック」で文を実行するには、sharedLockメソッドを呼び出します。共有ロックは、トランザクションがコミットされるまで、選択された行が変更されるのを防ぎます。

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

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

あるいは、lockForUpdateメソッドを使用することもできます。「更新用」ロックは、選択されたレコードが変更されたり、別の共有ロックで選択されたりするのを防ぎます。

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

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

必須ではありませんが、悲観的ロックをトランザクション内でラップすることをお勧めします。これにより、取得したデータが操作全体が完了するまでデータベースで変更されないことが保証されます。失敗した場合、トランザクションはすべての変更をロールバックし、ロックを自動的に解放します。

 1DB::transaction(function () {
 2    $sender = DB::table('users')
 3        ->lockForUpdate()
 4        ->find(1);
 5 
 6    $receiver = DB::table('users')
 7        ->lockForUpdate();
 8        ->find(2);
 9 
10    if ($sender->balance < 100) {
11        throw new RuntimeException('Balance too low.');
12    }
13 
14    DB::table('users')
15        ->where('id', $sender->id)
16        ->update([
17            'balance' => $sender->balance - 100
18        ]);
19 
20    DB::table('users')
21        ->where('id', $receiver->id)
22        ->update([
23            'balance' => $receiver->balance + 100
24        ]);
25});

DB::transaction(function () {
    $sender = DB::table('users')
        ->lockForUpdate()
        ->find(1);

    $receiver = DB::table('users')
        ->lockForUpdate();
        ->find(2);

    if ($sender->balance < 100) {
        throw new RuntimeException('Balance too low.');
    }

    DB::table('users')
        ->where('id', $sender->id)
        ->update([
            'balance' => $sender->balance - 100
        ]);

    DB::table('users')
        ->where('id', $receiver->id)
        ->update([
            'balance' => $receiver->balance + 100
        ]);
});

デバッグ

クエリを構築中にddメソッドとdumpメソッドを使用して、現在のクエリバインディングとSQLをダンプできます。ddメソッドはデバッグ情報を表示し、その後リクエストの実行を停止します。dumpメソッドはデバッグ情報を表示しますが、リクエストの実行を継続させます。

1DB::table('users')->where('votes', '>', 100)->dd();
2 
3DB::table('users')->where('votes', '>', 100)->dump();

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

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

dumpRawSqlメソッドとddRawSqlメソッドは、クエリで呼び出して、すべてのパラメータバインディングが適切に置換されたクエリのSQLをダンプできます。

1DB::table('users')->where('votes', '>', 100)->dumpRawSql();
2 
3DB::table('users')->where('votes', '>', 100)->ddRawSql();

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

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

序文

はじめに

アーキテクチャのコンセプト

基本

より深く知る

セキュリティ

データベース

Eloquent ORM

テスト

パッケージ

データベース：クエリビルダ

製品

パッケージ

リソース