PHPで学ぶGraphQL API入門！初心者でもわかる実装ステップと使い方

PHP の GraphQL API の実装方法

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

生徒

「PHPでAPIを作るときに、GraphQLという仕組みが良いって聞いたんですが、全くイメージができなくて…。」

先生

「GraphQLは、必要なデータだけを自由に取得できる便利なAPI方式なんです。PHPでも簡単に作れますよ。」

生徒

「REST APIとは何が違うんですか？どんなときに使うんでしょうか？」

先生

「それでは、GraphQLの仕組みと、PHPでの実装方法を一つずつ見ていきましょう。」

1. GraphQLとは？超初心者にもわかる基本の考え方

GraphQL（グラフキューエル）は、Facebookが開発したAPIのしくみで、クライアント（アプリやブラウザ）が「欲しいデータだけ」を自由にリクエストできるのが大きな特徴です。PHPで作ったサーバー側と、スマホやWebブラウザなどのクライアント側が、「どんな項目が必要か」を相談してやり取りするための共通ルール、と考えるとイメージしやすくなります。

イメージとしては、レストランで使う「注文表」のようなものです。食べたい料理だけにチェックを入れて店員さんに渡すと、その分だけ運ばれてきますよね。GraphQLも同じで、「ユーザー名とメールアドレスだけ欲しい」「記事タイトルと投稿日だけ欲しい」といった形で、必要な情報をまとめて指定できます。サーバー側（PHP）は、その注文表を見て、指定された項目だけを返してあげるイメージです。

従来のREST APIでは、複数のデータを集めたいときには、ユーザー情報のAPI、記事一覧のAPI、コメントのAPI…というように、いくつものURLに何度もアクセスする必要がありました。そのたびに不要な項目も一緒に返ってくることが多く、「欲しい情報は一部だけなのに通信量が多い」という状態になりがちです。しかしGraphQLなら、一度のリクエストの中で「ユーザーの名前」「記事タイトル」「コメント数」といった必要な情報だけを指定してまとめて受け取れます。その結果、無駄な通信が減り、スマホアプリやWebサービスの動きが軽くなりやすいというメリットがあります。

たとえば、PHPで作ったブログサービスを想像してみてください。トップページに表示したいのは「ユーザー名」「プロフィール画像」「最新の記事タイトル」だけだとします。GraphQLを使えば、「ユーザー名」「プロフィール画像」「最新の記事タイトル」という必要な項目だけを一度にリクエストできます。プログラミング未経験の方でも、「必要な情報だけをピンポイントでお願いできる仕組み」と理解しておけば、GraphQLやPHPでのAPI開発の全体像がぐっとつかみやすくなります。

2. REST APIとGraphQLの違いを例えながら理解しよう

REST APIは「決まったおかずがセットになった定食メニュー」、GraphQLは「好きなおかずを自由に詰められるお弁当」のようなイメージです。定食メニューでは、ご飯・味噌汁・メイン・小鉢など内容が最初から決まっています。一方で、お弁当なら「からあげ多め」「サラダ少なめ」のように、自分の好みに合わせて中身を選べます。PHPで作るAPIも同じで、REST APIは「決まった形のデータセット」、GraphQLは「欲しい項目だけを選んで受け取れる仕組み」と考えるとイメージしやすくなります。

REST APIの場合は、あらかじめ「ユーザー情報を返すURL」「記事一覧を返すURL」というようにURLごとに役割が決まっています。そのURLにアクセスすると、決められた形のJSONデータが一式まとめて返ってきます。たとえば、ただ「ユーザー名だけ知りたい」ときでも、メールアドレス・住所・登録日時など、たくさんの項目が一緒に返ってくることがあります。これが「定食メニュー」のイメージです。

一方、GraphQLでは「どの項目が必要か」をクエリ（質問文）の中で細かく指定できます。「名前だけ欲しい」「名前とメールアドレスだけ欲しい」のように、必要なものだけを選んでサーバーにお願いできます。そのため、無駄なデータを受け取らずに済み、スマホアプリやブラウザの通信量を減らすことができます。PHPでWebサービスやAPIを作るとき、「ページごとに欲しい情報が少しずつ違う」という場面で特に威力を発揮します。

