laravel-dto

laravel-dto

When to use

Use this skill when creating a new DTO for data transfer between layers (DB ↔ PHP, API ↔ Service, etc.).

Procedure: Create a DTO

1. Read the project's DTO docs — check agents/reference/docs/dto.md (if it exists) for project-specific conventions.
2. Check the base class — search for the DTO base class in the project (e.g., SimpleDto, LiteDto, or a custom base). Check composer.json for DTO-related packages.
3. Check existing DTOs — look at neighboring DTOs in the same directory to match the style.
4. Understand the model — if the DTO maps to a Model, read the model's properties and DB columns.

DTO conventions

Base class

• Use the project's standard DTO base class (typically SimpleDto or LiteDto).
• Never create plain PHP classes for DTOs that map to models — always extend the base class.

Property mapping

• Use #[Map('db_column')] attributes to map between DB column names and PHP properties.
• PHP properties: camelCase, English names.
• DB columns: snake_case, may be German (legacy) — match what's in the database.

Type casting

• Use typed properties (int, string, float, bool, Carbon, etc.).
• The base class handles casting from DB strings to PHP types automatically.

Validation

• Use validation attributes where appropriate: #[Length(50)], #[Email], #[Decimal(10,2)], #[Unsigned].
• Add #[ConvertEmptyToNull] at class level if empty strings should become null.

Model linkage

• Add #[HasModel(ModelClass::class)] on the DTO.
• Add #[HasDto(DtoClass::class)] and DtoMappingTrait on the Model (if not already present).

Structure

<?php

declare(strict_types=1);

namespace App\DTO;

use Vendor\DataHelpers\SimpleDto;
use Vendor\DataHelpers\SimpleDto\Attributes\HasModel;
use Vendor\DataHelpers\SimpleDto\Attributes\Map;

#[HasModel(MyModel::class)]
class MyModelDto extends SimpleDto
{
    #[Map('id_column')]
    public ?int $id = null;

    #[Map('name_column')]
    public string $name = '';

    #[Map('amount_column')]
    public float $amount = 0.0;
}