Laravel-Data入門：実案件で感じたメリット・デメリット

1. はじめに

みなさん、Laravelで開発を進める中で、

「FormRequestのバリデーションルールがどんどん増えて見通しが悪い…」

「RequestとAPI Resourceで、結局同じようなプロパティを何度も定義している…」

「配列でデータを扱っていて、どんなキーが存在するのか分かりにくい！」

といった悩みを抱えたことはありませんか？

これらの課題をスマートに解決してくれるのが、Spatie製の強力なDTO（Data Transfer Object）パッケージlaravel-dataです！

本記事では、laravel-dataの基本的な役割を解説し、さらに実案件で活用して感じたリアルなメリット・デメリットを共有します！

2. laravel-dataとは？

https://github.com/spatie/laravel-data

laravel-dataは、アプリケーション内でやり取りされるデータを、一貫性のある構造化されたオブジェクト（DTO）として扱うためのパッケージです。

従来の開発では、リクエストの入力値やデータベースから取得した値などを、連想配列のまま扱っていませんでしたか？

laravel-dataは、それらのバラバラなデータを入れるための、型安全な「専用の箱」を用意するようなものです。

この「専用の箱（Dataオブジェクト）」は、単にデータを持つだけでなく、自分自身のバリデーション方法を知っており、APIレスポンスとして最適な形に自動で変身することもできます。

これにより、データの入り口（Request）から出口（Response）まで、一貫したオブジェクトで安全にデータを扱うことが可能になります。

3. laravel-dataの主要な役割

laravel-dataは、Laravel標準のいくつかの機能を、よりモダンで集約された形に置き換えます。

• DTO (Data Transfer Object) リクエスト、モデル、配列など、様々なデータソースから型安全なオブジェクトを簡単に作成できます。これにより、メソッドの引数などで型宣言が使えるようになり、コードの信頼性が向上します。
• FormRequestの代替 Dataオブジェクト内に直接バリデーションルールを定義できます。これにより、FormRequestクラスを別途作成する必要がなくなり、データ定義とバリデーションロジックを1箇所に集約できます。
• API Resourceの代替 Dataオブジェクトをコントローラから直接返却すると、自動的にJSON形式に変換されます。これにより、API Resourceクラスを作成する手間を省きつつ、レスポンスの形式をコントロールできます。

4. データフローで理解するlaravel-dataの役割

典型的な「リクエストを受け取り、JSONを返す」APIの処理の流れで、laravel-dataがどのように機能するかを見てみましょう。

1. UI層 (Controller): リクエストの入り口

コントローラのメソッドの引数で、作成したPostDataのようにDataオブジェクトを型宣言します。 laravel-dataが裏側でリクエスト内容からPostDataオブジェクトを生成し、同時に定義されたバリデーションルールを実行します。この時点でFormRequestの役割は完了です。

// PostDataクラスがリクエストのバリデーションとDTOへの変換を自動で行う
public function store(PostData $postData)
{
    // ...
}

2. ビジネスロジック層 (Service / Action)

コントローラから、バリデーション済みの$postDataオブジェクトをサービス層に渡します。 サービス層では、$postData->title のようにプロパティに安全にアクセスでき、IDEの補完も効くため開発体験が向上します。もう配列のキーを気にする必要はありません。

3. UI層 (Controller): レスポンスの出口

処理結果をPostDataオブジェクト（またはそのCollection）のままコントローラから返します。 laravel-dataが自動でオブジェクトをJSONにシリアライズしてくれるため、API Resourceを介さずに、整形されたAPIレスポンスを返すことができます。

public function show(Post $post)
{
    // EloquentモデルからDataオブジェクトを生成し、そのまま返す
    return PostData::from($post);
}

5. 実案件で感じたメリット

• 責務の集約による圧倒的な見通しの良さ
  • これまでFormRequest、API Resource、そして時にはDTOクラスと、複数に分散しがちだったデータ定義、バリデーション、レスポンス整形の責務が、Dataクラス1つに集約されます。関連するコードが1ファイルにまとまるため、仕様変更時の修正箇所が明確になり、保守性が劇的に向上しました。
• 静的解析との相性抜群で、コードが堅牢になる
  • 全てのデータが型定義されたオブジェクトになるため、PHPStanなどの静的解析ツールとの相性が最高です。配列のキー間違いのような単純なミスが開発段階で検知できるため、コードの品質と堅牢性が格段に上がります。
• 柔軟かつ強力なデータ変換機能
  • ネストしたDTOや、特定の日付フォーマットを自動でCarbonインスタンスに変換するCast機能、プロパティ名を変えるMap機能など、かゆいところに手が届くデータ変換機能が非常に強力です。これにより、データソースの形を気にすることなく、アプリケーション内部では常に理想的なデータ構造を保つことができます。

6. 考慮すべきデメリットと注意点

• 学習コストと「Spatie流」への慣れ
  • Laravel標準のFormRequestやAPI Resourceとは異なる設計思想のため、導入には一定の学習コストがかかります。特に、laravel-data独自のデータ生成パイプラインや高度な機能を使いこなすには、公式ドキュメントの読み込みが必須です。
• ファイル数の増加と冗長感
  • Portoと同様に、シンプルなCRUD機能であっても必ずDataクラスを作成することになります。「リクエストをそのまま保存するだけ」のような単純な処理では、少しだけファイルが増え、お作法感が気になるかもしれません。

    • Laravel開発の実案件でPortoアーキテクチャを使用してみて感じたこと

• 小規模なプロジェクトには過剰になる可能性
  • Bladeビューがメインの伝統的なWebアプリケーションや、APIが数本しかないような小規模プロジェクトの場合、FormRequestとAPI Resourceで十分なケースも多いです。導入のメリットが、規約を学ぶコストを上回るかどうかの見極めは必要です。

7. 結論：私たちのプロジェクトはlaravel-dataを採用すべきか？

laravel-dataが向いているプロジェクト

• APIを多用する、フロントエンド分離型のアプリケーション（SPA, モバイルアプリなど）
• 長期的に運用・拡張が見込まれる、中〜大規模サービス
• 複雑なデータ構造や、外部APIとの連携が多い
• チーム開発でコードの品質と一貫性を高く保ちたい

laravel-dataが向いていないプロジェクト

• Bladeがメインの小規模なWebサイト
• プロトタイピングなど、開発スピードが最優先されるフェーズ
• チームメンバーがLaravelの基本機能にまだ慣れていない段階

8. おわりに

laravel-dataは、Laravelにおけるデータの取り扱いを、より安全で、見通しが良く、そして開発者フレンドリーにしてくれる非常に強力なパッケージです。

特にAPI開発においては、FormRequestとAPI Resourceの乱立によるコードの重複や分散といった課題を劇的に改善してくれます。プロジェクトの特性を見極めた上で、ぜひ導入を検討してみてはいかがでしょうか。