具体的なイメージをつかむために、REST APIとGraphQLで同じ情報を取得する例を見てみましょう。

REST APIのイメージ

まずは、よくあるREST APIのイメージです。ユーザー情報を取得するURLにアクセスすると、決められた形のデータがまとめて返ってきます。


// REST APIの例（イメージ）

// ユーザー情報を取得するURLにアクセス
GET /api/users/1

// 返ってくるJSONの例
{
  "id": 1,
  "name": "Taro",
  "email": "taro@example.com",
  "address": "Tokyo...",
  "created_at": "2024-01-01 10:00:00"
}

この例では、「ユーザー名だけ知りたい」と思っていても、住所や登録日時など、まとめて一式が返ってきます。Webページによっては「名前だけ表示できれば十分」というケースも多いのに、それ以外の情報も毎回受け取ることになり、結果として通信量が増えてしまいます。PHPでREST APIを作っていると、「本当はここまでいらないんだけどな…」という場面が出てきやすくなります。

GraphQLのイメージ

同じ「ユーザーの情報」を取得するときでも、GraphQLでは「欲しい項目」をクエリの中で選んで指定します。たとえば、名前とメールアドレスだけ欲しい場合は、次のようなイメージになります。


// GraphQLクエリの例（イメージ）

{
  user(id: 1) {
    name
    email
  }
}

// 返ってくるJSONの例
{
  "data": {
    "user": {
      "name": "Taro",
      "email": "taro@example.com"
    }
  }
}

クエリの中で name と email だけを書いているので、返ってくるデータもその2つだけです。住所や登録日時などはまったく含まれません。「注文表に書いたものだけ運ばれてくる」という、1章で紹介したGraphQLのイメージそのままの動きになっています。プログラミング未経験の方でも、「欲しい項目だけを紙に書いて店員さんに渡す」と考えると、REST APIとの違いがぐっとわかりやすくなります。

まとめると、PHPでAPIを作るときのポイントは次の通りです。REST APIはURLごとに決まったデータセットを返すため、「シンプルだけど柔軟性はやや低め」という特徴があります。GraphQLは、1つの入り口（エンドポイント）に対してクエリで項目を指定する仕組みなので、「柔軟で、画面ごとに欲しいデータだけを取り出しやすい」という特徴があります。どちらもPHPで実装できますが、「無駄な通信を減らしたい」「フロントエンドが細かくデータを選びたい」という場面では、GraphQLのほうが便利になるケースが増えてきています。

3. PHPでGraphQL APIを作るには？必要なライブラリと準備

PHPでGraphQL APIを作るときによく利用される定番ライブラリが webonyx/graphql-php です。GraphQLの基本構造である「スキーマ」「クエリ」「リゾルバ」を扱いやすい形で提供してくれるため、初心者でも比較的スムーズに扱えます。まずは、このライブラリを使えるように環境を整えるところから始めましょう。

インストールには PHPのパッケージ管理ツールである Composer を使います。Composerは、必要なライブラリを自動でダウンロードしプロジェクトに組み込んでくれる便利なツールです。まだ使ったことがない方でも、以下のコマンドを実行するだけで準備できます。


composer require webonyx/graphql-php

コマンドが完了すると、GraphQL APIを作るためのファイル一式がプロジェクトに追加されます。この状態になれば、PHPでスキーマを定義したり、クエリを処理したりする準備が整っているということです。ここまでの作業はとても簡単で、プログラミング初心者の方でもつまずきにくいステップです。

インストール後にできることをイメージしてみよう

「本当にこれだけで準備完了なの？」と不安に思う方もいるかもしれません。実は、GraphQL APIづくりの最初のハードルはこのライブラリの導入だけで、ここさえ済めば、あとは必要なデータの構造を決めたり、どう返すかを考えたりする段階に進めます。

たとえば、次のような超シンプルな“お試しスクリプト”を作ることで、GraphQLの動作を確認できます。


<?php
require 'vendor/autoload.php';

use GraphQL\GraphQL;
use GraphQL\Type\Schema;
use GraphQL\Type\Definition\ObjectType;

