Laravel

LaravelでAPI開発する手順

普段のプロジェクトでLaravelでApi作成しています。
ということで、私なりのApi作成時の流れを書いていきたいと思います。

まず最初に全体の流れをまとめておくとこのようになります。

  1. テーブル定義を作成する
  2. マイグレーションファイルの作成
  3. migrationファイルを編集し実行する
  4. コントローラーとモデルを作成する
  5. routeとコントローラーを接続する

以下ではそれぞれの手順を解説していきます。
あくまでも私個人でのやり方ではありますが、まだLaravelに触れて全体的な流れがわからないという場合には参考になると思い、書いてみました。

テーブル定義を作成する

まずは想定する使われ方に対して合わせたテーブルを考え、テーブル定義を作成します。

今回はサンプルとして社員を管理するようなテーブルを考えてみます。

staffテーブル定義

id:自動増分で一意の値を持ったキー(主キー)

name:氏名

hurigana:ふりがな

マイグレーションファイルの作成

このテーブルを作成するとした場合、まずLaravelでマイグレーションファイルを作成します。
作成するにはLaravelのプロジェクトルートで、以下のコマンドを実行します。

php artisan make:migration create_staffs_table

すると「database/migrations」にマイグレーションファイルが作成されます。
今回作成した「create_staffs_table.php」ができているのが確認できるかと思います。
最初についているのは作成日時です。

2014...,2019...というファイルは元々Laravelによって作成されています。
不要であると判断できるのであれば削除してOKですが、ここでは残しておきます。

「php artisan make:migration」はLaravelのコマンドで、最後にファイル名をつけます。
一つのマイグレーションファイルでどこまで書くかは各自のルールによりますが、基本的には1ファイルに1内容にしておくのがわかりやすいかと思います。

今回はテーブルを作成するので「create_staffs_table」としています。

注意

php artisan make:migration foldername/tablename

上記のようなコマンドでディレクトリを切るような形で記述できますが、この形では書かずサンプルのように1ファイルとして書くようにして下さい。

後で使用するmigrateコマンドを実行してもサブディレクトリは実行されません。

migrationファイルを編集し実行する

作成された「2023_10_24_055133_create_staffs_table.php」を編集していきます。
やることを簡単に書くと以下になります。

  • 実行時に行うことを「up」に記述
  • 戻すときに実行することを「down」に記述

自動で生成されるコードは以下のようになっています。

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    /**
     * Run the migrations.
     */
    public function up(): void
    {
        Schema::create('staffs', function (Blueprint $table) {
            $table->id();
            $table->timestamps();
        });
    }

    /**
     * Reverse the migrations.
     */
    public function down(): void
    {
        Schema::dropIfExists('staffs');
    }
};

実行時に行うことを「up」に記述

まずはマイグレーションを実行するときに行う処理を「up」の中に書いていきます。

作成フィールドはid,name,huriganaの3つなので以下のようになります。

    public function up(): void
    {
        Schema::create('staffs', function (Blueprint $table) {
            $table->id()->autoincrement();
            $table->string('name',50);
            $table->string('hurigana');

            $table->timestamps();

            $table->index('hurigana');
            $table->index(['name','hurigana']);

            $table->unique(['hurigana','name']);
        });
    }

autoincrement

自動増分のフィールドを作成できます。
私の場合は、基本的に全てのテーブルに「id」という名前でidを決めており、必ず作成するフィールドとしています。

string('フィールド名',文字数指定)

string()で書いてあるのがテキストフィールドを作成してくれます。
第二引数に数値を入力することで文字数制約を追加できます。

timestamps

timestamps()を書くと「created_at」「updated_at」を自動生成してくれます。
Laravelが自動で更新してくれるフィールドなので、全テーブルで書きます。

index

テーブルにインデックスを追加したい場合に使用します。

先ほどの例では「hurigana」だけのインデックスと、「name,hurigana」のインデックスを作成しました。
必要な数だけ追加可能なので、

unique

$table->unique(['hurigana','name']);この部分でユニークキー制約を追加できます。

その他の設定可能内容

ここまではよく使用するものについて書きました。
他にも設定項目はあるので、その他の部分はLaravel公式サイトを見て、随時使用してみて下さい。

Laravel公式:migrations

戻すときに実行することを「down」に記述

Laravelのmigrationは「php artisan migrate:rollback」というコマンドを使用することで元に戻すことができます。

そのときに実行される内容をマイグレーションファイル内の「down」の中に書いていきます。
基本的にはupで行うことの反対の処理を書いていきます。

今回はテーブル作成ですので、テーブル削除を書いていきます。
具体的にはサンプルコードにあるようなります。

    public function down(): void
    {
        Schema::dropIfExists('staffs');
    }

「staffsテーブルがあれば削除する」というシンプルなものになります。

仮にフィールドを追加するマイグレーションの時であれば「フィールドを削除する」というものになりますので、その際は以下のように記述します。

$table->dropColumn('email');

マイグレーションの実行

Laravelのプロジェクトルートにいき、以下のコマンドを実行します。

php artisan migrate

これを実行すると、実行されていないmigrationファイルが「全て」実行されます。
テスト的に指定ファイルのみを実行したい場合は以下のように実行します。

php artisan migrate --path=/database/migrations/2023_10_24_055133_create_staffs_table.php

「--path」のオプションで実行するファイルを指定してあげれば、特定のマイグレーションファイルのみ実行することができます。

