From 7cf5a2cb825e0198e02a55822ca09bf4cfb35d49 Mon Sep 17 00:00:00 2001
From: PurHur <PurHur@users.noreply.github.com>
Date: Tue, 19 May 2026 13:42:13 +0000
Subject: [PATCH] Document phpc run -q/-p web superglobals in CLI help (#268)

Contributors can run examples/001-SimpleWeb without phpc serve; help and
PhpcCliTest assert the existing vm.php passthrough.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 README.md                 |  1 +
 bin/phpc.php              |  7 +++++--
 test/unit/PhpcCliTest.php | 27 +++++++++++++++++++++++++++
 3 files changed, 33 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 5dd27ae2..43e31b7c 100755
--- a/README.md
+++ b/README.md
@@ -19,6 +19,7 @@ cd php-compiler
 composer install
 ./phpc test                    # full PHPUnit suite (VM, compliance, JIT, AOT)
 ./phpc run -r 'echo 1;'        # VM mode (or: php bin/vm.php -r 'echo 1;')
+./phpc run -q 'name=Dev' examples/001-SimpleWeb/example.php   # web example without TCP
 make web-smoke                 # VM: examples/001-SimpleWeb
 ./phpc serve examples/001-SimpleWeb   # http://127.0.0.1:8080/ (or: make serve)
 ```
diff --git a/bin/phpc.php b/bin/phpc.php
index d2d8313f..180dbf02 100755
--- a/bin/phpc.php
+++ b/bin/phpc.php
@@ -9,7 +9,7 @@
  * Usage:
  *   phpc serve [host:port] [docroot]
  *   phpc serve --aot [host:port] [docroot] [--binary path]
- *   phpc run script.php [args...]
+ *   phpc run [-q 'name=World'] [-p 'field=val'] script.php [args...]
  *   phpc build [-o outfile] entry.php
  *   phpc lint [-r 'code'] [--json] entry.php
  *   phpc test [-- phpunit/ci-local args...]
@@ -27,7 +27,10 @@
   phpc serve [host:port] [docroot]              Start HTTP dev server (VM)
   phpc serve --aot [host:port] [docroot]        Serve precompiled AOT binary (CGI env)
       [--binary path]                           Explicit binary or phpc.json "binary"
-  phpc run <script.php> [args...]              Run a script in the VM
+  phpc run <script.php> [vm.php flags...]      Run a script in the VM
+      -q 'name=World'                          CGI-style QUERY_STRING → $_GET
+      -p 'field=value'                         CGI-style POST body → $_POST
+      Example: phpc run -q 'name=Dev' examples/001-SimpleWeb/example.php
   phpc build [-o out] <entry.php>               AOT compile to a native binary
   phpc lint [-r 'code'] [--json] <entry.php>    Report unsupported syntax (line-accurate)
   phpc test [args...]                           Run ./script/ci-local.sh
diff --git a/test/unit/PhpcCliTest.php b/test/unit/PhpcCliTest.php
index 8dab4c94..c6164dee 100644
--- a/test/unit/PhpcCliTest.php
+++ b/test/unit/PhpcCliTest.php
@@ -33,6 +33,33 @@ public function testHelpListsSubcommands(): void
         $this->assertStringContainsString('phpc build', $out !== false ? $out : '');
         $this->assertStringContainsString('phpc test', $out !== false ? $out : '');
         $this->assertStringContainsString('phpc lint', $out !== false ? $out : '');
+        $this->assertStringContainsString('-q', $out !== false ? $out : '');
+        $this->assertStringContainsString('$_GET', $out !== false ? $out : '');
+    }
+
+    public function testRunSimpleWebWithQueryFlag(): void
+    {
+        $repoRoot = dirname(__DIR__, 2);
+        $script = $repoRoot.'/examples/001-SimpleWeb/example.php';
+        $cmd = array_merge(
+            self::phpCommand(),
+            [$repoRoot.'/bin/phpc.php', 'run', '-q', 'name=Dev', $script]
+        );
+        $descriptorSpec = [
+            0 => ['pipe', 'r'],
+            1 => ['pipe', 'w'],
+            2 => ['pipe', 'w'],
+        ];
+        $proc = proc_open($cmd, $descriptorSpec, $pipes, $repoRoot);
+        $this->assertIsResource($proc);
+        fclose($pipes[0]);
+        $out = stream_get_contents($pipes[1]);
+        $err = stream_get_contents($pipes[2]);
+        fclose($pipes[1]);
+        fclose($pipes[2]);
+        $exit = proc_close($proc);
+        $this->assertSame(0, $exit, $err !== false ? $err : '');
+        $this->assertStringContainsString('Hello Dev', $out !== false ? $out : '');
     }
 
     /**