// 「hello」という文字を返すだけの簡単なAPI
$query = new ObjectType([
    'name' => 'Query',
    'fields' => [
        'hello' => [
            'type' => \GraphQL\Type\Definition\Type::string(),
            'resolve' => fn() => 'Hello GraphQL!'
        ]
    ]
]);

$schema = new Schema(['query' => $query]);

$result = GraphQL::executeQuery($schema, '{ hello }');
print_r($result->toArray());
?>

このサンプルでは、GraphQLに「hello」という項目をリクエストすると、Hello GraphQL! と返してくれる仕組みになっています。実際にはより複雑なデータを扱っていきますが、まずはこのように“動く感覚”をつかんでおくと、後の理解がとてもスムーズになります。

4. GraphQLの基本構成「スキーマ」「クエリ」「リゾルバ」を理解しよう

GraphQL APIは、大きく分けて次の3つの要素によって動いています。どれか1つでも欠けると成り立たないため、PHPでGraphQLを扱う際の“基本の部品”として覚えておくと理解がとても速くなります。初心者の方でも、まずはこの3つがどのような役割なのか、家の設計図に例えながらイメージしてみましょう。

スキーマ（Schema）：扱うデータの種類や構造を決める設計図。家でいう間取りを決める役割です。
クエリ（Query）：クライアント側が「何が欲しいか」を指定する命令文。設計図を基に「どの部屋を見たいか」をリクエストするイメージです。
リゾルバ（Resolver）：クエリを受け取り、実際にデータを返す処理の本体。指定された部屋の情報を実際に案内してくれる役割です。

この3つがそろうと、GraphQLは「欲しい情報だけを返す」という柔軟な動きを実現できます。REST APIとの大きな違いがここにあり、スキーマを軸にしてクライアントが自由にデータを選べる点が大きな魅力です。イメージをさらに深めるため、非常にシンプルなサンプルを見てみましょう。

簡単なサンプルで構造を確認しよう

ここでは、GraphQLの基本3要素がどのように関係しているのかを体験できる、最小構成のPHPコードを紹介します。内部の処理はとてもシンプルですが、GraphQLの流れを理解するには十分です。


<?php
require 'vendor/autoload.php';

use GraphQL\Type\Definition\ObjectType;
use GraphQL\Type\Definition\Type;
use GraphQL\Type\Schema;
use GraphQL\GraphQL;

// 1. スキーマで扱う型（User型の例）
$userType = new ObjectType([
    'name' => 'User',
    'fields' => [
        'name' => Type::string(),
    ]
]);

// 2. クエリ（"user" という名前でリクエストできる）
$query = new ObjectType([
    'name' => 'Query',
    'fields' => [
        'user' => [
            'type' => $userType,
            'resolve' => fn() => ['name' => 'Sample User']
        ]
    ]
]);

// 3. スキーマを作成
$schema = new Schema(['query' => $query]);

// 実行テスト用（{ user { name } } を実行）
$result = GraphQL::executeQuery($schema, '{ user { name } }');
print_r($result->toArray());
?>

このサンプルは「名前を持つユーザーを1人返すだけ」の最小構成ですが、GraphQLの3つの要素がどのように連携しているかを確認できます。スキーマでデータ型を定義し、クエリで取得する項目を指定し、リゾルバがその内容を返す…。この流れを理解すると、複雑なデータを扱う場合でも仕組みが見通しやすくなり、PHPでのGraphQL開発がぐっと楽になります。

5. PHPで作るGraphQL APIの超簡単サンプル

ここでは、GraphQLの基本的な流れをつかむために、たった一つのユーザー情報を返すだけの「超シンプルなAPI」を作ってみましょう。複雑な準備は必要なく、GraphQLの動作が直感的に理解できる構成になっています。PHP初心者の方でも「こうやってデータが返ってくるのか」とイメージしやすいサンプルです。


<?php
require_once 'vendor/autoload.php';

use GraphQL\Type\Definition\ObjectType;
use GraphQL\Type\Schema;
use GraphQL\GraphQL;
use GraphQL\Type\Definition\Type;

// 1. User型（返すデータの形）を定義
$userType = new ObjectType([
    'name' => 'User',
    'fields' => [
        'name' => ['type' => Type::string()],
        'age' => ['type' => Type::int()],
    ]
]);

