😶‍🌫️ This person does not exist - PHP synchrone à l'orchestration asynchrone avec Flow

le 13 juin 2026

Vous devez télécharger dix images depuis une API distante. Entre chaque requête, vous attendez une seconde pour respecter un rate limit. Chaque image suit le même chemin : fetch, hash, sauvegarde, reporting.

Le code ressemble à une boucle for familière. Il fonctionne. Mais pendant qu'une image télécharge, les neuf autres attendent. Pendant qu'une fibre dort sur un sleep(), tout le processus est figé. Les unités de travail sont indépendantes — seule l'orchestration les traite comme si elles ne l'étaient pas.

C'est le problème concret que nous avons isolé dans le projet flow-thispersondoesnotexist : une commande Symfony minimale qui récupère plusieurs images depuis ThisPersonDoesNotExist et les sauvegarde sur disque.

L'objectif n'était pas de télécharger des images plus rapidement.

L'objectif était de comprendre comment faire évoluer une exécution séquentielle vers une orchestration asynchrone avec darkwood/flow — sans changer la logique métier, en changeant le modèle d'exécution.

La transition se résume en deux commits :

• fae47e8 — commande app:fetch-thispersondoesnotexist, boucle synchrone
• c61c929 — même commande, orchestrée par Flow et FiberDriver

Un seul fichier change entre les deux : src/Command/FetchThisPersonDoesNotExistCommand.php.

Le point de départ : une boucle synchrone

La première version (fae47e8) utilise une boucle for classique. Fetch, hash, sauvegarde et reporting sont exécutés inline ; un sleep(1) bloque le processus entre chaque téléchargement :

$savedFiles = [];

for ($index = 1; $index <= $count; ++$index) {
    if ($count > 1) {
        $this->io->section(sprintf('Download %d/%d', $index, $count));
    }

    try {
        $image = $this->fetchImage();
        $checksum = $this->computeChecksum($image);
        $filename = $this->generateFilename($checksum, $file);
        $outputPath = $this->saveFile($filename, $image);
        $this->report($outputPath, $checksum, \strlen($image));
    } catch (\RuntimeException $exception) {
        $this->io->error($exception->getMessage());

        return Command::FAILURE;
    }

    $savedFiles[] = $outputPath;

    if ($index < $count) {
        $this->io->note(sprintf('Waiting %d second(s) before next download...', self::DOWNLOAD_DELAY_SECONDS));
        sleep(self::DOWNLOAD_DELAY_SECONDS);
    }
}

Le fonctionnement est linéaire : télécharger, traiter, attendre, passer à l'image suivante. Chaque étape bloque entièrement le processus — y compris le sleep(), qui immobilise le programme même quand aucun travail utile n'est en cours.

Cette approche est facile à comprendre, mais elle gaspille les temps d'attente I/O : tant qu'une image n'est pas terminée, aucune autre ne peut avancer.

À noter : la version synchrone conservait aussi une méthode alternative fetchImageViaFileGetContents(). Elle sera supprimée dans la version Flow — les streams explicites (fopen) sont préférés pour la suite.

Observer le workflow caché

Derrière la boucle se cache un pipeline répété pour chaque image :

Fetch Image → Save Image → Report Result

Image #1 : Fetch → Save → Report
Image #2 : Fetch → Save → Report
Image #3 : Fetch → Save → Report

Chaque image est une unité de travail autonome. La question devient alors : pourquoi attendre la fin complète de l'image #1 avant de démarrer l'image #2 ?

Avant / Après : le changement architectural

Avant l'introduction de Flow, l'exécution est strictement séquentielle :

Image 1 → Fetch → Save → Sleep
Image 2 → Fetch → Save → Sleep
Image 3 → Fetch → Save → Sleep

Après, les unités de travail sont planifiées indépendamment et traversent un pipeline commun :

Image 1 ─┐
Image 2 ─┼─> Flow Pipeline (Fetch → Save + Report) ─> résultats
Image 3 ─┘

Le for ne pilote plus l'exécution étape par étape. Il enqueue des Ip (unités de travail). Flow orchestre leur passage dans le pipeline ; await() synchronise à la fin.

Introduire Flow

La dépendance darkwood/flow est ajoutée au projet avant la commande (e71899a). La version c61c929 l'utilise enfin pour orchestrer le travail.

Les imports introduits :

use Flow\Driver\FiberDriver;
use Flow\ExceptionInterface;
use Flow\FlowFactory;
use Flow\Ip;

