Zenn
⚡

API Platformの始め方（非Symfonyユーザー向け丁寧バージョン）

2023/12/25に公開
PHP
Symfony
#
apiplatform
tech

メリークリスマス！🎅🎁

API Platform Advent Calendar 2023 の25日目の記事です！🎄✨

Twitter (X) でもちょいちょいAPI Platformネタを呟いてます！よろしければ フォロー お願いします！

こんな本も書いてます！よろしくお願いします！

https://zenn.dev/ttskch/books/a3800fc0912fbb

はじめに

勢いで作ってしまったAPI Platformアドベントカレンダー、作ったときは僕以外誰も書く人いないかな・・と思っていたんですが、最終的には僕以外にも何人かの方にご参加いただけて、とても嬉しかったです！

個人的にAPI Platformは好きで使い込んでいるので、また今後も折に触れて布教活動を頑張っていこうと思います！

今日は、もともとSymfonyユーザーでない方が初めてAPI Platformを使ってみようとなったときに、具体的にどうやってプロジェクトを開始すればよいかを丁寧めに解説してみます。

2種類のインストール方法

API Platformのインストール方法にいは以下の2種類があります。

API Platformの公式ドキュメントでは 方法1が推奨されています。

推奨されるとおり方法1で開発を開始すると、プロジェクトには初めから以下のものが含まれている状態になります。

  • API Platform Coreが導入されたSymfonyアプリケーション（バックエンドアプリケーション）の雛形
  • バックエンドアプリケーションを利用するフロントエンドアプリケーションの雛形を自動生成するためのツールのセットアップ
  • バックエンドアプリケーションを利用する管理画面としてのフロントエンドアプリケーションの実装
  • Mercureプロトコル を使用してバックエンドアプリケーションからフロントエンドアプリケーションへデータをプッシュできる構成
  • バックエンドアプリケーションとフロントエンドアプリケーションをまとめてホスティングするためのDocker定義
  • バックエンドアプリケーションとフロントエンドアプリケーションをKubernetesクラスターにデプロイするためのHelmチャート

しかし、これらのうち「Web APIを開発する」という目的のために本質的に必要なのは、1つ目の 「API Platform Coreが導入されたSymfonyアプリケーション（バックエンドアプリケーション）の雛形」だけ です。

なので、個人的には、特に入門時においては、方法2を強くお勧めします。 方法2はまさにこの1つ目だけを含むプロジェクトを作成する方法です。

公式の推奨は方法1ですが、正直、実務でWeb APIを開発する場面において、方法1が採用されるケースは現実的にはごく稀と言わざるを得ません。まず、方法1はSPAの開発を前提とした構成となっているので、それ以外の文脈では採用できません。SPAの開発においても、多くの場合、バックエンド、フロントエンド、サーバー環境などのインフラは、それぞれ独立した文脈を踏まえて技術選定がなされるので、初めからそれらがすべて渾然一体となっているような雛形を使いたいというケースは、実際にはほとんどないでしょう。

実際、僕自身も、これまでに多くの実務案件でAPI Platformを使用してきましたが、方法1を採用したことは一度もありません。

具体的なインストール手順

というわけで、この記事では、既存のSymfonyアプリケーションにAPI Platform Coreを導入する方法について解説することにします。

流れとしては以下のような感じになります。

  1. Symfonyアプリケーションの開発補助ツールである「Symfony CLI」をインストールする
  2. Symfony CLIを使って土台となるSymfonyアプリケーションの雛形を作る
  3. アプリケーションにAPI Platformを導入する

1. Symfony CLIのインストール

まずはSymfonyアプリケーションの開発補助ツールである Symfony CLI をインストールします。

Symfony CLIはSymfonyアプリケーションの開発に必須ではありませんが、様々な機能が備わっており非常に便利なツールなので、API Platformアプリケーション（⊆ Symfonyアプリケーション）を開発するなら絶対にインストールしておいたほうがいいです。

各種OSごとのSymfony CLIのインストール方法は下記の公式ドキュメントをご参照ください。

https://symfony.com/download

2. Symfonyアプリケーションの雛形の作成

次に、Symfony CLIを使って土台となるSymfonyアプリケーションの雛形を作成します。以下のコマンドを実行してください。

