Laravel で API サーバを実現する際の構成案

<?php

use MyApp\Exceptions\MyAppException;

//---------------------------------------------------
// ログには「コーヒーがリクエストされました」というメッセージとともに、そのサイズと種類を出力
// ユーザにはステータスコード 418 で「私はティーポットです。コーヒーは提供できません。」というメッセージを表示
// ---------------------------------------------------
throw new MyAppException(
    'コーヒーがリクエストされました',
    ['size' => 'tall', 'type' => 'espresso'],
    '私はティーポットです。コーヒーは提供できません。',
    418
);

エラー時の挙動カスタマイズ

エラー時の挙動のカスタマイズは主に \Base\Exceptions\Handler の report() および render() メソッドの書き換えによって行われる。

前者は

独自の例外に $context というプロパティを用意しておき、ログ出力時にメッセージ以外の情報を任意で与えられるようしたい

という要件を満たすためのものである。

こちらは副作用のある「ログ出力」に関する部分なので、書き換えの際に parent::report()を活用することができず、継承元のクラスの実装をそのまま持ってきてたうえで書き換える必要があった。

具体的には、以下に示した $additionalContext という変数に関する処理を追加している。

<?php

// 独自の例外から $context を取得
$additionalContext = [];
if ($e instanceof MyAppException) {
    $additionalContext = array_merge($additionalContext, $e->getContext());
}

$logger->error(
    $e->getMessage();
    array_merge($this->context(), $additionalContext, ['exception' => $e]); // array_merge() の引数に $additionalContext を追加
);

後者、 render() の書き換えは次の要件を満たすように行われている。

開発環境下では、先述の表明（assertion）のチェックを行いたい
一方で、開発環境下でのエラー発生時には、デバッグに役に立つ Laravel のエラー画面（Whoops）を出したい
- ただし、未認証・バリデーションエラー等のよるリダイレクトは発生させたくない
本番環境下では、いかなるエラーも JSON レスポンスとして返したい

これたを満たすために ini_set('assert.active', false) をするなど、少し気持ち悪い感じになってしまった。

なお、ここで独自の例外を HttpException に変換しているのは、自前で render() の処理を書くことなく既存の仕組みを利用することができるためである。

例として echo API を実装 + Http Test

コミット：Add echo api · okashoi/laravel5.6-sandbox@87283c4 · GitHub

コミット：Add Http test for echo api · okashoi/laravel5.6-sandbox@9c6964f · GitHub

ここまで構築したものが動くかどうかの確認のため、受け取った message をそのまま返す echo という API を実装。

基本的な書き方が変わるわけではないので、説明は割愛。

Http テストによって API が想定どおりの動作をしていることが確認できた。

$ docker-compose exec php-cli ./vendor/bin/phpunit
PHPUnit 7.2.6 by Sebastian Bergmann and contributors.
                                                                              
..                                                                  2 / 2 (100%)                                                                           
                                                            
Time: 1.87 seconds, Memory: 14.00MB                                                         
                                                                              
OK (2 tests, 4 assertions)

今後の展望

とりあえず、ここまでで基礎的な部分はできあがった。

あとは実際の用途に合わせて更なるカスタマイズをしていくことになる。

例えば

Laravel Passport を利用した認証機構
Eloquent ORM を設置している Model を Domain 層の Entity/ValueObject・Infrastructure 層の Repository/Eloquent等に分割

などが考えられる。

今回は Laravel から不要な機能を削っていくというアプローチだったが、逆に Lumen を使って必要な機能を選択・追加していく、というようなアプローチのほうが良かったりするのだろうか。

このあたりも気になるところ。

*1:実際にはアプリケーションの名前を使うイメージ

*2:設定に準ずる修正は行う

*3:けど、おそらく9割以上のプロジェクトで作成される

*4:API サーバ実現の検証が目的なので

*5:しかし「リクエストヘッダを書き換える」という操作はやっていいのだろうか？という疑問が残る

*6:php.ini の設定が必要

s平面の左側

左側なので安定してます（制御工学の話は出てきません）

Laravel で API サーバを実現する際の構成案

背景

リポジトリについて

解説

不要なファイル・ディレクトリを削除

名前空間の整理および WEB の無効化

必要なディレクトリを追加

レスポンスは JSON であることを表明

独自の例外を作成・エラー時の挙動カスタマイズ

独自の例外を作成

エラー時の挙動カスタマイズ

例として echo API を実装 + Http Test

今後の展望