Type-Safe de A à Z

Il est parfois fastidieux d'unifier les types de données échangés entre notre backend et notre frontend, pour répondre à cette contrainte le package typescript-transformer vous propose de partager les types des attributs de vos classes automatiquement.

Installation

Pour commencer, nous allons installer le package Laravel avec la commande :

1composer require spatie/laravel-typescript-transformer

Il est possible de publier le fichier de configuration avec la commande :

1php artisan vendor:publish --provider="Spatie\TypescriptTransformer\TypescriptTransformerServiceProvider" --tag="config"

Utilisation

Maintenant que tout est installé, comment cela fonctionne ?

Ce package va prendre du code PHP via un Collecteur, le modifier dans un Transformateur pour, au final, générer un fichier de déclaration TypeScript.

Pour que vos classes soient prises en compte par le collecteur, il suffit de typer les attributs d'une classe et de l'annoter avec @typescript pour qu'elle soit identifiée au moment de la compilation en exécutant la commande suivante :

1php artisan typescript:transform

⚠️ Il est probable qu'une erreur apparaisse au moment de la compilation si votre projet n'utilise pas SpatieEnumTransformer. Dans ce cas-là, il suffira de commenter ce dernier dans le fichier de configuration.

La classe suivante :

 1<?php
 2 
 3namespace App\Models;
 4 
 5use App\Enums\Seasons;
 6 
 7/** @typescript */
 8class UserData
 9{
10    public string $name;
11    public string $email;
12    public ?int $age;
13    public Seasons $birthSeason;
14 
15}

Ainsi que cette enum :

 1<?php
 2 
 3namespace App\Enums;
 4 
 5enum Seasons: string
 6{
 7    case SPRING = 'spring';
 8    case SUMMER = 'summer';
 9    case AUTUMN = 'fall';
10    case WINTER = 'winter';
11}

Seront transformés en :

 1declare namespace App.Enums {
 2    export type Seasons = "spring" | "summer" | "fall" | "winter";
 3}
 4declare namespace App.Models {
 5    export type UserData = {
 6        name: string;
 7        email: string;
 8        age: number | null;
 9        birthSeason: App.Enums.Seasons;
10    };
11}

Cette commande va générer un nouveau fichier de déclaration TypeScript generated.d.ts qui contiendra les types des données répertoriées par typescript transformer.

Pour utiliser ce résultat, il vous suffit d’appeler votre fichier de types comme suit :

 1export default function DisplayUser(user: App.Models.UserData) { 
 2 
 3    return (
 4        <>
 5            <p>Name: {user.email}</p>
 6            <p>Email: {user.name}</p>
 7            <p>Age: {user.age}</p>
 8            <p>Birth season: {user.birthSeason}</p>
 9        </>
10    );
11}

Vous remarquerez que, contrairement à la classe User, l'énumération Seasons n'a pas l'annotation @typescript. En effet, ce package dispose de différents collecteurs qui récupèrent automatiquement certains fichiers, dans ce cas les enums.

Conclusion

Le package vous permettra rapidement et simplement d’éviter des bugs liés aux différences de typage afin d'être complètement end-to-end typesafe.

La documentation vous expliquera des concepts plus poussés et vous permettra entre autres de créer vos propres transformer, writer, ou encore de caster différents types afin de s'ajuster précisément chacun de vos besoins.

Rémy Guillermic

Développeur full stack spécialisé dans l'écosystème de Laravel