Laravel実践入門! シンプルなREST APIを実装して学ぶ、多機能なPHPフレームワークの使い方

LaravelはPHPで実装されたオープンソースのWebアプリケーションフレームワークです。自由度が高く、幅広いニーズをサポートし、開発支援も充実し、多くのユーザに使われています。ここではサンプルアプリケーションとしてREST APIの実装を通して、Laravelを利用した開発を体験します。

Laravel実践入門! シンプルなREST APIを実装して学ぶ、多機能なPHPフレームワークの使い方

はじめまして。Webアプリケーション開発や技術サポートを行っている新原@shin1x1です。本記事では、これからLaravelを使ってみたい方を対象に、シンプルなREST APIの実装を通じて、Laravelを利用した開発のイメージを紹介します。フレームワークの詳細には触れていないので、実際の開発で必要な情報は公式マニュアルや書籍、ブログなどを参照してください。

Laravelの概要と特徴

Laravelは、PHPで実装されているオープンソースのWebアプリケーションフレームワークです。Taylor Otwell@taylorotwell氏を中心に、コミュニティによって開発されています。MITライセンスで公開されており、個人の非商用アプリケーションから企業による商用アプリケーションまで幅広く利用できます。

フルスタックフレームワークに分類されており、下記のようなWebアプリケーションで必要となる機能を豊富に持ちます。

  • ルーティング
  • HTTPリクエストハンドリング
  • バリデーション
  • ビューやJSONによるHTTPレスポンス生成
  • データストア(データベース、KVS、ファイルなど)アクセス
  • メール送信
  • データベースマイグレーション
  • テスト支援
  • 通知
  • キャッシュ
  • メッセージキュー連携
  • 外部API連携

PHPには、Laravel以外にも多くのフレームワークがあります。筆者もその中のいくつかを利用してきましたが、現在はLaravelをメインに利用しています。Laravelを利用していく中で筆者が感じる特徴には、下記のようなものがあります。

特徴1. 自由度が高い

Laravelは、アプリケーションに求める制約が少ないフレームワークです。アプリケーションコードディレクトリや名前空間は基本的には自由に変更できます。

また、他のフレームワークではコントローラにフレームワークのクラスを継承することが前提になっているものもありますが、LaravelではPOPO(Plain Old PHP Object)やクロージャで実装できます(Eloquentのように継承が前提のものもあります)

フレームワークのコンポーネントについてもサービスコンテナ(DIコンテナ)で構成されているので、必要があればユーザが任意のコンポーネントを実装して差し替えることも可能です。

こうした自由度の高さにより、ユーザが好むアーキテクチャを採用できるのは大きなメリットです。一般的なMVC(MVC2)だけでなく、レイヤードアーキテクチャやクリーンアーキテクチャといったいろいろな構造でLaravelを利用できます。

一方で、このような自由度の高さがゆえにプロジェクトによって構成が異なっていたり、そもそもどのような構成を取るのがよいかという判断をユーザに委ねられているという面があります。

これは、フレームワークに何を求めるかというスタンスの問題です。デフォルトの構成は用意されているので、アーキテクチャなどにこだわりがなければ、それをそのまま利用すればよいでしょう。ただ構造の変更や拡張が容易な分、独自な構成となっている場合があるということは覚えておきましょう。

特徴2. 幅広いニーズをサポート

PHPでWebアプリケーションを開発するユーザは、実に多様です。単にデータベースから値を取得して、HTMLを組み立てることだけを実現できればよい人もいるでしょう。OOPなどを駆使して、複雑なビジネスアプリケーションやWebサービスを開発している人もいます。また、同じユーザであっても、プロジェクトによって求められる内容は変わるでしょう。

Laravelでは、こうした多様なニーズを満たすようになっています。同じ機能でも、ファサードと呼ばれるクラスメソッド呼び出し、ヘルパー関数による簡便な呼び出し方法、そしてDIでコンポーネントをインジェクトして利用する方法が用意されています。内部的にはファサードやヘルパー関数も同じコンポーネントを利用するようになっているので、どちらでも実現できることは同じです。

簡潔なコードで実現したいときは簡単に、必要なコンポーネントを明確にしてフレームワークへの依存をコントロールしたい時はそのようにできるようになっており、ユーザやプロジェクトによって求められる方法でコンポーネントを利用できます。

一方、これには上述した自由度の高さと似通った面があり、同じプロジェクト内でもコードを書く人によってファサードを使ったり、DIを使ったりが分かれてしまう場合があります。もちろん現場ではコードレビューなどで方法を統一したりするなどを行うのですが、制御できない場合は実現方法が混在して混乱してしまうということがあります。

