From 14a49f72860010acfd756bea4293e3bfb6820718 Mon Sep 17 00:00:00 2001
From: Timm Friebe <thekid@thekid.de>
Date: Sat, 18 May 2024 15:27:47 +0800
Subject: [PATCH] Reintroduce the web.Dispatch class for BC (but deprecate it!)

See https://github.com/xp-forge/web/issues/113#issuecomment-2118673725
---
 src/main/php/web/Application.class.php        |  4 +--
 src/main/php/web/Dispatch.class.php           | 34 +++++++++++++++++++
 .../web/unittest/ApplicationTest.class.php    | 17 +++++++++-
 3 files changed, 52 insertions(+), 3 deletions(-)
 create mode 100755 src/main/php/web/Dispatch.class.php

diff --git a/src/main/php/web/Application.class.php b/src/main/php/web/Application.class.php
index c4a14707..c926188a 100755
--- a/src/main/php/web/Application.class.php
+++ b/src/main/php/web/Application.class.php
@@ -1,6 +1,6 @@
 <?php namespace web;
 
-use Closure, Generator;
+use Closure, Traversable;
 use lang\Value;
 
 /**
@@ -86,7 +86,7 @@ public function service($request, $response) {
 
     // Handle dispatching
     dispatch: $result= $this->routing()->handle($request, $response);
-    if ($result instanceof Generator) {
+    if ($result instanceof Traversable) {
       foreach ($result as $kind => $argument) {
         if ('dispatch' === $kind) {
           $seen[$request->uri()->hashCode()]= true;
diff --git a/src/main/php/web/Dispatch.class.php b/src/main/php/web/Dispatch.class.php
new file mode 100755
index 00000000..6344e881
--- /dev/null
+++ b/src/main/php/web/Dispatch.class.php
@@ -0,0 +1,34 @@
+<?php namespace web;
+
+use IteratorAggregate, Traversable;
+use util\URI;
+
+/**
+ * Dispatches a request; performing an internal redirect.
+ * 
+ * Return instances of this class from a handler *before* the response
+ * has been flushed, as follows:
+ *
+ * ```php
+ * function($req, $res) {
+ *   return $req->dispatch('/home');
+ * }
+ * ```
+ *
+ * @deprecated See https://github.com/xp-forge/web/issues/113#issuecomment-2118673725
+ * @see   xp://web.Request#dispatch
+ */
+class Dispatch implements IteratorAggregate {
+  private $uri;
+
+  /** @param util.URI|string $uri */
+  public function __construct($uri) {
+    $this->uri= $uri instanceof URI ? $uri : new URI($uri);
+  }
+
+  /** @return util.URI */
+  public function uri() { return $this->uri; }
+
+  /** @return iterable */
+  public function getIterator(): Traversable { yield 'dispatch' => $this->uri; }
+}
\ No newline at end of file
diff --git a/src/test/php/web/unittest/ApplicationTest.class.php b/src/test/php/web/unittest/ApplicationTest.class.php
index 205ee7bc..530d3fd1 100755
--- a/src/test/php/web/unittest/ApplicationTest.class.php
+++ b/src/test/php/web/unittest/ApplicationTest.class.php
@@ -4,7 +4,7 @@
 use test\{Assert, Expect, Test, Values};
 use util\Objects;
 use web\io\{TestInput, TestOutput};
-use web\{Application, Environment, Error, Filter, Filters, Handler, Request, Response, Routing};
+use web\{Application, Dispatch, Environment, Error, Filter, Filters, Handler, Request, Response, Routing};
 
 class ApplicationTest {
   private $environment;
@@ -218,6 +218,21 @@ public function dispatch_request_bubbles_up_to_toplevel() {
     });
   }
 
+  /** @deprecated */
+  #[Test]
+  public function dispatch_request_via_dispatch_instance() {
+    $this->assertHandled($handled, function() use(&$handled) {
+      return [
+        '/home' => function($request, $response) use(&$handled) {
+          $handled[]= [$request, $response];
+        },
+        '/' => function($request, $response) {
+          return new Dispatch('/home');
+        },
+      ];
+    });
+  }
+
   #[Test]
   public function string_representation() {
     Assert::equals(