Communitygithub.com

Crear DTO u Objeto de Datos

Una habilidad para guiar la creación de Data Transfer Objects (DTOs) robustos y reutilizables en Laravel, utilizando principalmente Spatie Laravel Data, ideal para arquitecturas limpias y separación de responsabilidades.

¿Qué es Crear DTO u Objeto de Datos?

Esta habilidad está diseñada para asistentes de codificación con IA (como Claude Code, Cursor, Codex o Gemini CLI) cuando el desarrollador necesita crear un DTO o un objeto de datos. Proporciona reglas claras sobre cuándo usar DTOs (cuando los datos cruzan un límite o son reutilizados por web, API, Livewire, trabajos, comandos o integraciones), qué entradas se requieren (campos, tipos, reglas de validación, límites de origen, consumidores de salida, valores predeterminados y necesidades de serialización), y cómo estructurarlos de manera segura. La habilidad recomienda usar `final readonly class` con promoción de propiedades en el constructor para inmutabilidad, aprovechar los atributos de Spatie Laravel Data (como `#[MapInputName]`, `#[WithCast]`, `#[ValidationAttribute]`, etc.), y mantener los DTOs agnósticos al cliente. Además, establece reglas arquitectónicas muy estrictas: los DTOs no deben depender de Livewire, Blade, controladores o respuestas, y deben evitar lógica de persistencia, autorización o flujo de trabajo. También incluye requisitos de prueba (campos requeridos, conversión de tipos, valores predeterminados, datos inválidos y serialización) y una checklist de revisión. Todo esto ayuda a mantener un código limpio, testeable y autocontenido, reduciendo el acoplamiento entre capas del sistema.

Compatible con✓Claude Code✓Codex CLI✓Cursor✓Gemini CLI
npx skills add AlizHarb/agent-skills

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace Crear DTO u Objeto de Datos?

Cuándo Usarlo

Usa esta habilidad cuando los datos crucen un límite o deban ser reutilizados por web, API, Livewire, trabajos, comandos o integraciones.

Entradas Requeridas

  • Campos, tipos, reglas de validación, límites de origen, consumidores de salida, valores predeterminados y necesidades de serialización.

Flujo de Trabajo

  1. Inspeccionar las convenciones existentes de objetos de datos.
  2. Usar Spatie Laravel Data por defecto ahora que está instalado. Si ya existe un estilo de datos diferente en un módulo cercano, seguir la convención local.
  3. Preferir final readonly class con promoción de propiedades en el constructor para DTOs inmutables.
  4. Usar atributos de Spatie Data donde se ajusten a la propiedad:
    • #[MapInputName]
    • #[MapOutputName]
    • #[WithCast]
    • #[WithTransformer]
    • #[Computed]
    • #[ValidationAttribute] o atributos de validación del paquete
    • #[DataCollectionOf]
    • #[Lazy]
    • #[Hidden]
    • #[LoadRelation] y #[LoadMissing]
    • #[Inject] o atributos de inyección de propiedades cuando el paquete o la convención del proyecto los use
  5. Usar enums para conjuntos cerrados y constantes de clase tipadas para contratos escalares reutilizables.
  6. Mantener los DTOs agnósticos al cliente.
  7. Agregar constructores nombrados como fromArray, fromRequest o fromModel solo cuando sea útil.
  8. Colocar las reglas de validación cerca de los DTOs cuando la convención del proyecto lo soporte.
  9. Evitar lógica de persistencia, autorización o flujo de trabajo.
  10. Agregar pruebas para construcción, reglas de validación, serialización y casos extremos.

Archivos que Pueden Crearse

  • app/Data/*.php, app/DTOs/*.php o el equivalente local existente.
  • Pruebas del DTO.

Archivos que Pueden Modificarse

  • Form Requests, Actions, Resources, componentes Livewire, controladores, trabajos y pruebas.

Reglas de Arquitectura

  • Los DTOs representan contratos de entrada o salida.
  • Los DTOs soportan reutilización en API y UI.
  • Los DTOs no deben depender de Livewire, Blade, controladores o respuestas.
  • Los DTOs deben usar tipado moderno de PHP en lugar de arreglos no estructurados cuando sea práctico.
  • Usar colecciones/recursos de Spatie Data cuando una característica necesite formas de datos anidadas, transformadas o reutilizables.
  • Preferir atributos de validación de Spatie Data antes que validación ad hoc con arreglos dentro de código reutilizable.

Requisitos de Prueba

  • Probar campos requeridos, conversión de tipos, valores predeterminados, datos inválidos y serialización si está expuesta.

Requisitos de Seguridad

  • No confiar en la construcción del DTO como autorización.
  • Evitar incluir campos sensibles en DTOs de salida a menos que sea explícitamente intencionado.

Lista de Verificación de Revisión

  • ¿El DTO es estable y agnóstico al cliente?
  • ¿Los campos están tipados?
  • ¿Las reglas de validación están lo suficientemente cerca para mantenerse sincronizadas?

Ejemplos

Buen Ejemplo

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,
    ) {}
}

Mal Ejemplo

// ❌ Mala seguridad de tipos, sin contexto de validación, difícil de reutilizar en trabajos en segundo plano.
class RegisterController extends Controller
{
    public function store(Request $request)
    {
        $this->action->handle($request->all());
    }
}

Skills relacionados