特徴3. 開発支援の充実

Laravelには、冒頭で記述したWebアプリケーションを実行するための機能だけでなく、開発支援の機能が充実しています。コード生成機能、データベースマイグレーションによるテーブルスキーマ管理やテスト(とくにファンクショナルテスト)のサポート、.envや環境変数による設定情報管理といったものは日常的な開発、運用において強力なサポートとなるでしょう。

他にもCLIアプリケーションを実装する機能を持っており、バッチ処理やワーカー処理、自動化ツールなどをこうした機能を用いて実装できます。

こうした開発支援の機能は、Laravel以外にオープンソースで公開されているものもあるので、そちらを利用することで同様のことは実現できます。ただ、フレームワークにはじめから同梱されているおかげで、ユーザはパッケージを探したり、連携方法を探ったりすることなく、すぐにこうした機能を利用できます。

多様な機能がオールインワンでインテグレートされているのも1つの特徴でしょう。

特徴4. ユーザが多い

これはLaravel自身の特徴というより、それを取り巻く環境の話ですが、ユーザが多いというのも1つの特徴です。GitHubのスター数は60,000を超えており、これはサーバーサイドのWebアプリケーションフレームワークとしては最多です(2020年9月時点)

多くのユーザがいるおかげで、多くのノウハウがインターネットや書籍で公開されています。また、Laravelで活用することを前提としたパッケージも多く存在するので、それらを利用することで効率的な開発が可能です。

Laravelのバージョンと選び方

現在(2020年9月時点)、Laravelは6、7、8の3つのバージョンをサポートしています。それぞれのリリースで、初期バージョンがリリースされた日から一定期間、バグフィックスやセキュリティフィックスがサポートされます。

Laravel 6はLTS(Long-term Support)と呼ばれるリリースで、長期間サポートされます。Laravel 8が最新のバージョンですが、これは通常のリリースです。それぞれのサポート期限は下表のとおりです。

バージョン リリース日 バグフィックス
サポート期限
セキュリティフィックス
サポート期限
6 (LTS) 2019年9月3日 2021年10月5日 2022年9月3日
7 2020年3月3日 2020年10月6日 2021年3月3日
8 2020年9月8日 2021年4月6日 2021年9月8日

これからLaravelを利用するのであれば、どのバージョンを使えばよいでしょうか?

現在(2020年9月時点)の状況であれば、6もしくは8のいずれかを選択することになります。どちらを選ぶかはアプリケーションの要件次第です。長期間安定したバージョンを利用したいのであれば6を、最新機能を利用していきたければ8を選ぶことになります。

この選択はさらに、セキュリティフィックス期限が切れた後にも影響します。例えば6を選択した場合、おそらく長期間利用することになるので、次にバージョンを上げる際は最新バージョンとの差異が大きくなり、アップグレードに手間がかかる可能性があります。

一方、8を選択して最新バージョンに適宜アップグレードしていけば、頻度は増えますが、都度の手間は小さくなります。ご自身やチームの開発状況や方針などを鑑みて、どちらを選ぶか検討してください。

なお、Laravelは6以降、セマンティックバージョニングを採用しているので、メジャーバージョンが変わらない限り、後方互換性が壊れることはありません。マイナーバージョンやパッチバージョンは頻繁に上がりますが、それについては基本的には最新バージョンを利用するとよいでしょう。

サンプル開発に必要な情報と環境の構築

ここから、サンプルアプリケーションの実装を通じて、Laravelを利用した開発を体験してみましょう。

近年のWebアプリケーション開発では、SPA(Single Page Application)やモバイルアプリケーションのように、ユーザが利用するUIはJavaScriptやスマートフォンアプリで実装して、PHPが担うサーバ側はAPIのみを提供するというケースが多くあります。本記事でも、WebのUIは実装せず、REST APIのみをLaravelで実装します。

なお、本記事で実装するソースコードは下記のリポジトリにあります。実装の手順を確認したり、動作イメージを知りたい場合などに活用してください。

https://github.com/shin1x1/eh-laravel-sample

必要なシステム構成

本記事のサンプルアプリケーションを動作させるには、下記のシステム構成を必要とします。

  • PHP:バージョン7.3以降
  • Webサーバ:nginx
  • データベースサーバ:PostgreSQL

ここでは、この構成をDockerを利用して構築します。Dockerはコンテナ技術を利用して、ホストマシン(PC)の中に仮想的な実行環境を構築できます。本記事では詳細には触れませんが、開発現場ではDockerを利用した開発環境の構築が一般的になりつつあります。

