DTOまたはデータオブジェクトの作成
使用すべきタイミング
データが境界を越える場合、またはWeb、API、Livewire、ジョブ、コマンド、統合で再利用する必要がある場合にこのスキルを使用します。
必要な入力
- フィールド、型、バリデーションルール、ソース境界、出力コンシューマ、デフォルト値、シリアライゼーション要件。
ワークフロー
- 既存のデータオブジェクトの規約を確認します。
- デフォルトでは、Spatie Laravel Data(インストール済み)を使用します。近くのモジュールに異なるデータスタイルがすでに存在する場合は、ローカルの規約に従います。
- 不変DTOには、コンストラクタプロパティプロモーションを使用した
final readonly classを推奨します。 - プロパティに適したSpatie Data属性を使用します。
#[MapInputName]#[MapOutputName]#[WithCast]#[WithTransformer]#[Computed]#[ValidationAttribute]またはパッケージのバリデーション属性#[DataCollectionOf]#[Lazy]#[Hidden]#[LoadRelation]および#[LoadMissing]#[Inject]またはパッケージやプロジェクトの規約で使用する場合のプロパティインジェクション属性
- 閉じた集合には列挙型を、再利用可能なスカラー契約には型付きクラス定数を使用します。
- DTOをクライアントから独立させておきます。
fromArray、fromRequest、fromModelなどの名前付きコンストラクタは、有用な場合にのみ追加します。- プロジェクトの規約がサポートしている場合は、バリデーションルールをDTOの近くに配置します。
- 永続化、認可、ワークフローロジックは避けます。
- 構築、バリデーションルール、シリアライゼーション、エッジケースのテストを追加します。
作成される可能性のあるファイル
app/Data/*.php、app/DTOs/*.php、または既存のローカル同等のもの。- DTOテスト。
修正される可能性のあるファイル
- フォームリクエスト、アクション、リソース、Livewireコンポーネント、コントローラ、ジョブ、テスト。
アーキテクチャルール
- DTOは入力または出力の契約を表します。
- DTOはAPIとUIの両方での再利用をサポートします。
- DTOはLivewire、Blade、コントローラ、レスポンスに依存してはなりません。
- DTOは、実用的な場合は常に非構造化配列ではなく、最新のPHP型付けを使用する必要があります。
- ネスト、変換、または再利用可能なデータ形状が必要な機能には、Spatie Dataコレクション/リソースを使用します。
- 再利用可能なコード内でのアドホックな配列バリデーションよりも、Spatie Dataバリデーション属性を優先します。
テスト要件
- 必須フィールド、型変換、デフォルト値、無効なデータ、および公開されている場合はシリアライゼーションをテストします。
セキュリティ要件
- DTOの構築を認可として信頼しないでください。
- 明示的に意図されていない限り、機密フィールドを出力DTOに含めないでください。
レビューチェックリスト
- DTOは安定しており、クライアントから独立していますか?
- フィールドは型付けされていますか?
- バリデーションルールは十分に近くにあり、同期を維持できますか?
例
良い例
namespace App\Data;
use Spatie\LaravelData\Data;
use Spatie\LaravelData\Attributes\Validation\Email;
use Spatie\LaravelData\Attributes\Validation\Required;
use Spatie\LaravelData\Attributes\Validation\Max;
final readonly class RegisterUserData extends Data
{
public function __construct(
#[Required, Max(255)]
public string $name,
#[Required, Email]
public string $email,
) {}
}
悪い例
// ❌ 型安全性が低く、バリデーションコンテキストがなく、バックグラウンドジョブでの再利用が困難。
class RegisterController extends Controller
{
public function store(Request $request)
{
$this->action->handle($request->all());
}
}