$ symfony new my-first-api-platform-app --version=7.0.*

Symfony CLIが提供する symfony new コマンドは、Symfonyの規約や標準に沿ったディレクトリ構成と最低限必要なファイル群を持つアプリケーションの雛形をカレントディレクトリ直下に作成するためのコマンドです。エラーなどが発生せずに上記のコマンドが実行完了すると、Symfonyのバージョン7.0を使用したアプリケーションの雛形が my-first-api-platform-app というディレクトリ配下に作成されます。

インストール直後の my-first-api-platform-app ディレクトリ内の構造は以下のようになっています。

$ cd my-first-api-platform-app
$ tree . -L 1
.
├── bin
├── composer.json
├── composer.lock
├── config
├── public
├── src
├── symfony.lock
├── var
└── vendor

my-first-api-platform-app ディレクトリ直下の各ディレクトリ・ファイルはそれぞれ以下のような役割となっています（Composer関連のディレクトリ・ファイルについては説明を割愛します）。

ディレクトリ・ファイル 役割
bin/ 中身は bin/console のみ。bin/console は、Symfonyアプリケーションに対してCLIから各種操作を行うためのコマンド
config/ Symfonyアプリケーションの各種設定ファイルが配置されるディレクトリ
public/ Webサーバーのドキュメントルートとして配信されるディレクトリ
src/ Symfonyアプリケーションの実装ソースコードを配置すべきディレクトリ
symfony.lock Symfonyに組み込まれている Symfony FlexというComposerプラグインによって利用される管理用ファイル
var/ Symfonyアプリケーションによってキャッシュやログなどの一時ファイルが出力されるディレクトリ

Symfony Flexについては以下の記事などをご参照ください。

https://zenn.dev/ttskch/articles/13013224b61531

3. API Platformのインストール

続けて、このSymfonyアプリケーションにAPI Platformを導入します。以下のコマンドを実行してください。

$ composer require api-platform/api-pack:^1.3

api-platform/api-pack は、API Platform Coreに加えて、SymfonyベースのAPI Platformアプリケーションを構築する上で最低限必要となるライブラリ群をまとめてインストールするためのメタパッケージです。

コマンドを実行してしばらくすると、以下のような質問が表示され、回答の入力待ち状態になります。

Do you want to include Docker configuration from recipes?
[y] Yes
[n] No
[p] Yes permanently, never ask again for this project
[x] No permanently, never ask again for this project
(defaults to y):

これは、アプリケーションにおいてデータベースを利用するにあたり、データベースサーバーを構築するためのDockerの設定を自動生成するかどうかを尋ねているものです。

今回は、Dockerを使わずにローカル環境のデータベースを使用する前提で手順を解説します。

この場合、尋ねられている自動生成は不要なので、n と入力してからEnterキーを押してください。

もし誤ってYesと回答してしまった場合は、コマンド実行完了後に以下の2つのファイルが余分に生成された状態となっているので、これらのファイルを手動で削除してください。

  • docker-compose.yaml
  • docker-compose.override.yaml

これで、Noと回答したのと同じ状態になります。

この時点で、プロジェクトルートディレクトリにある .env というファイルには、以下のような内容が記載されているはずです。

.env
###> doctrine/doctrine-bundle ###
# Format described at https://www.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/configuration.html#connecting-using-a-url
# IMPORTANT: You MUST configure your server version, either here or in config/packages/doctrine.yaml
#
# DATABASE_URL="sqlite:///%kernel.project_dir%/var/data.db"
# DATABASE_URL="mysql://app:!ChangeMe!@127.0.0.1:3306/app?serverVersion=8.0.32&charset=utf8mb4"
# DATABASE_URL="mysql://app:!ChangeMe!@127.0.0.1:3306/app?serverVersion=10.11.2-MariaDB&charset=utf8mb4"
DATABASE_URL="postgresql://app:!ChangeMe!@127.0.0.1:5432/app?serverVersion=15&charset=utf8"
###< doctrine/doctrine-bundle ###

これを参考に、以下のような内容でプロジェクトルートディレクトリに .env.local というファイルを作成してください。ただし、{ユーザー名} および {パスワード} の部分は、ご自身の環境においてデータベース作成権限を持っているユーザー（rootユーザーなど）のユーザー名とパスワードに置き換えてください。