PHP自体もDockerコンテナのものを利用するので、PCにPHPをインストールする必要はありません。もしPCにインストールされているPHPのバージョンが古くても問題ありません。

REST APIクライアントツール

REST APIを実装するにあたって、動作確認を行うツールが必要です。本記事では実行例として、curlコマンドを利用します。

また、GUIのREST APIクライアントツールもいくつか公開されているので、必要であればそちらを利用してください。主なGUIツールには以下のようなものがあります。

Docker Desktopのインストール

Dockerを利用するため、Docker Desktopをインストールします。すでにDockerが利用できる環境をお持ちの方は不要です。

Docker Desktop overview | Docker Documentation

MacもしくはWindows版がありますので、ご利用の環境に合わせてダウンロード、インストールしてください。本記事ではMac環境を想定していますが、Windows環境でも基本的な流れは同じです。

Docker Desktopがインストールできたら、ターミナルを開いてdocker --versionコマンドを入力してください。下記のようにDockerのバージョンが表示されればインストールが成功しています。バージョン番号やbuildの後ろの値はインストールを行ったタイミングによって変わっている可能性はあります。

$ docker --version
Docker version 19.03.12, build 48a66213fe

サンプルアプリケーションを実行するには、PHP(php-fpm)、nginx、PostgreSQLという3つのDockerコンテナを利用するので、それらを統合して管理できるようにdocker-composeを利用します。このコマンドはDocker Desktopに同梱されているので、下記のようにdocker-composeコマンドも実行できるか確認しておきます。

$ docker-compose version
docker-compose version 1.26.2, build eefe0d31
docker-py version: 4.2.2
CPython version: 3.7.7
OpenSSL version: OpenSSL 1.1.1g  21 Apr 2020

Laravelプロジェクトの作成

サンプルアプリケーションを実装するため、Laravelプロジェクトを生成します。

ComposerのDockerコンテナが公開されているので、これを利用して次のようにcomposer create-projectコマンドを実行します。

$ docker run --rm -v `pwd`:/opt -w /opt composer:1.10 create-project laravel/laravel todoApp

コマンドを実行すると、新しいLaravelプロジェクトがtodoAppディレクトリに生成されます。todoAppディレクトリの内容を確認すると、プロジェクトのディレクトリやファイルが生成されていることが分かります。

$ tree -L 1 todoApp
todoApp
├── README.md
├── app
├── artisan
├── bootstrap
├── composer.json
├── composer.lock
├── config
├── database
├── package.json
├── phpunit.xml
├── public
├── resources
├── routes
├── server.php
├── storage
├── tests
├── vendor
└── webpack.mix.js

なお、本記事執筆時は最新版であるLaravel 8のプロジェクトが生成されますが、下記のようにバージョンを指定することで任意のバージョンのプロジェクトを生成することもできます。

# Laravel 6 プロジェクトを生成
$ docker run --rm -v `pwd`:/opt -w /opt composer:1.10 create-project "laravel/laravel=^6.0" todoApp6

docker-compose.ymlのダウンロード

docker-composeで環境構築するため、構成ファイルであるdocker-compose.ymlを下記URLからダウンロードして、todoAppディレクトリに設置してください。

https://raw.githubusercontent.com/shin1x1/eh-laravel-sample/master/docker-compose.yml

$ cd todoApp
$ wget https://raw.githubusercontent.com/shin1x1/eh-laravel-sample/master/docker-compose.yml
$ ls docker-compose.yml
docker-compose.yml

このdocker-compose.ymlには、以下のコンテナが含まれています。

  • nginx:HTTPサーバ(nginx 1.18)
  • php:PHP(php-fpm 7.4)
  • db:データベース(PostgreSQL 12)
  • db-test:テスト用データベース(PostgreSQL 12)
  • composer:Composer

Laravelを実行するためのコンテナをdocker-compose upコマンドで起動します。初回はコンテナのダウンロードを伴うので時間がかかります。

$ docker-compose up -d
Creating network "todoapp_default" with the default driver
Creating todoapp_composer_1 ... done
Creating todoapp_db_1       ... done
Creating todoapp_db-test_1  ... done
Creating todoapp_php_1      ... done
Creating todoapp_nginx_1    ... done

コンテナが起動できれば、Laravelの動作環境が整いました。

ブラウザでhttp://localhost:8000にアクセスすると、下記のようにLaravelの初期画面が表示されます。

laravel-startup

起動中のDockerコンテナを終了・破棄する場合は、docker-compose downコマンドを実行します。

