From 8bfd798be8ffdb81822c04544a533f28d98865a3 Mon Sep 17 00:00:00 2001 From: Durable Workflow Date: Sat, 5 Sep 2026 06:51:26 +0000 Subject: [PATCH] Clarify the managed PHP playground and editable source paths --- AGENTS.md | 2 ++ README.md | 30 +++++++++++++++++++++++---- scripts/playground | 7 +++++++ tests/Unit/PlaygroundContractTest.php | 4 ++++ 4 files changed, 39 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3f57931..6af2112 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,6 +16,8 @@ start with the repository playground instead of the conformance matrix. `--runtime-url`, `--namespace`, and `--task-queue`; provide its separate worker and client role credentials through the named process environment variables described by `scripts/playground --help`. +- The [PHP on Cloud example](README.md#php-on-cloud) shows the complete + managed invocation and explains the Laravel bridge versus embedded runtime. - Treat the printed effective contract and `Worker ready` checkpoint as the source of truth for workflow type, activity type, task queue, worker command, start command, and expected result. Do not repeat scenario identities in an diff --git a/README.md b/README.md index e6efc6c..235e6d4 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,8 @@ Runnable examples for Durable Workflow 2.0. Start a PHP-authored workflow that calls Python and Rust activities through a standalone Server, build a workflow with any first-party SDK, or run the workflow engine inside Laravel. +Already have a Cloud namespace? Start with [PHP on Cloud](#php-on-cloud). + [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/durable-workflow/sample-app?quickstart=1) ## Choose a path @@ -61,6 +63,12 @@ isolated local Server and Waterline, waits for the worker registration, starts the workflow, verifies its result and history, and prints the matching Waterline run URL. Existing authored files are preserved. +The generated workflow and activity are yours to edit. `.playground/` and the +default evidence files are ignored by Git; the evidence is a run report, not +application source. To keep authored code in your project, choose a directory +with `--source`, review the generated files, and commit only your source, not +credentials or run reports. Existing files are preserved on subsequent runs. + Create a caller-owned project elsewhere with `--source`: ```bash @@ -82,24 +90,38 @@ scripts/playground down rust ### Managed runtime +#### PHP on Cloud + The same authored project can run against Durable Workflow Cloud or another -existing runtime. Supply role-specific credentials without putting them in -source control: +existing runtime, without starting a local Server or Waterline. Use the exact +runtime URL and namespace shown by Cloud; do not append `/api`. Supply the +runtime worker and client SDK credentials, not a Cloud control-plane API key: ```bash export DURABLE_WORKFLOW_WORKER_TOKEN='' export DURABLE_WORKFLOW_CLIENT_TOKEN='' -scripts/playground rust \ +scripts/playground php \ --runtime managed \ --runtime-url 'https://runtime.example/namespaces/example' \ --namespace 'example' \ - --task-queue 'my-rust-worker' + --task-queue 'my-php-worker' ``` The worker receives only the worker credential, and the client receives only the client credential. The runner prints the workflow type, activity type, task queue, worker command, start command, and expected result before it runs. +Expect `Worker ready: target=managed`, followed by `Completed php workflow` +and the result containing `workflow_runtime: php` and `activity_runtime: php`. +Use `python` or `rust` in place of `php` for the other SDKs. + +This PHP path is **service mode using the Laravel bridge**, not the embedded +workflow engine. Laravel provides configuration, dependency injection, PSR +logging, and the SDK test fake. The SDK worker polls Cloud; Laravel's embedded +queue worker is not its executor. The generated `bootstrap.php` and activity +use Laravel, while the core PHP SDK also supports framework-free processes. +For those, use `scripts/playground scaffold php --standalone --source ` +to inspect the installed SDK's own worker/client examples. ## Embedded Laravel diff --git a/scripts/playground b/scripts/playground index 031c3db..d97ed9d 100755 --- a/scripts/playground +++ b/scripts/playground @@ -955,6 +955,13 @@ def journey( if effective_task_queue: scenario["task_queue"] = effective_task_queue created = scaffold(language, source_dir, scenario=scenario) + print(f"Editable {language} source: {source_dir}", flush=True) + print(f"Generated run evidence: {evidence_path}", flush=True) + print( + "Edit the generated source for your application. The default .playground/ " + "directory is Git-ignored; use --source for your project directory.", + flush=True, + ) project = os.environ.get("PLAYGROUND_COMPOSE_PROJECT", "sample-app-playground") task_queue = str(scenario["task_queue"]) worker_id = f"sample-app-playground-{language}-worker-{suffix}" diff --git a/tests/Unit/PlaygroundContractTest.php b/tests/Unit/PlaygroundContractTest.php index ea6dc5c..e7b1078 100644 --- a/tests/Unit/PlaygroundContractTest.php +++ b/tests/Unit/PlaygroundContractTest.php @@ -724,6 +724,10 @@ class FakeWorker: $this->assertStringContainsString('managed-harness=["php", "python", "rust"]', $output); $this->assertSame(3, substr_count($output, 'Worker ready: target=managed')); $this->assertSame(3, substr_count($output, '"runtime_target":"managed"')); + foreach (['php', 'python', 'rust'] as $language) { + $this->assertStringContainsString("Editable {$language} source: {$temporaryDirectory}/{$language}", $output); + $this->assertStringContainsString("Generated run evidence: {$temporaryDirectory}/{$language}.json", $output); + } $this->assertStringNotContainsString('worker-secret', $output); $this->assertStringNotContainsString('client-secret', $output); } finally {