Chaque image devient une unité de travail indépendante.

Dans Flow, cette unité est représentée par un Ip (Instruction Pointer) :

$flow(new Ip($index));

Le pipeline est décrit sous forme d'étapes avec FlowFactory et un générateur :

$driver = new FiberDriver();
$savedFiles = [];

$flow = (new FlowFactory())->create(function () use ($file, &$savedFiles, $driver) {
    yield [
        fn (int $index) => $this->fetchImage($index, $driver),
        fn (ExceptionInterface $exception) => throw new \RuntimeException($exception->getMessage()),
    ];
    yield function (string $image) use ($file, &$savedFiles): string {
        $outputPath = $this->saveAndReport($image, $file);
        $savedFiles[] = $outputPath;

        return $outputPath;
    };
}, ['driver' => $driver]);

for ($index = 1; $index <= $count; ++$index) {
    $flow(new Ip($index));
}

try {
    $flow->await();
} catch (\RuntimeException $exception) {
    $this->io->error($exception->getMessage());

    return Command::FAILURE;
}

Conceptuellement, cela revient à écrire :

Ip($index)
 ↓
Fetch Image        ← étape async (fiber + delay)
 ↓
Save + Report      ← étape suivante, reçoit le string image

Chaque image traverse exactement le même pipeline.

Les responsabilités sont extraites en méthodes dédiées :

• fetchImage(int $index, FiberDriver $driver): string — téléchargement, avec suspension cooperative
• saveAndReport(string $image, ?string $fileOverride): string — hash, sauvegarde, reporting

La gestion d'erreur quitte la boucle : un errorJob sur l'étape fetch relance une RuntimeException, capturée une seule fois autour de await().

Remplacer l'attente bloquante

Le changement le plus important concerne la gestion du temps d'attente.

Dans la version synchrone, le délai est global et bloquant :

private const int DOWNLOAD_DELAY_SECONDS = 1;

// dans la boucle, entre chaque image :
sleep(self::DOWNLOAD_DELAY_SECONDS);

Dans la version Flow, le délai est par fibre et cooperative :

private const int DELAY_MIN_SECONDS = 1;
private const int DELAY_MAX_SECONDS = 3;

// dans fetchImage(), avant le téléchargement :
$delay = random_int(self::DELAY_MIN_SECONDS, self::DELAY_MAX_SECONDS);
$this->io->note(sprintf('#%d: suspending fiber for %ds before download...', $index, $delay));
$driver->delay($delay);

$driver->delay() suspend uniquement la fibre en cours. Les autres fibres continuent :

Image #1 attend (delay 2s)
Image #2 télécharge
Image #3 sauvegarde
Image #4 démarre son delay

Avec --count=5, le temps total se rapproche du max(delays + fetch) plutôt que de leur somme.

Les Fibers comme fondation d'exécution

Sous le capot, FiberDriver s'appuie sur les Fibers de PHP 8.1 : une Fiber peut être suspendue puis reprise plus tard, ce qui permet d'exécuter plusieurs traitements indépendants avec une écriture proche du PHP classique.

$driver = new FiberDriver();

Chaque image dispose de sa propre Fiber. Lorsqu'une Fiber attend ($driver->delay()), les autres continuent leur progression. Le logging reflète ce comportement :

#2: suspending fiber for 2s before download...
#2: downloading (other fibers may run while this one waits)...
#2: fetch complete in 1.34s

Flow ne remplace pas les Fibers : il les utilise via un driver. Le choix du driver détermine comment le pipeline s'exécute ; la description du pipeline reste identique.

Le point de synchronisation

Le for enqueue les unités de travail :

for ($index = 1; $index <= $count; ++$index) {
    $flow(new Ip($index));
}

await() devient le point de synchronisation unique :

$flow->await();

Planifier Ip(1)
Planifier Ip(2)
Planifier Ip(3)
…
await() — barrière finale

La responsabilité de l'orchestration est déplacée vers Flow. Le for ne fait plus le travail : il enqueue des unités. Flow les exécute en parallèle ; await() attend que tout le pipeline soit terminé.

Pourquoi conserver les Streams PHP ?

Le projet utilise volontairement :

$stream = fopen(self::FETCH_URL, 'r', false, $context);
$content = stream_get_contents($stream);

plutôt que file_get_contents().

L'objectif n'est pas de réinventer un client HTTP.

L'objectif est de rester proche des primitives PHP — le commentaire du code le dit explicitement :

