Comment se fait une feature, stack par stack

Les guidelines de dev-standards, montrées en code : la séquence complète d'une feature, les patterns du moment, et les pièges.

Twig rend les pages, React prend la main là où il faut de l'interaction. PHP est la source de vérité, les types TS en descendent. symfony-react/symfony-guidelines.md et reactony.md

La séquence du playbook, dans l'ordre : le contrat backend, la route, les types générés, le composant, le cache, les tests, la porte qualité.

1symfony-guidelines.md, Playbook 1 · reactony.md §2

Modéliser le contrat backend

PHP est la source de vérité. Les types et la validation vivent sur l'entité, et tout le reste en découle.

src/Entity/AlerteRecherche.phpphp

<?php

class AlerteRecherche
{
    #[ORM\Id]
    #[ORM\GeneratedValue(strategy: 'IDENTITY')]
    #[ORM\Column]
    private ?int $id = null;  // privé et sans Groups : le Serializer l'ignore

    #[Assert\NotBlank]
    #[Assert\Count(min: 1)]
    #[Groups(['alerte:read', 'alerte:create'])]
    public array $canaux = [];

    #[Assert\Email]
    #[Groups(['alerte:create'])]
    public ?string $email = null;
}

2symfony-guidelines.md §3 · Playbook 2

La route du contrôleur

format: 'json' est obligatoire, #[IsGranted] aussi. Le contrôleur oriente : Domain décide, Service exécute.

src/Controller/AlerteController.phpphp

<?php

/** @return array<int, AlerteRecherche> */
#[IsGranted('ROLE_USER')]
#[Route('/api/alertes', methods: ['POST'], format: 'json')]
#[Serialize(code: 201, context: ['groups' => ['alerte:read']])]
public function create(
    #[MapRequestPayload] AlerteRecherche $alerte,
): AlerteRecherche {
    // CRUD simple : l'EntityManager directement dans le contrôleur.
    $this->entityManager->persist($alerte);
    $this->entityManager->flush();

    return $alerte;
}

3symfony-guidelines.md, Playbook 3 · reactony.md §5

La génération de types

Une commande, et le contrat PHP devient des types TS, du Zod, un SDK et les queryOptions. Rien n'est écrit à la main de ce côté.

Makefilemake

types:
	php -d memory_limit=512M bin/console nelmio:apidoc:dump --format=yaml > openapi.yaml
	pnpm openapi-ts

# En CI, la porte de dérive :
#   make types && git diff --exit-code openapi.yaml assets/lib/api/

3 bisreactony.md §5

La configuration hey-api

Cinq plugins, tous embarqués dans le même paquet. Le pin exact est demandé par les mainteneurs : le projet est en pre-1.0.

openapi-ts.config.tstypescript

import { defineConfig } from "@hey-api/openapi-ts";

export default defineConfig({
  input: "./openapi.yaml",
  output: "assets/lib/api",
  plugins: [
    "@hey-api/typescript",
    "@hey-api/client-fetch",
    { name: "@hey-api/sdk", validator: { response: "zod" } },
    "zod",
    "@tanstack/react-query", // nom du plugin embarque, pas un paquet npm
  ],
});

// pnpm add -D -E @hey-api/openapi-ts

4reactony.md §4 · §3

Le composant React

Un seul patron de formulaire : Controller de RHF, la famille Field de shadcn, le Zod généré, useMutation. Le 422 revient champ par champ.

assets/components/alerte-form.tsxtsx

import { zodResolver } from "@hookform/resolvers/zod";
import { useMutation } from "@tanstack/react-query";
import { Controller, useForm } from "react-hook-form";

import { postAlerte } from "@/lib/api";
import { zAlerteRecherche } from "@/lib/api/zod.gen"; // généré
import { handleSdkError } from "@/lib/parseViolations";

type FormValues = z.infer<typeof zAlerteRecherche>;

