Laravelのresponse()->json()をもう少し理解する

## はじめに
Laravelでresponse()->json()を使用する場合、かなりシンプルすぎてjsonというものを扱っている気もしない。公式サイトを見てもシンプルすぎる。
シンプルな例を見ても単純すぎて応用が効かないので今一度考察がてら調査してみた。
２回に分けてまとめる
・今回は、まず整理し使用の仕方を把握する。
・次回は実際にソースを追ってみる。

以下実際にソースを追ってみた記事。

https://qiita.com/kenji123/items/792915191ce8c51ab47d

## 整理
### 公式サイト抜粋

jsonメソッドは自動的にContent-Typeヘッダをapplication/jsonにセットし、同時に指定された配列をjson_encode PHP関数によりJSONへ変換します。

```php
return response()->json([
    'name' => 'Abigail',
    'state' => 'CA',
]);
```

これでは例が少なすぎる！


### APIの例
バックエンドをAPIとして使用する場合、フロントエンド(Vue.js等)にJSON形式でデータでやり取りする例を見る。

前回、以下を記載した。

https://qiita.com/kenji123/items/6b72d412e1c60dd1f27e

上記は、web.phpを使用した記載であったが、api.phpを使用し、APIとして使用することにより、各処理が成功した場合や失敗した場合に、HTTPステータスコードと共にJSON形式でメッセージを返すように変更すると、以下のようになる。

```php
namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\DB;
use Illuminate\Database\QueryException;
use PDOException;
use Exception;
use App\Exceptions\FileExtensionException;
use App\Exceptions\CsvColumnMismatchException;

class MyController extends Controller
{
    public function handleRequest(Request $request)
    {
        try {
            $this->validateFileExtension($request);
            $this->validateCsvColumns($request);
            $this->handleTransaction($request);

            return response()->json([
                'status' => 'success',
                'message' => '操作が成功しました。'
            ], 200);

        } catch (FileExtensionException $e) {
            return response()->json([
                'status' => 'error',
                'message' => 'アップロードされたファイルはCSVではありません。'
            ], 400);

        } catch (CsvColumnMismatchException $e) {
            return response()->json([
                'status' => 'error',
                'message' => 'CSVのカラムが一致しません。'
            ], 400);

        } catch (PDOException $e) {
            return response()->json([
                'status' => 'error',
                'message' => 'データベースに接続できませんでした。'
            ], 500);

        } catch (QueryException $e) {
            return response()->json([
                'status' => 'error',
                'message' => 'データベースクエリに問題がありました。'
            ], 500);

        } catch (Exception $e) {
            \Log::error($e);
            return response()->json([
                'status' => 'error',
                'message' => 'データの操作中にエラーが発生しました。'
            ], 500);
        }
    }

    // その他のメソッドは変更なし
}


```
第一引数で、フロントに渡す配列をセット、第２引数でステータスコードをセットしている。

上記ではデータを渡していないが、データを渡す例を追加で記載する。
Laravelの response()->json() メソッドは、配列やオブジェクト（Eloquentのコレクションを含む）をJSON形式に自動的に変換してレスポンスとして返す。

たとえば、Eloquentモデルからデータを取得してJSONとして返す例を以下に示す。

```php
public function getData() {
    $data = MyModel::all(); // Eloquent Collection

    return response()->json($data, 200);
}
```
また、連想配列を用いることで、データとメタデータをメッセージで一緒に返すこともできる。
```php
public function getDataWithMetadata() {
    $data = MyModel::all(); // Eloquent Collection

    return response()->json([
        'status' => 'success',
        'message' => 'データの取得に成功しました。',
        'data' => $data
    ], 200);
}
```

簡潔にいうと、response()->json()は、第一引数でデータやメタデータをセット、第２引数でステータスを返す。

### 素のPHPでの実装と比較した理解
現状だと、いまいちAPIとフロントエンドの連携が見えない。
素のPHPで記載すると以下のようになる。
(例）
```php
<?php
// サンプルデータ
$data = [
    'code' => 200,
    'message' => 'Success',
    'results' => [
        'WCost' => 500
    ]
];

// HTTPステータスコード
http_response_code(200);

// レスポンスヘッダーの設定
header('Content-Type: application/json');
header('Access-Control-Allow-Origin: *'); // CORS対策（必要に応じて）

// レスポンスデータのエンコードと出力
echo json_encode($data, JSON_UNESCAPED_SLASHES);

```
（内容)
この例では以下の点を実装している：
`$data` 配列にレスポンスデータを設定。
`http_response_code()` 関数でHTTPステータスコードを設定。
`header()` 関数でレスポンスヘッダーを設定。
`json_encode()` 関数でレスポンスデータをJSON形式にエンコード。
`echo` でエンコードしたデータを出力。

(比較)
response()->json() メソッドはこれらの手順を抽象化してシンプルに呼び出せるようにしている。この背景を理解すると、Laravelの response()->json() が何をしているのかより明確になった。

## おわりに
今回はresponse()->json()の理解を深めることを行なった。
参考文献ではないが、主にChatgptを使用した。
次回はソースを追った例を記載する。