ここまでデーターベースに新規テーブルの作成が完了します。
次は実際にLaravel側のプログラムを書いていきます。

コントローラーとモデルを作成する

まず簡単にコントローラーとモデルについて説明すると以下のようになります。

  • モデル:テーブルをプログラミングで描きやすいようにラップしたもの。
  • コントローラー:実際にどのように情報処理するかを書いたもの

マイグレーションすることで、実態であるテーブルを作成しました。
それを実際に扱っていくものがコントローラーとモデルになります、まずはコントローラーとモデルを作成します。

プロジェクトルートに戻って以下のコマンドを実行します。

php artisan make:controller Staff/StaffController --api --model=App/Models/Staff/Staff

すると以下のように表示されると思います。

Yesを押せばOKです。

すると以下二つのファイルが作成されます。
それぞれを詳しく書いていくことでApiが完成していきます。

  • App/Http/Controllers/Staff/StaffController.php
  • App/Models/Staff/Staff.php

make:controller コマンドについて

今回説明しているコマンドには典型的なApi向けのものに適した内容になっています。
デフォルトとは違うオプションが入っているので、基本からオプションについて解説します。

php artisan make:controller StaffController

Laravelの公式リファレンスなどに載っている基本的な書き方は上記となります。

これはシンプルにコントローラーを作成するコマンドとなっていて、必要最低限のみの内容でコントローラーが作成されます。
実際にこのコマンドで作成した場合の内容を見てみます。

class StaffController extends Controller
{
    //
}

中身が何もないコントローラーが作成されるので、全て自分で記述する場合はこれで書くので良いかと思います。

先ほど指定したコマンドで作成した場合のコントローラーの内容はこのようになります。
「一覧取得」「個別取得」「登録」「更新」「削除」それぞれのメソッドが自動で作成されています。

class StaffController extends Controller
{
    /**
     * Display a listing of the resource.
     */
    public function index()
    {
        //
    }

    /**
     * Store a newly created resource in storage.
     */
    public function store(Request $request)
    {
        //
    }

    /**
     * Display the specified resource.
     */
    public function show(Staff $staff)
    {
        //
    }

    /**
     * Update the specified resource in storage.
     */
    public function update(Request $request, Staff $staff)
    {
        //
    }

    /**
     * Remove the specified resource from storage.
     */
    public function destroy(Staff $staff)
    {
        //
    }
}

make:controllerの書き方、オプションがあるので、どれが正解というのはないですが、個人的にはこの書き方をメインで書いています。

作成フォルダの指定

php artisan make:controller Staff/StaffController

先ほどのコマンドと違うのが「Staff/StaffController」です。

最初に「Staff/」でディレクトリを指定しています。

特に指定がない場合は「App/Http/Controllers」直下に作成されますが、ディレクトリを指定してあげることでController配下でディレクトリを作成してコントローラーを配置してくれます。

オプション：--api

「--api」というオプションを指定しておくと、api用のrouteとmethodを用意してくれます。

オプション:--model=モデルまでのpath

コントローラーと紐付けするモデルを指定できます。

指定したモデルと作成するコントローラーを紐付けすることを明示しておくことで、自動で紐付けされたApi用のコントローラーが作成されます。
また、指定したモデルがない場合は作成するかの確認をしてくれます。

自分でモデルを作成するコマンドを実行しても良いのですが、わざわざしなくてもできるのでオプションでモデルを作成しています。

routeとコントローラーを接続する

コントローラーまで作成したら、アクセスされるURLとコントローラーを接続します。
使用するのはこちらのファイルです。

routes/api.php

route/api.phpはApi用にあるルート用のファイルです。
Laravelの公開ルートフォルダが「http://localhost」とした場合に「api.php」は以下のURLとなります。

http://localhost/api/指定ルート

では実際の手順を見ていきます。
早速サンプルを書くとこのようになります。

Route::apiResources([
  'staff' => App\Http\Controllers\Staff\StaffController::class,
]);

こんのように書くことで以下のrouteが作成されることになります。

MethodAPI URLコントローラー
GETStaffController@index
GET/{id}StaffController@show
POSTStaffController@store
PUT/PATCH/{id}StaffController@update
DELETE/{id}StaffController@destroy
※API URLは前部分にhttp://localhost/api/がつきます
※{id}の部分にはテーブルを一意にするID番号が入ります。(デフォルトではidカラム)

1行で5つのルートに対してできているのは「apiResources」のおかげです。
仮に全てを自分で書くとなると以下のようになります。

Route::get('/staff', [App\Http\Controllers\Staff\StaffController::class, 'index']);
Route::get('/staff', [App\Http\Controllers\Staff\StaffController::class, 'show']);
Route::post('/staff', [App\Http\Controllers\Staff\StaffController::class, 'store']);
Route::put('/staff', [App\Http\Controllers\Staff\StaffController::class, 'update']);
Route::delete('/staff', [App\Http\Controllers\Staff\StaffController::class, 'destroy']);

どちらの書き方も一長一短あるのですが、個人的にapi用のrouteを作成する場合はapiResourceで書くようにしています。

LaravelでApiを作成するときの流れ まとめ

ここまで読んでいただきありがとうございます。

個人的な開発方法ではありますが、Api開発時の全体的な流れについて書いてみました。
どの方法が正しいというのはありませんが、これから初めてApi開発をしてみようという方向けに書いてみました。

もし詳しい方が読んでくださって、もっと良い方法があるよ！と言った意見をくださる方はぜひ、コメントに書いていただければと思います！

-Laravel
-,