From e1268d19720fc866db979b417cfbf8f5e04b6bf5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9gory=20Planchat?= Date: Mon, 31 Aug 2026 09:18:33 +0200 Subject: [PATCH 1/3] docs(user): ancrer la comparaison sur temporal/sdk v2.18 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit La page ne disait contre quelle version du SDK elle avait été vérifiée. Un comparatif non daté face à une cible mouvante devient faux tout seul, et se lit ensuite comme malhonnête plutôt que périmé — « à l'heure où ces lignes sont écrites » en §8 le montrait déjà. L'en-tête nomme donc la version vérifiée (v2.18, 2026-08-17) et dit de lire une différence comme vraie à cette version. Les deux sections que le SDK a annoncé vouloir refermer citent le travail public plutôt que l'annonce : §5 pointe la PR #798 (API de fibres) et le ticket #702, §8 la PR #768 (intégration Nexus) et la tentative #580. §5 précise en plus ce que les fibres ne changeraient pas — le moteur du worker et la surface d'écriture, soit les sections 1, 2 et 4. Les sections 1, 4 et 8 de la version française prennent l'ancre explicite de leur équivalent anglais, comme le font déjà les sections 2 et 5, pour que les renvois soient les mêmes dans les deux langues. Co-Authored-By: Claude Opus 5 (1M context) --- documentation/user/comparison/_index.fr.md | 50 ++++++++++++++++------ documentation/user/comparison/_index.md | 40 ++++++++++++++--- 2 files changed, 71 insertions(+), 19 deletions(-) diff --git a/documentation/user/comparison/_index.fr.md b/documentation/user/comparison/_index.fr.md index bb27c07b..a46fbf4c 100644 --- a/documentation/user/comparison/_index.fr.md +++ b/documentation/user/comparison/_index.fr.md @@ -12,9 +12,16 @@ métier au long cours — et font des arbitrages différents à chaque couche en Cette page énonce ces différences, y compris celles où le SDK est devant. +**Quelle version du SDK.** Chaque affirmation ci-dessous a été vérifiée contre `temporal/sdk` +**v2.18**, publiée le 2026-08-17. Le SDK avance, et deux des différences énoncées ici sont de celles +que ses mainteneurs ont dit à voix haute vouloir refermer — les sections +[5](#5-fibers-or-generators-the-colouring-problem) et [8](#8-nexus-the-one-place-durable-is-ahead) +nomment le travail public en cours. Lisez une différence comme vraie à cette version, non comme une +propriété permanente. + --- -## 1. Le moteur du worker : pas de RoadRunner +## 1. Le moteur du worker : pas de RoadRunner {#1-the-worker-runtime-no-roadrunner} Le SDK se scinde en un **client** et un **worker**. Le client exige `ext-grpc` ; le worker exige **RoadRunner**, un serveur applicatif Go que l'on télécharge dans le projet par @@ -211,7 +218,7 @@ bouge pas. Voir [Backends](../backends/). --- -## 4. La surface d'écriture +## 4. La surface d'écriture {#4-the-authoring-surface} Le même workflow — encaisser une commande, attendre une heure, envoyer le reçu — écrit deux fois. @@ -388,6 +395,19 @@ Aucun des deux modèles n'affecte le déterminisme : les deux rejouent le même interdisent les mêmes appels non déterministes dans un workflow. La différence est l'endroit où vit le mot-clé de suspension — dans votre code, ou dans le moteur. +### Le SDK compte refermer cet écart + +Les fibres ne sont pas une frontière permanente. Le SDK a une *pull request* ouverte qui ajoute une +API de fibres ([#798](https://github.com/temporalio/sdk-php/pull/798)), après le ticket qui +proposait de remplacer les *yields* par une suspension de fibre +([#702](https://github.com/temporalio/sdk-php/issues/702)), et ses mainteneurs ont annoncé le +changement prototypé et prévu pour un prochain majeur. Rien de tout cela n'est dans une version +publiée à la v2.18, et cette section décrit la v2.18. + +Ce que cela réglerait, c'est la coloration, pas le reste de la page : les sections +[1](#1-the-worker-runtime-no-roadrunner), [2](#2-testability) et [4](#4-the-authoring-surface) +reposent sur le moteur du worker et la surface d'écriture, auxquels les fibres ne touchent pas. + --- ## 6. Planifier des activités @@ -435,7 +455,7 @@ Voir [Changer un workflow qui tourne](../deploying/). --- -## 8. Nexus : le seul endroit où Durable est devant +## 8. Nexus : le seul endroit où Durable est devant {#8-nexus-the-one-place-durable-is-ahead} [Nexus](https://docs.temporal.io/nexus) achemine un appel d'un workflow vers une opération servie dans un autre espace de noms ou un autre cluster. **Un workflow Durable peut en appeler une, et @@ -452,15 +472,21 @@ chaîne. Cela compte parce que le serveur ne garde que le point d'entrée : il r malformé, et accepte sans un mot un service ou une opération vide ou faite d'espaces — laissant l'appel attendre un gestionnaire dont le nom ne correspondra jamais. -À l'heure où ces lignes sont écrites, « Nexus » n'apparaît dans le SDK PHP que comme de la plomberie -gRPC engendrée — CRUD de points d'entrée sur le client opérateur, une option d'emplacement de tâche -sur le worker, un vidage d'historique — sans aucune API qu'un workflow puisse atteindre. La -documentation de Temporal porte une section Nexus pour Go, Java, Python, TypeScript et .NET, et -aucune pour PHP. Côté Durable, le chemin appelant est éprouvé par des tests d'intégration contre un -vrai serveur Temporal : aller-retours, annulation et échec, bornes d'opération, les règles de -nommage du point d'entrée, du service, de l'opération et des en-têtes — et, côté gestionnaire, les -deux formes de réponse et le chemin d'annulation, un appelant Durable et un gestionnaire Durable -dans le même test. +À la v2.18, « Nexus » n'apparaît dans le SDK PHP que comme de la plomberie gRPC engendrée — CRUD de +points d'entrée sur le client opérateur, une option d'emplacement de tâche sur le worker, un vidage +d'historique — sans aucune API qu'un workflow puisse atteindre. La documentation de Temporal porte +une section Nexus pour Go, Java, Python, TypeScript et .NET, et aucune pour PHP. + +**Et cela se construit.** Une intégration est ouverte en *pull request* +([#768](https://github.com/temporalio/sdk-php/pull/768)), après une première tentative +d'implémentation ([#580](https://github.com/temporalio/sdk-php/pull/580)), et ses mainteneurs l'ont +annoncée pour un prochain majeur. Lisez « le seul endroit où Durable est devant » comme une avance +qui se mesure en versions, non comme un écart qui restera ouvert. + +Côté Durable, le chemin appelant est éprouvé par des tests d'intégration contre un vrai serveur +Temporal : aller-retours, annulation et échec, bornes d'opération, les règles de nommage du point +d'entrée, du service, de l'opération et des en-têtes — et, côté gestionnaire, les deux formes de +réponse et le chemin d'annulation, un appelant Durable et un gestionnaire Durable dans le même test. **Et l'appel interopère.** La charge voyage telle que l'appelant l'a écrite — sans emballage, sans enveloppe —, si bien qu'un gestionnaire écrit avec un autre SDK y lit les champs qu'il déclare. diff --git a/documentation/user/comparison/_index.md b/documentation/user/comparison/_index.md index 3bd40373..e4c145d0 100644 --- a/documentation/user/comparison/_index.md +++ b/documentation/user/comparison/_index.md @@ -12,6 +12,12 @@ long-running business logic — and they make different trade-offs at every laye This page states those differences, including the ones where the SDK is ahead. +**Which SDK.** Every claim below was checked against `temporal/sdk` **v2.18**, released 2026-08-17. +The SDK moves, and two of the differences stated here are ones its maintainers have said out loud +they intend to close — sections [5](#5-fibers-or-generators-the-colouring-problem) and +[8](#8-nexus-the-one-place-durable-is-ahead) name the public work in flight. Read a difference as of +that version, not as a permanent property. + --- ## 1. The worker runtime: no RoadRunner @@ -382,6 +388,18 @@ Neither model affects determinism: both replay the same history, and both forbid non-deterministic calls inside a workflow. The difference is where the suspension keyword lives — in your code, or in the runtime. +### The SDK intends to close this + +Fibers are not a permanent divide. The SDK has an open pull request adding a Fibers API +([#798](https://github.com/temporalio/sdk-php/pull/798)), on top of the issue that proposed +replacing yields with fiber suspension ([#702](https://github.com/temporalio/sdk-php/issues/702)), +and its maintainers have said the change is prototyped and slated for an upcoming major. None of it +is in a release as of v2.18, and this section describes v2.18. + +What that would settle is the colouring, not the rest of the page: sections +[1](#1-the-worker-runtime-no-roadrunner), [2](#2-testability) and [4](#4-the-authoring-surface) rest +on the worker runtime and the authoring surface, which fibers do not touch. + --- ## 6. Scheduling activities @@ -444,13 +462,21 @@ That matters because the server only guards the endpoint: it refuses a malformed accepts an empty or whitespace-only service or operation without a word — leaving the call waiting for a handler whose name will never match. -At the time of writing, "Nexus" appears in the PHP SDK only as generated gRPC plumbing — endpoint -CRUD on the operator client, a task-slot option on the worker, history dumping — with no API a -workflow can reach. Temporal's own documentation carries a Nexus section for Go, Java, Python, -TypeScript and .NET, and none for PHP. On the Durable side the caller path is exercised by -integration tests against a real Temporal server: round trips, cancellation and failure, operation -bounds, the endpoint, service, operation and header naming rules — and, on the handler side, both -response shapes and the cancellation path, a Durable caller and a Durable handler in the same test. +As of v2.18, "Nexus" appears in the PHP SDK only as generated gRPC plumbing — endpoint CRUD on the +operator client, a task-slot option on the worker, history dumping — with no API a workflow can +reach. Temporal's own documentation carries a Nexus section for Go, Java, Python, TypeScript and +.NET, and none for PHP. + +**This one is being built.** An integration is open in a pull request +([#768](https://github.com/temporalio/sdk-php/pull/768)), following an earlier implementation +attempt ([#580](https://github.com/temporalio/sdk-php/pull/580)), and its maintainers have said it +is slated for an upcoming major. Read "the one place Durable is ahead" as a lead measured in +releases, not as a gap that will stay open. + +On the Durable side the caller path is exercised by integration tests against a real Temporal +server: round trips, cancellation and failure, operation bounds, the endpoint, service, operation +and header naming rules — and, on the handler side, both response shapes and the cancellation path, +a Durable caller and a Durable handler in the same test. **And the call interoperates.** The payload travels as the caller wrote it — no wrapper, no envelope — so a handler written with another SDK reads the fields it declares. Measured against a From 7bb941119b1618a43ffa1aa3d5f108b9f2ff3c86 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9gory=20Planchat?= Date: Mon, 31 Aug 2026 09:19:30 +0200 Subject: [PATCH 2/3] docs(user): #580 est un ticket, pas une pull request MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Le lien pointait vers /pull/580 et le texte l'annonçait comme une tentative d'implémentation. GitHub redirige, donc le lien marchait, mais la section dit justement citer ses sources plutôt que de répéter une annonce — s'y tromper était la seule erreur qu'un mainteneur du SDK verrait du premier coup d'œil. Co-Authored-By: Claude Opus 5 (1M context) --- documentation/user/comparison/_index.fr.md | 4 ++-- documentation/user/comparison/_index.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/documentation/user/comparison/_index.fr.md b/documentation/user/comparison/_index.fr.md index a46fbf4c..805f9e18 100644 --- a/documentation/user/comparison/_index.fr.md +++ b/documentation/user/comparison/_index.fr.md @@ -478,8 +478,8 @@ d'historique — sans aucune API qu'un workflow puisse atteindre. La documentati une section Nexus pour Go, Java, Python, TypeScript et .NET, et aucune pour PHP. **Et cela se construit.** Une intégration est ouverte en *pull request* -([#768](https://github.com/temporalio/sdk-php/pull/768)), après une première tentative -d'implémentation ([#580](https://github.com/temporalio/sdk-php/pull/580)), et ses mainteneurs l'ont +([#768](https://github.com/temporalio/sdk-php/pull/768)), après le ticket qui a ouvert le +sujet ([#580](https://github.com/temporalio/sdk-php/issues/580)), et ses mainteneurs l'ont annoncée pour un prochain majeur. Lisez « le seul endroit où Durable est devant » comme une avance qui se mesure en versions, non comme un écart qui restera ouvert. diff --git a/documentation/user/comparison/_index.md b/documentation/user/comparison/_index.md index e4c145d0..68e8e0d1 100644 --- a/documentation/user/comparison/_index.md +++ b/documentation/user/comparison/_index.md @@ -468,8 +468,8 @@ reach. Temporal's own documentation carries a Nexus section for Go, Java, Python .NET, and none for PHP. **This one is being built.** An integration is open in a pull request -([#768](https://github.com/temporalio/sdk-php/pull/768)), following an earlier implementation -attempt ([#580](https://github.com/temporalio/sdk-php/pull/580)), and its maintainers have said it +([#768](https://github.com/temporalio/sdk-php/pull/768)), following the issue that opened the +subject ([#580](https://github.com/temporalio/sdk-php/issues/580)), and its maintainers have said it is slated for an upcoming major. Read "the one place Durable is ahead" as a lead measured in releases, not as a gap that will stay open. From 9fb74f383a50977e64042cf3a1c73d638fd02802 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9gory=20Planchat?= Date: Mon, 31 Aug 2026 09:20:39 +0200 Subject: [PATCH 3/3] =?UTF-8?q?docs(user):=20les=20fibres=20ne=20referment?= =?UTF-8?q?=20pas=20la=20testabilit=C3=A9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Le paragraphe de clôture de la §5 disait que les fibres ne touchent ni au moteur du worker ni à la surface d'écriture. C'est vrai mais trop plat : il ne disait pas laquelle des différences restantes deviendrait la principale. Le mécanisme de suspension n'est pas ce qui oblige un test de workflow à démarrer un serveur — c'est le moteur du worker. Un workflow tourne dans RoadRunner, piloté par une file de tâches sur un vrai cluster, qu'il suspende sur un yield ou sur une fibre. Une fois les fibres arrivées, c'est donc la §2 qui porte l'écart. Co-Authored-By: Claude Opus 5 (1M context) --- documentation/user/comparison/_index.fr.md | 10 +++++++--- documentation/user/comparison/_index.md | 9 ++++++--- 2 files changed, 13 insertions(+), 6 deletions(-) diff --git a/documentation/user/comparison/_index.fr.md b/documentation/user/comparison/_index.fr.md index 805f9e18..903722ed 100644 --- a/documentation/user/comparison/_index.fr.md +++ b/documentation/user/comparison/_index.fr.md @@ -404,9 +404,13 @@ proposait de remplacer les *yields* par une suspension de fibre changement prototypé et prévu pour un prochain majeur. Rien de tout cela n'est dans une version publiée à la v2.18, et cette section décrit la v2.18. -Ce que cela réglerait, c'est la coloration, pas le reste de la page : les sections -[1](#1-the-worker-runtime-no-roadrunner), [2](#2-testability) et [4](#4-the-authoring-surface) -reposent sur le moteur du worker et la surface d'écriture, auxquels les fibres ne touchent pas. +Ce que cela réglerait, c'est la coloration, et rien qu'elle. Le mécanisme de suspension n'est pas ce +qui oblige un test de workflow à démarrer un serveur : c'est [le moteur du +worker](#1-the-worker-runtime-no-roadrunner). Un workflow continue de tourner dans RoadRunner, +piloté par une file de tâches sur un vrai cluster, qu'il suspende sur un `yield` ou sur une fibre. +La différence qui compterait donc le plus une fois les fibres arrivées est celle au-dessus d'elles : +[la testabilité](#2-testability) — mener un workflow jusqu'au bout dans le processus de test, +vérifier une valeur rendue, sans serveur à démarrer ni second moteur à surveiller. --- diff --git a/documentation/user/comparison/_index.md b/documentation/user/comparison/_index.md index 68e8e0d1..b3b9e987 100644 --- a/documentation/user/comparison/_index.md +++ b/documentation/user/comparison/_index.md @@ -396,9 +396,12 @@ replacing yields with fiber suspension ([#702](https://github.com/temporalio/sdk and its maintainers have said the change is prototyped and slated for an upcoming major. None of it is in a release as of v2.18, and this section describes v2.18. -What that would settle is the colouring, not the rest of the page: sections -[1](#1-the-worker-runtime-no-roadrunner), [2](#2-testability) and [4](#4-the-authoring-surface) rest -on the worker runtime and the authoring surface, which fibers do not touch. +What that would settle is the colouring, and only the colouring. The suspension mechanism is not +what makes a workflow test need a server — [the worker runtime](#1-the-worker-runtime-no-roadrunner) +is. A workflow still runs inside RoadRunner, driven by a task queue on a real cluster, whether it +suspends on a `yield` or on a fiber. So the difference that would matter most once fibers land is +the one above them: [Testability](#2-testability) — running a workflow to completion in the test +process, asserting on a returned value, with no server to start and no second runtime to supervise. ---