$ docker-compose down
Stopping eh-laravel-sample_nginx_1   ... done
Stopping eh-laravel-sample_php_1     ... done
Stopping eh-laravel-sample_db-test_1 ... done
Stopping eh-laravel-sample_db_1      ... done
Removing eh-laravel-sample_nginx_1    ... done
Removing eh-laravel-sample_php_1      ... done
Removing eh-laravel-sample_composer_1 ... done
Removing eh-laravel-sample_db-test_1  ... done
Removing eh-laravel-sample_db_1       ... done
Removing network eh-laravel-sample_default

サンプル1. Hello APIの実装

Laravelの開発環境が整ったので、下記のようなJSONを返すだけのシンプルなAPIを実装してみましょう。

  • GET /api/hello
    • レスポンス
      • ステータスコード: 200
      • ボディ: {"message": "Hello"}

APIを実装するには、URIパスに対応する処理をルーティングに登録します。ルーティングはroutesディレクトリ以下のファイルに記述します。APIはroutes/api.phpが対象となります。このファイルに下記のコードを追加します。

routes/api.php

Route::get('/hello', function () {
    $message = 'Hello';

    return response()->json([
        'message' => $message
    ]);
});

Route::get()では、GETリクエストに対するルーティングを設定します。第一引数にはURIパスを指定します。プレフィックスの/apiはフレームワークのデフォルト設定で指定されているので、ここでは/helloのみとします。第二引数には処理を行うハンドラを指定します。ハンドラには、クロージャやクラス、クラスのメソッドなどが指定できます。上記ではクロージャを指定しています。

ハンドラの戻り値がHTTPレスポンスとなるので、ここではresponse()->json()を指定してJSON形式のレスポンスを返すようにしています。json()の引数ではレスポンスボディとなるJSONの内容を記述します。上記では、messageキーに対してHelloという文字列を返すようになっています。

これでAPIが実装できました。curlコマンドで/api/helloにGETリクエストを送信すると、HelloがJSONで返ってきます。

$ curl http://localhost:8000/api/hello
{"message":"Hello"}

Hello APIのテストを実装

Laravelには、テストを支援する仕組みがあります。これを利用して、Hello APIのテストを実装してみましょう。

テストは、testsディレクトリ以下に配置します。testsディレクトリ以下には、FeatureディレクトリとUnitディレクトリがあります。前者はAPIのような機能テスト、後者はクラスやメソッドなどの単体テストを配置します。ここでは、APIのテストを記述するのでFeatureディレクトリを利用します。

デフォルトではtests/Featureディレクトリとtests/Unitディレクトリにサンプル用のテストファイルが含まれています。これらは開発には不要なので削除しておきます。

$ rm tests/Feature/ExampleTest.php tests/Unit/ExampleTest.php

テストクラスはartisan make:testコマンドで雛形を生成できます。下記のようにコマンドの後ろにテストクラスのクラス名を指定して実行します。

$ docker-compose exec php ./artisan make:test GetHelloTest
Test created successfully.

生成したテストクラスはtests/Feature/GetHelloTest.phpになります。このファイルにHello APIのテストコードを追加したのが、下記のコードです。

tests/Feature/GetHelloTest.php

<?php

namespace Tests\Feature;

use Tests\TestCase;

class GetHelloTest extends TestCase
{
    public function testExample()
    {
        $response = $this->get('/api/hello');

        $response->assertStatus(200);
        $response->assertJson([
            'message' => 'Hello',
        ]);
    }
}

ここでは、/api/helloにGETリクエストを送信して、そのレスポンスとしてステータスコードが200であること、JSONの内容がmessageキーにHelloという文字列が入っていることを確認しています。

LaravelアプリケーションのテストではPHPUnitを利用しているので、phpunitコマンドでテストが実行できます。下記のように実行するとテストが通過し、想定どおりにHello APIが動いていることが確認できます。

$ docker-compose exec php ./vendor/bin/phpunit
PHPUnit 9.3.8 by Sebastian Bergmann and contributors.

.                                                                   1 / 1 (100%)

Time: 00:01.300, Memory: 18.00 MB

OK (1 test, 2 assertions)

ここまで、Laravelに新しいAPIを追加して、テストで動作を確認するという流れを見てきました。次は、これをベースにTo-DoアプリのAPIを実装していきましょう。

サンプル2. To-DoアプリケーションAPI

エンジニアHubに会員登録すると
続きをお読みいただけます(無料)。
登録のメリット
  • すべての過去記事を読める
  • 過去のウェビナー動画を
    視聴できる
  • 企業やエージェントから
    スカウトが届く