// 2. Query（取得命令）を設定
$queryType = new ObjectType([
    'name' => 'Query',
    'fields' => [
        'user' => [
            'type' => $userType,
            'resolve' => function () {
                // 実際に返す“サンプルデータ”
                return ['name' => 'Taro', 'age' => 25];
            }
        ]
    ]
]);

// 3. スキーマを作成（GraphQL全体の設計図）
$schema = new Schema([
    'query' => $queryType
]);

// クエリ例:
// {
//   user { name age }
// }

try {
    $rawInput = file_get_contents('php://input');
    $input = json_decode($rawInput, true);
    $query = $input['query'];

    // クエリを実行して結果を返す
    $result = GraphQL::executeQuery($schema, $query);
    echo json_encode($result->toArray());
} catch (Exception $e) {
    echo json_encode(['error' => $e->getMessage()]);
}
?>

このサンプルでは、GraphQLに対して user { name age } というクエリを送ると、シンプルに「Taro」と「25」という値が返ってきます。REST APIのようにURLを複数用意する必要もなく、欲しい項目だけを指定して受け取れる“GraphQLらしさ”を体験できる構成になっています。最初の一歩として、この小さなAPIが動くだけでGraphQLの仕組みがぐっと理解しやすくなるはずです。

6. GraphQLのクエリの書き方を理解しよう

GraphQLの大きな特徴のひとつが「欲しいデータだけを明確に書ける」という点です。REST APIではURLによって取得する内容があらかじめ決められていますが、GraphQLでは“クエリ”と呼ばれるリクエスト文を自分で組み立てることで、必要な項目だけを指定して取り出せます。文章を書くような感覚でデータを指定できるため、プログラミング初心者の方でも直感的に理解しやすい仕組みです。

基本のクエリ例を見てみよう

たとえば「ユーザーの名前と年齢だけ知りたい」という場合、GraphQLでは次のように書きます。とてもシンプルで、見慣れてくると、まるで“データの注文表”を書くような感覚になります。


{
    user {
        name
        age
    }
}

このクエリは「user というデータの中から name と age の2項目だけ返してください」という意味になります。もし他の情報が欲しくなったら、項目名を追加するだけでOKです。不要なデータは一切返ってこないため、通信量が少なく済むというメリットもあります。

クエリがどのように動くのかイメージしよう

GraphQLでは、クエリを送るとサーバー側の「リゾルバ」がその内容を読み取り、必要なデータだけを返してくれます。つまり、クエリは“欲しい情報をサーバーに伝えるメッセージ”のような存在です。以下に、実際にPHPのGraphQL APIへクエリを送ったときに返ってくる例を紹介します。


{
  "data": {
    "user": {
      "name": "Taro",
      "age": 25
    }
  }
}

このように、書いたクエリそのままの形でデータが返ってくるため、何が取得できるか迷うことがなく、学習もしやすいのがGraphQLの魅力です。REST APIのように複数のURLを覚える必要もなく、使いたいデータだけを明確に指定できるシンプルさが、初心者にとって大きな利点となります。

7. PHP GraphQL APIが便利な理由と活用例

PHPでGraphQL APIを取り入れると、Webアプリやスマートフォンアプリの開発がこれまでよりもシンプルで効率的になります。特に「必要なデータだけを取り出せる」という点が非常に大きなメリットで、無駄な通信を避けながら柔軟なデータ取得が可能になります。ここでは、初心者の方でもイメージしやすい具体的な活用シーンを挙げながら、その便利さを紹介していきます。

無駄なデータ通信を減らしたいとき
GraphQLでは、画面で使うデータだけをピンポイントで要求できるため、通信量を減らしアプリ表示を軽快にできます。REST APIでありがちな「使わないデータも返ってくる」という問題を避けられます。
複雑なデータを一度に取得したいとき
たとえば「ユーザー情報」「投稿一覧」「コメント数」をまとめて取得したい場合でも、GraphQLなら1回のリクエストで完結します。複数URLを叩く必要がなく、コードも管理もしやすくなります。
APIの管理をわかりやすくしたいとき
データ構造がスキーマとして明確に定義されるため、開発メンバー間の認識が揃い、仕様の把握もしやすくなります。特に長期運用のサービスでは大きな効果を発揮します。

