Créer un DTO ou Objet de Données
Quand l'utiliser
Utilisez cette compétence lorsque des données franchissent une frontière ou doivent être réutilisées par le web, l'API, Livewire, les jobs, les commandes ou les intégrations.
Entrées nécessaires
- Champs, types, règles de validation, frontières de source, consommateurs de sortie, valeurs par défaut et besoins de sérialisation.
Workflow
- Inspectez les conventions existantes des objets de données.
- Utilisez Spatie Laravel Data par défaut maintenant qu'il est installé. Si un style de données différent existe déjà dans un module voisin, suivez la convention locale.
- Préférez
final readonly classavec promotion de propriété de constructeur pour les DTOs immuables. - Utilisez les attributs Spatie Data là où ils correspondent à la propriété :
#[MapInputName]#[MapOutputName]#[WithCast]#[WithTransformer]#[Computed]#[ValidationAttribute]ou les attributs de validation du package#[DataCollectionOf]#[Lazy]#[Hidden]#[LoadRelation]et#[LoadMissing]#[Inject]ou les attributs d'injection de propriété lorsque le package ou la convention du projet les utilise.
- Utilisez des enums pour les ensembles fermés et des constantes de classe typées pour les contrats scalaires réutilisables.
- Gardez les DTOs indépendants du client.
- Ajoutez des constructeurs nommés comme
fromArray,fromRequestoufromModeluniquement lorsque c'est utile. - Placez les règles de validation près des DTOs lorsque la convention du projet le permet.
- Évitez la persistance, l'autorisation ou la logique de workflow.
- Ajoutez des tests pour la construction, les règles de validation, la sérialisation et les cas limites.
Fichiers pouvant être créés
app/Data/*.php,app/DTOs/*.php, ou l'équivalent local existant.- Tests DTO.
Fichiers pouvant être modifiés
- Formulaires de requête, Actions, Ressources, composants Livewire, contrôleurs, jobs et tests.
Règles d'architecture
- Les DTOs représentent des contrats d'entrée ou de sortie.
- Les DTOs prennent en charge la réutilisation par l'API et l'interface utilisateur.
- Les DTOs ne doivent pas dépendre de Livewire, Blade, des contrôleurs ou des réponses.
- Les DTOs doivent utiliser le typage PHP moderne plutôt que des tableaux non structurés lorsque cela est pratique.
- Utilisez les collections/ressources Spatie Data lorsqu'une fonctionnalité nécessite des formes de données imbriquées, transformées ou réutilisables.
- Privilégiez les attributs de validation Spatie Data avant la validation ad hoc de tableaux dans du code réutilisable.
Exigences de test
- Testez les champs obligatoires, la conversion de types, les valeurs par défaut, les données invalides et la sérialisation si elle est exposée.
Exigences de sécurité
- Ne faites pas confiance à la construction de DTO comme autorisation.
- Évitez d'inclure des champs sensibles dans les DTOs de sortie, sauf si cela est explicitement voulu.
Liste de vérification de révision
- Le DTO est-il stable et indépendant du client ?
- Les champs sont-ils typés ?
- Les règles de validation sont-elles suffisamment proches pour rester synchronisées ?
Exemples
Bon exemple
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,
) {}
}
Mauvais exemple
// ❌ Mauvaise sécurité de typage, pas de contexte de validation, difficile à réutiliser dans les jobs d'arrière-plan.
class RegisterController extends Controller
{
public function store(Request $request)
{
$this->action->handle($request->all());
}
}