const form = useForm<FormValues>({
  resolver: zodResolver(zAlerteRecherche),
  defaultValues: { canaux: [], email: "" },
});

const mutation = useMutation({
  mutationFn: async (values: FormValues) => {
    const resultat = await postAlerte({ body: values });
    const erreurs = handleSdkError(resultat);
    if (erreurs) {
      Object.entries(erreurs).forEach(([champ, message]) =>
        form.setError(champ as any, { message }),
      );
      throw new Error("Validation failed");
    }
  },
});

<Controller
  name="canaux"
  control={form.control}
  render={({ field, fieldState }) => (
    <Field data-invalid={fieldState.invalid}>
      <FieldLabel htmlFor={field.name}>Canaux</FieldLabel>
      <Input id={field.name} aria-invalid={fieldState.invalid} {...field} />
      {fieldState.invalid && <FieldError errors={[fieldState.error]} />}
    </Field>
  )}
/>;

4 bisreactony.md §4

Action simple, édition en ligne

Un seul champ, un toggle, un date picker : RHF est de trop. useMutation, le SDK, handleSdkError, un toast.

tsx

import { toast } from "sonner";

const mutation = useMutation({
  mutationFn: async (donnees: { id: string; valeur: string }) => {
    const resultat = await postFieldUpdate({ body: donnees });
    const erreurs = handleSdkError(resultat);
    if (erreurs) throw new Error(Object.values(erreurs)[0]);
  },
  onSuccess: () => toast.success("Enregistre"),
  onError: (erreur: Error) => toast.error(erreur.message),
});

5reactony.md §4 · Playbook 5

Invalider le cache

Toute mutation qui change une donnée lue ailleurs invalide, dans son onSuccess, avec les mêmes queryOptions générées.

tsx

import { getAlerteListOptions } from "@/lib/api";

const queryClient = useQueryClient();

const mutation = useMutation({
  mutationFn: postAlerte,
  onSuccess: () =>
    queryClient.invalidateQueries({ ...getAlerteListOptions({ query: filtres }) }),
});

6symfony-guidelines.md, Playbook 6 · §13

Les tests dus

Ce qu'une nouvelle route et un nouveau parcours doivent, par rendement décroissant.

tests/Functional/AlerteControllerTest.phpphp

<?php

public function testCreationAlerte(): void
{
    $client = static::createClient();
    $client->loginUser(UserFactory::createOne()->_real());

    // Le contrat HTTP.
    $client->jsonRequest('POST', '/api/alertes', ['canaux' => ['email']]);
    self::assertResponseStatusCodeSame(201);

    // Et l'état en base : les deux, pas l'un ou l'autre.
    AlerteRechercheFactory::assert()->count(1);
}

// Fonctionnel PHPUnit pour toute nouvelle route /api/ non triviale.
// Unitaire sans mocks pour le Domain pur, Foundry pour construire les entités.
// Vitest + RTL + MSW pour les 422 d'un formulaire React.
// Playwright pour chaque nouveau parcours utilisateur.

7symfony-guidelines.md, Definition of Done

Definition of Done

La feature est finie quand toutes ces lignes sont vertes.

markdown

- [ ] /quality passe : PHPStan niveau 9+, PHP-CS-Fixer, ESLint, Prettier, `tsc --noEmit`
- [ ] `make types` ne produit aucune dérive dans `assets/lib/api/`
- [ ] `doctrine:schema:validate --skip-sync` OK
- [ ] `lint:container` OK
- [ ] Un test fonctionnel par nouvelle route /api/ non triviale
- [ ] Un test basé sur les propriétés (Eris) sur tout nouveau calcul d'argent
- [ ] Un spec Playwright par nouveau parcours utilisateur
- [ ] /live-test joue : chemin nominal plus un cas limite, console et réseau propres
- [ ] `#[IsGranted]` et `format: 'json'` présents sur les nouvelles routes /api/

1 / 9