さらに、GraphQLは「あとから項目を増やす」「画面ごとに異なるデータが必要」というケースにも柔軟に対応できます。PHPでWeb APIを作る際の選択肢として、今後ますますGraphQLが重宝される理由はこうした“拡張しやすさ”にもあります。小さなプロジェクトでも大規模開発でも導入しやすいため、初心者が最初に触れておく技術としても非常におすすめです。

まとめ

PHPでGraphQL APIを実装するためには、まずGraphQLが持つ「必要なデータだけを取得できるしくみ」を理解することが大切です。従来のREST APIとは異なり、GraphQLではクライアント側が自由に項目を指定できるため、通信量が削減され、Webサービスやスマートフォンアプリのパフォーマンスが向上しやすくなります。初心者の方でも、スキーマ、クエリ、リゾルバという三つの基本要素を押さえることで、複雑なAPI機能を扱うときにも迷いにくくなり、実践的な開発をスムーズに進められます。特にPHPでは、webonyx/graphql-php というライブラリを利用することで、型定義やフィールド設定を直感的に書けるため、進めながら自然と構造を理解できる点も魅力です。

また、GraphQLの最大の特徴である「柔軟なデータ取得」は、一度使ってみるとすぐに便利さを実感できます。例えば、ユーザー情報の一覧を取得するとき、名前だけ、または名前と年齢だけ、といった具合に好きな項目を組み合わせられるため、API利用側の自由度が高くなります。この特性は、フロントエンドとバックエンドが協力して作り上げる現代の開発に非常に相性が良く、さらにシステムが複雑になるほどGraphQLのメリットはより大きく感じられるでしょう。PHPを学び始めたばかりの方でも、基本を押さえれば確実に応用していける技術なので、少しずつ手を動かしながら感覚を掴んでいくのがおすすめです。

ここでは基本的なサンプルを使用しましたが、GraphQLはクエリだけでなく、データを追加・更新・削除する「ミューテーション」も扱えるため、本格的なアプリケーション開発にも利用できます。実際に触ってみることで、スキーマ設計や型の扱いにも慣れていき、より効率的にAPIを構築できるようになります。PHPで構築するGraphQL APIは、今後ますます需要が高まる分野でもあり、学んでおくことで開発の幅が大きく広がります。ぜひ、このまとめをきっかけに、さらに一歩進んだGraphQLの設計や応用にも挑戦してみてください。

GraphQLレスポンス形式の再確認サンプル

ここで改めて、GraphQLの基本的なレスポンスを読み解く練習として、簡単なPHPコード例を掲載します。実際の開発では、フロントエンド側からこのような形式でデータを受け取ることが多く、どのように値が返ってくるか理解しておくことが重要です。


<?php
// GraphQLのレスポンス例をPHPで出力するシンプルなコード

$response = [
    "data" => [
        "user" => [
            "name" => "Hanako",
            "age" => 30
        ]
    ]
];

header("Content-Type: application/json; charset=utf-8");
echo json_encode($response, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);
?>

このように、GraphQLでは「data」の中にクエリで指定した情報だけが返ってきます。REST APIとの違いを比較しながら学ぶと、より深く理解できるはずです。

先生と生徒の振り返り会話

生徒

「今日はPHPでGraphQL APIを作る方法を学びましたけど、最初は難しそうに感じていました。でも、スキーマとクエリとリゾルバの三つを押さえると意外と理解しやすかった気がします。」

先生

「そうですね。GraphQLは一見複雑に思えますが、考え方が整理されているので、構造を理解するとむしろ扱いやすいAPIになりますよ。必要なデータだけ取得できるという特徴は、特に大規模なアプリで重宝されます。」

生徒

「REST APIより自由にデータを組み合わせられるので、フロント側が欲しい情報をうまく指定できるところが便利ですね。今後はミューテーションにも挑戦してみたいです。」

先生

「それは良い目標ですね。GraphQLは応用範囲が広いので、一つの機能を理解するたびに開発の幅が広がります。今回学んだPHPでのGraphQL実装は、今後のAPI設計にも役立つはずですよ。」