O que Criar DTO ou Objeto de Dados faz?
Quando Usar
Use esta habilidade quando dados cruzarem uma fronteira ou precisarem ser reutilizados por web, API, Livewire, jobs, comandos ou integrações.
Entradas Necessárias
- Campos, tipos, regras de validação, limites de origem, consumidores de saída, valores padrão e necessidades de serialização.
Fluxo de Trabalho
- Inspecione as convenções existentes de objetos de dados.
- Use Spatie Laravel Data por padrão, agora que está instalado. Se um estilo diferente de dados já existir em um módulo próximo, siga a convenção local.
- Prefira
final readonly classcom promotion de propriedades do construtor para DTOs imutáveis. - Use atributos do Spatie Data onde eles se encaixam na propriedade:
#[MapInputName]#[MapOutputName]#[WithCast]#[WithTransformer]#[Computed]#[ValidationAttribute]ou atributos de validação do pacote#[DataCollectionOf]#[Lazy]#[Hidden]#[LoadRelation]e#[LoadMissing]#[Inject]ou atributos de injeção de propriedade quando o pacote ou a convenção do projeto os utiliza
- Use enums para conjuntos fechados e constantes de classe tipadas para contratos escalares reutilizáveis.
- Mantenha os DTOs agnósticos ao cliente.
- Adicione construtores nomeados como
fromArray,fromRequestoufromModelapenas quando forem úteis. - Coloque regras de validação próximas aos DTOs quando a convenção do projeto suportar.
- Evite lógica de persistência, autorização ou fluxo de trabalho.
- Adicione testes para construção, regras de validação, serialização e casos de borda.
Arquivos Que Podem Ser Criados
app/Data/*.php,app/DTOs/*.phpou o equivalente local existente.- Testes para DTOs.
Arquivos Que Podem Ser Modificados
- Form Requests, Actions, Resources, componentes Livewire, controllers, jobs e testes.
Regras de Arquitetura
- DTOs representam contratos de entrada ou saída.
- DTOs suportam reúso em API e UI.
- DTOs não devem depender de Livewire, Blade, controllers ou respostas.
- DTOs devem usar tipagem moderna do PHP em vez de arrays não estruturados sempre que prático.
- Use coleções/recursos do Spatie Data quando um recurso precisar de formas de dados aninhadas, transformadas ou reutilizáveis.
- Prefira atributos de validação do Spatie Data em vez de validação de array ad hoc dentro de código reutilizável.
Requisitos de Teste
- Teste campos obrigatórios, conversão de tipos, valores padrão, dados inválidos e serialização se exposta.
Requisitos de Segurança
- Não confie na construção do DTO como autorização.
- Evite incluir campos sensíveis em DTOs de saída, a menos que seja explicitamente intencionado.
Checklist de Revisão
- O DTO é estável e agnóstico ao cliente?
- Os campos são tipados?
- As regras de validação estão próximas o suficiente para permanecerem sincronizadas?
Exemplos
Bom Exemplo
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,
) {}
}
Mau Exemplo
// ❌ Pouca segurança de tipos, sem contexto de validação, difícil de reutilizar em jobs em segundo plano.
class RegisterController extends Controller
{
public function store(Request $request)
{
$this->action->handle($request->all());
}
}