.env.local
# PostgreSQLを使用する場合
DATABASE_URL="postgresql://{ユーザー名}:{パスワード}@127.0.0.1:5432/my_first_api_platform_app?serverVersion={PostgreSQLのバージョン番号}&charset=utf8"

# MySQLを使用する場合
DATABASE_URL="mysql://{ユーザー名}:{パスワード}@127.0.0.1:3306/my_first_api_platform_app?serverVersion={MySQLのバージョン番号}&charset=utf8mb4"

# SQLiteを使用する場合
DATABASE_URL="sqlite:///%kernel.project_dir%/var/data.db

これにより、アプリケーションがデータベースを利用できるようになります。

.env .env.local って？

.env.local は、Symfonyアプリケーションに環境変数をセットするためのファイルです。上記は DATABASE_URL という環境変数の値を定義しています。Symfonyアプリケーションは、プロジェクトルートディレクトリに配置されている .env や .env.local などのファイルを、環境変数設定ファイルとして自動で読み込みます。.env と .env.local の違いは、.env と .env.local に同じ環境変数が定義されている場合に .env.local が優先的に読み込まれるという点のみです。通常は、.env でデフォルト値を定義しておき、開発環境やステージング環境、本番環境など、環境ごとに異なる値で上書きしたい場合に、その環境で.env.local を作成し、目当ての環境変数だけを定義して上書きするという使い方をします。したがって、.env.local はGitなどのバージョン管理配下に置くべきではありません。

.env はSymfonyのインストール時に自動で生成されています。また、ライブラリのインストール時に .env に環境変数の定義が自動で追記されることもあります。DATABASE_URL は、api-platform/api-pack 経由でインストールされた doctrine/doctrine-bundle というライブラリがデータベースへの接続情報を得るために使用する環境変数です。.env にはすでにこの環境変数が一般的な値で定義されている状態になっていましたが、これは doctrine/doctrine-bundle がインストールされた際に自動で追記されたものです。開発環境においては実際にローカル環境で起動しているデータベースサーバーを使用する必要があるので、.env.local で適切な値に上書きしようというわけです。

さて、ここまでの手順で、API Platformを導入したSymfonyアプリケーションの雛形が完成しました。

動作確認

最後に、今回作成したAPI Platformアプリケーションの雛形を動作させてみましょう。以下のコマンドを実行してください。

$ symfony server:start

以下のような案内が表示されれば成功です。

 [OK] Web server listening
      The Web server is using PHP FPM 8.3.0
      http://127.0.0.1:8000

この表示は、Symfony CLIが提供するローカルWebサーバー機能によって、Symfonyアプリケーションが http://127.0.0.1:8000 というURLでホストされていることを意味しています。なお、すでに別のSymfonyアプリケーションが起動している場合は、URLのポート番号の部分が8000ではなく8001など別の番号になっているかもしれません。その場合は以降の解説を適宜読み替えてください。

ブラウザで http://127.0.0.1:8000 や http://localhost:8000 にアクセスしてみてください。以下のような画面が表示されれば成功です。

<img width="1024" alt="image.png (413.4 kB)" src="https://img.esa.io/uploads/production/attachments/15064/2023/12/18/77821/8703a065-c230-402a-aa64-a266a61ad321.png">

この画面は、Symfonyアプリケーションにまだルートパス（/）に対応するページが実装されていない場合に、開発環境においてのみ表示されるデフォルトのWelcomeページです。

次に、http://localhost:8000/api にアクセスしてみてください。以下のような画面が表示されれば成功です。

この画面は、API Platform Coreによって自動で生成された、Swagger UI製のAPIドキュメントページです。今後、API Platformの機能を使ってAPIを作成していくと、自動的にこの画面にAPIドキュメントが追加されていくことになります。

以上2つの画面が正常に表示されることが確認できれば、API Platformアプリケーションの雛形の動作確認は完了です🎉

おわりに

というわけで、もともとSymfonyユーザーでない方が初めてAPI Platformを使ってみようとなったときに、具体的にどうやってプロジェクトを開始すればよいかを丁寧めに解説してみました。

API Platformを始めようとする人の背中をちょっとでも押すことができたら嬉しいです。

GitHubで編集を提案

Discussion