先生と生徒の会話形式で理解しよう

生徒

「Symfonyで複雑な条件を使ってデータベースを検索する方法ってあるんですか？」

先生

「SymfonyではDoctrine ORMのQueryBuilderという仕組みを使えば、複雑な条件でも柔軟に検索できますよ。」

生徒

「findやfindByではできないような検索もできるんですか？」

先生

「もちろんできます。ではこれから検索条件を自由に組み立てられるQueryBuilderをやさしく説明していきますね。」

1. QueryBuilderとは何か？初心者にもわかる仕組み

SymfonyのDoctrine ORMには、データベースの検索条件を自由に組み立てられるQueryBuilder（クエリビルダー）があります。これは「検索する内容をブロックのように積み上げて作れる道具」のようなものです。SQLという難しい言葉を覚えなくても、PHPのコードだけで複雑な検索条件を作れるのが最大のメリットです。

プログラミング未経験の人に分かりやすく例えると、QueryBuilderは「好きな材料を選んで自由に料理ができるキッチン」のようなものです。どんな条件を使うのか、どのデータを取り出すのかを自由に組み合わせて、自分の求める検索を作ることができます。

たとえば、特定の名前で検索したい、日付の範囲を指定したい、複数の条件を組み合わせたい、といった操作を柔軟に行うことができます。

2. QueryBuilderの基本的な使い方

QueryBuilderはエンティティのリポジトリから呼び出します。まずは最も基本的な書き方を見てみましょう。下記の例では、Userエンティティを検索するためにQueryBuilderを使っています。

■ QueryBuilderの基本サンプル


$query = $userRepository->createQueryBuilder('u')
    ->where('u.age > :age')
    ->setParameter('age', 20)
    ->getQuery()
    ->getResult();

このコードでは、「ageが20より大きいユーザーを検索してね」という条件をQueryBuilderで作っています。キーワードのように積み上げていくのが特徴で、SQLを書かずに柔軟な検索ができる点がとても便利です。

また、whereの中に「:age」という書き方がありますが、これはパラメータを表し、SQLを安全に実行するための仕組み（プレースホルダ）です。初心者でも安全に検索できるようにするための大事なポイントです。

3. 複数条件を組み合わせた検索方法

QueryBuilder最大の強みは、複数の条件をつなげて柔軟に検索できることです。たとえば「名前に特定の文字が含まれていて、年齢が20以上」というように条件を複数組み合わせることができます。

■ AND条件を使った検索


$query = $userRepository->createQueryBuilder('u')
    ->where('u.name LIKE :keyword')
    ->andWhere('u.age >= :age')
    ->setParameter('keyword', '%山%')
    ->setParameter('age', 20)
    ->getQuery()
    ->getResult();

LIKEというキーワードは「部分一致検索」を意味します。たとえば「山田」「山本」など、含まれる文字を探すときに使います。初心者でもイメージしやすい検索方法です。

andWhereを使うことで条件を積み重ねていき、そのままSQL文を組み立ててくれる便利機能です。

4. OR条件を使った検索方法

「どちらかの条件を満たしていれば良い」という検索をしたい場合はorWhereを使います。たとえば「名前に山が含まれるか、もしくは年齢が30以上」のような場合です。

■ OR条件のサンプルコード


$query = $userRepository->createQueryBuilder('u')
    ->where('u.name LIKE :keyword')
    ->orWhere('u.age >= :age')
    ->setParameter('keyword', '%山%')
    ->setParameter('age', 30)
    ->getQuery()
    ->getResult();

orWhereは「どちらか一方でも条件に合えばOK」という検索に使います。複雑な条件でも組み合わせ次第で自由に検索できるのがQueryBuilderの面白いところです。

5. 並び順や取得件数を指定した検索

QueryBuilderは条件だけでなく、並び順や取得件数の制限にも対応しています。データ量が増えると検索結果が多くなりすぎるため、制限をかけることがよくあります。

■ 並び順・件数指定のサンプル


$query = $userRepository->createQueryBuilder('u')
    ->orderBy('u.id', 'DESC')
    ->setMaxResults(5)
    ->getQuery()
    ->getResult();

orderByは並び順を決める命令で、DESCは「降順（大きい順）」を意味します。また、setMaxResultsを使うと取得する件数を制限できます。たとえば「新しい順に5件だけ表示したい」というような場面で使う便利な機能です。

6. QueryBuilderで自由な検索ができる理由

DoctrineのQueryBuilderが便利なのは、条件を自由に積み重ねられるだけでなく、裏側でSQLを安全に組み立ててくれる仕組みがあるからです。初心者が間違いやすいSQLの書き方や、入力された値によって起きる危険な攻撃（SQLインジェクション）を防ぐことができるように設計されています。

また、QueryBuilderはSymfonyの開発でよく使われる「複雑な検索条件が必要な場面」で大活躍します。日付範囲検索、タグ検索、複数項目の組み合わせなど、サイトの検索機能を作るときに欠かせない存在です。

「簡単な検索はfind」「条件を柔軟に組むときはQueryBuilder」という使い分けができるようになると、Symfonyでの開発が一気にスムーズになります。

Symfony Doctrine ORMのQueryBuilderを完全ガイド！初心者でもわかる柔軟な検索方法