Preferred for Flow experimentation: the resource handle is the primitive that can later be wired to stream_select(), non-blocking mode, or fibers.

Ces primitives pourront ensuite évoluer vers :

stream_set_blocking(false);
stream_select(...);

ou être intégrées dans des drivers plus avancés (Amp, React, Swoole — tous supportés par darkwood/flow).

Les streams constituent une base naturelle pour expérimenter les modèles asynchrones en PHP.

Limiter la concurrence (étape suivante)

Dans ce POC, toutes les images partent en parallèle (jusqu'à --count fibres actives).

Pour un usage production, Flow propose des stratégies comme MaxIpStrategy :

use Flow\IpStrategy\MaxIpStrategy;

yield [$job1, $errorJob1, new MaxIpStrategy(5)];

L'exemple officiel du package (examples/flow.php) utilise MaxIpStrategy(2) pour plafonner le nombre de jobs simultanés sur chaque étape.

Ce n'est pas encore branché dans flow-thispersondoesnotexist, mais c'est le levier naturel pour du rate limiting sans retomber dans du sleep() séquentiel.

Un modèle applicable bien au-delà des images

L'exemple ThisPersonDoesNotExist est volontairement simple. Le même schéma se retrouve dans les pipelines Darkwood :

Scraping YouTube     → Lister → Télécharger / transcrire → Sauvegarder
Traitement vidéo     → Générer assets → Encoder → Persister
Agent IA             → Lire → Transformer → Publier

Dans tous les cas : des unités de travail indépendantes qui traversent une succession d'étapes. Flow ne cherche pas à exécuter une tâche — il orchestre des flux de tâches.

Récapitulatif de la migration

Ce que Flow n'est pas

Avant de conclure, une clarification utile pour éviter les confusions courantes.

Flow n'est pas une event loop. Il ne gère pas directement un cycle select / poll sur des descripteurs I/O.

Flow n'est pas une implémentation de Fibers. Les Fibers sont une primitive PHP 8.1. Flow les orchestre via des drivers, mais ne les remplace pas.

Flow n'est pas un runtime. Il ne modifie pas le modèle d'exécution de PHP. Il s'exécute dans un processus PHP standard.

Flow n'est pas un substitut à Amp, ReactPHP ou Swoole. Ces bibliothèques fournissent des runtimes et des boucles d'événements. Flow peut s'appuyer dessus — AmpDriver, ReactDriver, SwooleDriver — sans entrer en concurrence avec elles.

Ce que Flow apporte, c'est un modèle d'orchestration :

• décrire des unités de travail (Ip)
• composer des pipelines d'étapes (yield dans FlowFactory)
• déléguer l'exécution à un driver choisi (FiberDriver, AmpDriver, ReactDriver, SwooleDriver, …)

Le modèle d'orchestration est séparé du modèle d'exécution. On peut décrire un pipeline une fois, puis changer de driver selon le contexte — CLI avec Fibers, worker Swoole, service React — sans réécrire la logique métier.

Conclusion

Le passage du synchrone vers l'asynchrone n'est pas avant tout une question de performance.

C'est un changement de modèle mental :

Avant : exécuter l'opération A, puis B, puis C — et attendre entre chaque étape.

Après : décrire un pipeline, enqueue des unités de travail,
        laisser l'orchestrateur planifier l'exécution.

La boucle for devient un producteur d'Ip. Les étapes fetch et save deviennent des jobs chaînés. await() remplace la succession de sleep(). La logique métier (télécharger, hasher, sauvegarder) reste la même ; ce qui change, c'est qui décide quand chaque étape s'exécute.

C'est exactement le modèle dont Darkwood a besoin pour ses pipelines à venir : scraping YouTube et extraction de transcripts, traitement média dans MediaBundle, agents IA multi-étapes, orchestration de workflows longue durée. Des unités indépendantes, des étapes composables, un point de synchronisation explicite.

Le projet ThisPersonDoesNotExist en est la démonstration minimale : un seul fichier, un pipeline à deux étapes, un driver — suffisant pour illustrer la transition sans en masquer la portée.

Pour aller plus loin

• Dépôt du POC : flow-thispersondoesnotexist — commits fae47e8 → c61c929
• Package : darkwood/flow — exemple examples/flow.php
• L'article de Frédéric Bouchery retrace l'histoire de la programmation asynchrone en PHP, depuis les streams introduits dans PHP 4.3 jusqu'aux Fibers modernes de PHP 8.1 : https://f2r.github.io/fr/asynchrone.html