Dev Playbook

1

Modéliser le contrat backend

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

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/SearchAlert.phpphp

<?php

class SearchAlert
{
    #[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(['search_alert:read', 'search_alert:create'])]
    public array $channels = [];

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

1 bis

Le schéma suit l'entité

symfony-guidelines.md, Playbook 1, §19

Pas de migration écrite à la main : le hook de déploiement applique le schéma. On relit donc le SQL qu'il va jouer avant de commiter.

shell

# Le SQL que le déploiement va jouer, à lire avant de commiter :
php bin/console doctrine:schema:update --dump-sql

# Et le mapping reste cohérent avec la base :
php bin/console doctrine:schema:validate --skip-sync

2

La route du contrôleur

symfony-guidelines.md §3, Playbook 2

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

src/Controller/SearchAlertController.phpphp

<?php

#[IsGranted('ROLE_USER')]
#[Route('/api/search-alerts', methods: ['POST'], format: 'json')]
#[Serialize(code: 201, context: ['groups' => ['search_alert:read']])]
public function create(
    #[MapRequestPayload] SearchAlert $searchAlert,
): SearchAlert {
    // CRUD simple : l'EntityManager directement dans le contrôleur.
    $this->entityManager->persist($searchAlert);
    $this->entityManager->flush();

    return $searchAlert;
}

2 bis

La règle métier vit dans Domain

symfony-guidelines.md, Principes, §2, §15

Dès qu'il y a une décision (un seuil, une éligibilité, un calcul), elle sort du contrôleur. Domain décide sans rien connaître d'extérieur, Service exécute, le contrôleur relie les deux.

src/Domain/SearchAlert/SearchAlertRules.phpphp

<?php

final class SearchAlertRules
{
    private const MAX_ALERTS_PER_USER = 10;

    public function canCreate(int $existingAlerts): bool
    {
        return $existingAlerts < self::MAX_ALERTS_PER_USER;
    }
}

// Dans le contrôleur : le Domain décide, puis on exécute.
$count = $this->searchAlertRepository->countFor($this->getUser());

if (!$this->rules->canCreate($count)) {
    throw new UnprocessableEntityHttpException("Nombre maximal d'alertes atteint.");
}

3

La génération de types

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

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 bis

Ce que la commande a écrit pour vous

reactony.md §5

Une commande, et tout le contrat backend existe en TypeScript : les types, les schémas Zod, une fonction par endpoint, les options TanStack Query. Ce dossier se consomme, il ne s'écrit pas.

assets/lib/api/typescript

// Écrit par `make types`, commité, jamais édité à la main :
//
//   assets/lib/api/
//     types.gen.ts   les types du contrat, un par schéma OpenAPI
//     zod.gen.ts     les schémas Zod, tirés des contraintes #[Assert] du PHP
//     sdk.gen.ts     une fonction typée par endpoint, multipart compris
//     ...            les queryOptions et mutationOptions du plugin TanStack Query

import { getSearchAlertListOptions, postSearchAlert } from "@/lib/api";
import { zSearchAlert } from "@/lib/api/zod.gen";

// Lire : les options générées portent déjà la queryKey et le queryFn.
const { data } = useQuery({ ...getSearchAlertListOptions({ query: filters }) });

// Valider : le schéma descend des contraintes PHP, il ne se réécrit pas ici.
const form = useForm({ resolver: zodResolver(zSearchAlert) });

// Écrire : une fonction par endpoint, typée sur le corps attendu.
await postSearchAlert({ body: values });

4

Le montage dans la page Twig

symfony-guidelines.md, Playbook 4, reactony.md §6

Twig rend la page, React ne prend que l'îlot interactif. Les données initiales descendent en props, sérialisées avec les mêmes groupes que l'API.

templates/search_alert/index.html.twigtwig

{% extends 'base.html.twig' %}

{% block body %}
    <div {{ react_component('SearchAlertForm', {
        farm: farm|serialize('json', { groups: ['farm:read'] }),
    }) }}></div>
{% endblock %}

{# assets/react/controllers/SearchAlertForm.tsx :
   export default function (props) {
     return <AppProviders><SearchAlertForm {...props} /></AppProviders>;
   } #}

5

Le composant React

reactony.md §4, §3

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/search-alert-form.tsxtsx

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

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

type FormValues = z.infer<typeof zSearchAlert>;

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

const mutation = useMutation({
  mutationFn: async (values: FormValues) => {
    const result = await postSearchAlert({ body: values });
    const errors = handleSdkError(result);
    if (errors) {
      // Les champs dans l'ordre de l'écran : le premier fautif prend le focus.
      const first = FIELD_ORDER.find((name) => name in errors);
      Object.entries(errors).forEach(([field, message]) =>
        form.setError(field as any, { message }, { shouldFocus: field === first }),
      );
      throw new Error("Validation failed");
    }
  },
});

<Controller
  name="channels"
  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>
  )}
/>;

5 bis

Action simple, édition en ligne

reactony.md §4

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

tsx

import { toast } from "sonner";

import { handleSdkError, sdkErrorMessage } from "@/lib/parseViolations";

const mutation = useMutation({
  mutationFn: async (data: { id: string; value: string }) => {
    const result = await postFieldUpdate({ body: data });
    const errors = handleSdkError(result);
    if (errors) throw new Error(Object.values(errors)[0]);
  },
  onSuccess: () => toast.success("Enregistré"),
  onError: (error: Error) => toast.error(sdkErrorMessage(error)),
});

6

Invalider le cache

reactony.md §4, Playbook 5

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

tsx

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

const queryClient = useQueryClient();

const mutation = useMutation({
  mutationFn: postSearchAlert,
  onSuccess: () =>
    queryClient.invalidateQueries({ ...getSearchAlertListOptions({ query: filters }) }),
});

7

Les tests dus

symfony-guidelines.md, Playbook 6, §13

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

tests/Functional/SearchAlertControllerTest.phpphp

<?php

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

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

    // Et l'état en base : les deux, pas l'un ou l'autre.
    SearchAlertFactory::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.

8

Definition of Done

symfony-guidelines.md, 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 ci-local` passe sur la branche fusionnée avec main
- [ ] `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/
- [ ] Aucun anti-pattern de la liste : `useEffect` + fetch, `$request->get()`, `new RetryableHttpClient`, `any` hors du `setError` de RHF

Comment se fait une feature, stack par stack