README

Bundle Symfony qui génère les définitions TypeScript (.ts) de vos entités et DTO à partir de ce que le Symfony Serializer expose réellement : groupes de sérialisation, noms sérialisés, custom normalizers, relations Doctrine et, en option, JMS Serializer.

Le front consomme ainsi des types toujours alignés sur l'API, sans les écrire à la main.

Fonctionnalités

Groupes de sérialisation : seules les propriétés des groupes demandés (#[Groups(['user:read'])]) sont générées, jamais les autres.
Plusieurs projets : chaque projet a son dossier de sortie (assets/ts/types, public/ts/types…) et sa liste de types.
interface, class ou type au choix, par type (option kind).
Quatre modes d'extraction : runtime (vrai normalize(), custom normalizers compris), static (métadonnées, sans exécuter de code), jms et auto. Voir Modes d'extraction.
Objet réel en exemple : avec sample_id, le mode runtime normalise une vraie entité plutôt qu'un objet vide, et déduit des valeurs le type des champs non typés (custom normalizers, getters sans type). Voir Normaliser un objet réel.
Typage riche : génériques PHPDoc (Collection<int, Tag>, array<Tag>, Tag[]), array shapes, alias @phpstan-type, enums, dates, unions. Voir Correspondance des types.
Relations Doctrine : OneToMany / ManyToMany en Array<Target>, ManyToOne / OneToOne nullables selon le JoinColumn.
Références entre types : imports relatifs, génération automatique des dépendances (auto_generate_deps) ou description inline récursive. Voir Références et imports.

Compatibilité

PHP : 8.2 et supérieur (8.4+ pour Symfony 8).
Symfony : 7.4 (LTS) et 8.1+, les branches encore maintenues.
Optionnel : doctrine/orm (relations), jms/serializer-bundle (mode jms), phpstan/phpdoc-parser (génériques PHPDoc résolus par PropertyInfo).

Installation

composer require --dev codifyo/ts-generator-bundle

Si Symfony Flex n'enregistre pas le bundle, ajoutez-le dans config/bundles.php :

return [
    // ...
    Codifyo\TsGeneratorBundle\CodifyoTsGeneratorBundle::class => ['dev' => true],
];

Le bundle s'appuie sur les services serializer et property_info de FrameworkBundle : le serializer doit être activé (framework.serializer.enabled: true, activé par défaut avec symfony/serializer).

Démarrage rapide

config/packages/dev/codifyo_ts_generator.yaml :

codifyo_ts_generator:
    projects:
        frontend:
            dir: 'assets/ts/types'
            types:
                - class: 'App\Entity\User'
                  groups: ['user:read']
                  auto_generate_deps: true

php bin/console codifyo:ts-generator:generate

Toutes les options sont décrites dans Configuration.

Exemple

namespace App\Entity;

use Doctrine\Common\Collections\Collection;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Serializer\Attribute\Groups;

class User
{
    #[Groups(['user:read'])]
    private int $id;

    #[Groups(['user:read'])]
    private string $username;

    #[Groups(['user:read'])]
    private ?string $email = null;

    #[Groups(['admin'])]
    private string $password;

    /**
     * @var Collection<int, Role>
     */
    #[Groups(['user:read'])]
    #[ORM\ManyToMany(targetEntity: Role::class)]
    private Collection $roles;

    #[Groups(['user:read'])]
    public function getFullName(): string
    {
        return $this->firstName . ' ' . $this->lastName;
    }
}

assets/ts/types/User.ts :

/* tslint:disable */
/* eslint-disable */
// Auto-generated by CodifyoTsGeneratorBundle. Do not edit manually.

import { Role } from './Role';

export interface User {
  id: number;
  username: string;
  email?: string | null;
  roles: Array<Role>;
  fullName: string;
}

password (groupe admin) n'apparaît pas, et Role.ts est généré à côté grâce à auto_generate_deps.

Documentation

Configuration : référence complète des options et de la commande.
Modes d'extraction : auto, runtime, static, jms et l'ordre de résolution des types.
Correspondance des types : règles de conversion PHP → TypeScript, nullabilité, Doctrine.
Références et imports : dépendances générées, types inline, collisions de noms.
Dépannage : erreurs fréquentes et leurs solutions.

Développement

composer test     # PHPUnit
composer phpstan  # analyse statique (niveau 6)
composer cs       # vérification du style (PHP-CS-Fixer) ; composer cs-fix pour corriger

La CI GitHub Actions exécute ces vérifications sur Symfony 7.4 (dépendances minimales et maximales), 8.1 et 8.x.

Licence

Ce bundle est distribué sous la licence MIT.

codifyo / ts-generator-bundle

Package info

Security

Statistics