Deprecate DoublePassDecoratorMiddleware.

Support for "double pass" middleware was added just to make upgrading from 3.x easier.

psalm-baseline.xml

@@ -140,6 +140,12 @@
       <code>$this-&gt;headers</code>
     </PropertyTypeCoercion>
   </file>
+  <file src="src/Http/MiddlewareQueue.php">
+    <DeprecatedClass occurrences="2">
+      <code>new DoublePassDecoratorMiddleware($middleware)</code>
+      <code>new DoublePassDecoratorMiddleware($middleware)</code>
+    </DeprecatedClass>
+  </file>
   <file src="src/Http/ServerRequest.php">
     <ArgumentTypeCoercion occurrences="1">
       <code>$this-&gt;data</code>

src/Http/Middleware/DoublePassDecoratorMiddleware.php

@@ -38,6 +38,9 @@ use Psr\Http\Server\RequestHandlerInterface;
  * or a class with `__invoke()` method with same signature as above.
  *
  * Neither the arguments nor the return value need be typehinted.
+ *
+ * @deprecated 4.3.0 "Double pass" middleware are deprecated.
+ *   Use a `Closure` or a class which implements `Psr\Http\Server\MiddlewareInterface` instead.
  */
 class DoublePassDecoratorMiddleware implements MiddlewareInterface
 {
@@ -55,6 +58,10 @@ class DoublePassDecoratorMiddleware implements MiddlewareInterface
      */
     public function __construct(callable $callable)
     {
+        deprecationWarning(
+            '"Double pass" middleware are deprecated. Use a `Closure` with the signature of'
+            . ' `($request, $handler)` or a class which implements `Psr\Http\Server\MiddlewareInterface` instead.'
+        );
         $this->callable = $callable;
     }
 

tests/TestCase/Http/MiddlewareQueueTest.php

@@ -175,8 +175,8 @@ class MiddlewareQueueTest extends TestCase
         $queue->add('Sample');
         $queue->prepend('TestApp\Middleware\SampleMiddleware');
 
-        $this->assertInstanceOf('TestApp\Middleware\SampleMiddleware', $queue->current()->getCallable());
-        $this->assertInstanceOf('TestApp\Middleware\SampleMiddleware', $queue->current()->getCallable());
+        $this->assertInstanceOf('TestApp\Middleware\SampleMiddleware', $queue->current());
+        $this->assertInstanceOf('TestApp\Middleware\SampleMiddleware', $queue->current());
     }
 
     /**
@@ -193,7 +193,7 @@ class MiddlewareQueueTest extends TestCase
         $queue->add([$one]);
         $queue->prepend(['TestApp\Middleware\SampleMiddleware']);
 
-        $this->assertInstanceOf('TestApp\Middleware\SampleMiddleware', $queue->current()->getCallable());
+        $this->assertInstanceOf('TestApp\Middleware\SampleMiddleware', $queue->current());
         $queue->next();
         $this->assertSame($one, $queue->current()->getCallable());
     }
@@ -219,7 +219,7 @@ class MiddlewareQueueTest extends TestCase
         $queue->next();
         $this->assertSame($one, $queue->current()->getCallable());
         $queue->next();
-        $this->assertSame($four, $queue->current()->getCallable());
+        $this->assertInstanceOf(SampleMiddleware::class, $queue->current());
         $queue->next();
         $this->assertSame($two, $queue->current()->getCallable());
 
@@ -272,7 +272,7 @@ class MiddlewareQueueTest extends TestCase
         $this->assertCount(3, $queue);
         $this->assertSame($two, $queue->current()->getCallable());
         $queue->next();
-        $this->assertSame($three, $queue->current()->getCallable());
+        $this->assertInstanceOf(SampleMiddleware::class, $queue->current());
         $queue->next();
         $this->assertSame($one, $queue->current()->getCallable());
     }
@@ -299,9 +299,9 @@ class MiddlewareQueueTest extends TestCase
         $queue->next();
         $this->assertSame($three, $queue->current()->getCallable());
         $queue->next();
-        $this->assertSame($four, $queue->current()->getCallable());
+        $this->assertInstanceOf(DumbMiddleware::class, $queue->current());
         $queue->next();
-        $this->assertSame($two, $queue->current()->getCallable());
+        $this->assertInstanceOf(SampleMiddleware::class, $queue->current());
 
         $two = SampleMiddleware::class;
         $queue = new MiddlewareQueue();
@@ -315,7 +315,7 @@ class MiddlewareQueueTest extends TestCase
         $queue->next();
         $this->assertSame($three, $queue->current()->getCallable());
         $queue->next();
-        $this->assertInstanceOf(SampleMiddleware::class, $queue->current()->getCallable());
+        $this->assertInstanceOf(SampleMiddleware::class, $queue->current());
     }
 
     /**
@@ -357,9 +357,9 @@ class MiddlewareQueueTest extends TestCase
             ->insertAfter(SampleMiddleware::class, $four);
 
         $this->assertCount(4, $queue);
-        $this->assertSame($one, $queue->current()->getCallable());
+        $this->assertInstanceOf(SampleMiddleware::class, $queue->current());
         $queue->next();
-        $this->assertSame($four, $queue->current()->getCallable());
+        $this->assertInstanceOf(DumbMiddleware::class, $queue->current());
         $queue->next();
         $this->assertSame($three, $queue->current()->getCallable());
         $queue->next();
@@ -373,7 +373,7 @@ class MiddlewareQueueTest extends TestCase
             ->insertAfter('Sample', $three);
 
         $this->assertCount(3, $queue);
-        $this->assertInstanceOf(SampleMiddleware::class, $queue->current()->getCallable());
+        $this->assertInstanceOf(SampleMiddleware::class, $queue->current());
         $queue->next();
         $this->assertSame($three, $queue->current()->getCallable());
         $queue->next();
@@ -396,10 +396,25 @@ class MiddlewareQueueTest extends TestCase
         $queue->add($one)->add($two)->insertAfter('InvalidClass', $three);
 
         $this->assertCount(3, $queue);
-        $this->assertSame($one, $queue->current()->getCallable());
+        $this->assertInstanceOf(SampleMiddleware::class, $queue->current());
         $queue->next();
         $this->assertSame($two, $queue->current()->getCallable());
         $queue->next();
         $this->assertSame($three, $queue->current()->getCallable());
     }
+
+    /**
+     * @deprecated
+     */
+    public function testAddingDeprecatedDoublePassMiddleware()
+    {
+        $queue = new MiddlewareQueue();
+        $cb = function ($request, $response, $next) {
+            return $next($request, $response);
+        };
+        $queue->add($cb);
+        $this->deprecated(function () use ($queue, $cb) {
+            $this->assertSame($cb, $queue->current()->getCallable());
+        });
+    }
 }

tests/TestCase/Http/RunnerTest.php

@@ -39,13 +39,13 @@ class RunnerTest extends TestCase
 
         $this->queue = new MiddlewareQueue();
 
-        $this->ok = function ($req, $res, $next) {
-            return $next($req, $res);
+        $this->ok = function ($request, $handler) {
+            return $handler->handle($request);
         };
-        $this->pass = function ($req, $res, $next) {
-            return $next($req, $res);
+        $this->pass = function ($request, $handler) {
+            return $handler->handle($request);
         };
-        $this->fail = function ($req, $res, $next) {
+        $this->fail = function ($request, $handler) {
             throw new RuntimeException('A bad thing');
         };
     }
@@ -73,20 +73,20 @@ class RunnerTest extends TestCase
     public function testRunSequencing()
     {
         $log = [];
-        $one = function ($req, $handler) use (&$log) {
+        $one = function ($request, $handler) use (&$log) {
             $log[] = 'one';
 
-            return $handler->handle($req);
+            return $handler->handle($request);
         };
-        $two = function ($req, $res, $next) use (&$log) {
+        $two = function ($request, $handler) use (&$log) {
             $log[] = 'two';
 
-            return $next($req, $res);
+            return $handler->handle($request);
         };
-        $three = function ($req, $res, $next) use (&$log) {
+        $three = function ($request, $handler) use (&$log) {
             $log[] = 'three';
 
-            return $next($req, $res);
+            return $handler->handle($request);
         };
         $this->queue->add($one)->add($two)->add($three);
         $runner = new Runner();

tests/TestCase/Http/ServerTest.php

@@ -304,10 +304,10 @@ class ServerTest extends TestCase
         $called = false;
 
         $server->getEventManager()->on('Server.buildMiddleware', function (EventInterface $event, MiddlewareQueue $middlewareQueue) use (&$called) {
-            $middlewareQueue->add(function ($req, $res, $next) use (&$called) {
+            $middlewareQueue->add(function ($request, $handler) use (&$called) {
                 $called = true;
 
-                return $next($req, $res);
+                return $handler->handle($request);
             });
             $this->middlewareQueue = $middlewareQueue;
         });

tests/TestCase/Routing/Middleware/RoutingMiddlewareTest.php

@@ -272,15 +272,15 @@ class RoutingMiddlewareTest extends TestCase
     public function testInvokeScopedMiddleware()
     {
         Router::scope('/api', function (RouteBuilder $routes) {
-            $routes->registerMiddleware('first', function ($req, $res, $next) {
+            $routes->registerMiddleware('first', function ($request, $handler) {
                 $this->log[] = 'first';
 
-                return $next($req, $res);
+                return $handler->handle($request);
             });
-            $routes->registerMiddleware('second', function ($req, $res, $next) {
+            $routes->registerMiddleware('second', function ($request, $handler) {
                 $this->log[] = 'second';
 
-                return $next($req, $res);
+                return $handler->handle($request);
             });
             $routes->registerMiddleware('dumb', DumbMiddleware::class);
 
@@ -315,15 +315,15 @@ class RoutingMiddlewareTest extends TestCase
     public function testInvokeScopedMiddlewareReturnResponse()
     {
         Router::scope('/', function (RouteBuilder $routes) {
-            $routes->registerMiddleware('first', function ($req, $res, $next) {
+            $routes->registerMiddleware('first', function ($request, $handler) {
                 $this->log[] = 'first';
 
-                return $next($req, $res);
+                return $handler->handle($request);
             });
-            $routes->registerMiddleware('second', function ($req, $res, $next) {
+            $routes->registerMiddleware('second', function ($request, $handler) {
                 $this->log[] = 'second';
 
-                return $res;
+                return new Response();
             });
 
             $routes->applyMiddleware('first');
@@ -356,15 +356,15 @@ class RoutingMiddlewareTest extends TestCase
     public function testInvokeScopedMiddlewareReturnResponseMainScope()
     {
         Router::scope('/', function (RouteBuilder $routes) {
-            $routes->registerMiddleware('first', function ($req, $res, $next) {
+            $routes->registerMiddleware('first', function ($request, $handler) {
                 $this->log[] = 'first';
 
-                return $res;
+                return new Response();
             });
-            $routes->registerMiddleware('second', function ($req, $res, $next) {
+            $routes->registerMiddleware('second', function ($request, $handler) {
                 $this->log[] = 'second';
 
-                return $next($req, $res);
+                return $handler->handle($request);
             });
 
             $routes->applyMiddleware('first');
@@ -401,15 +401,15 @@ class RoutingMiddlewareTest extends TestCase
     public function testInvokeScopedMiddlewareIsolatedScopes(string $url, array $expected)
     {
         Router::scope('/', function (RouteBuilder $routes) {
-            $routes->registerMiddleware('first', function ($req, $res, $next) {
+            $routes->registerMiddleware('first', function ($request, $handler) {
                 $this->log[] = 'first';
 
-                return $next($req, $res);
+                return $handler->handle($request);
             });
-            $routes->registerMiddleware('second', function ($req, $res, $next) {
+            $routes->registerMiddleware('second', function ($request, $handler) {
                 $this->log[] = 'second';
 
-                return $next($req, $res);
+                return $handler->handle($request);
             });
 
             $routes->scope('/api', function (RouteBuilder $routes) {

tests/test_app/Plugin/TestPlugin/src/Plugin.php

@@ -31,8 +31,8 @@ class Plugin extends BasePlugin
 
     public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue
     {
-        $middlewareQueue->add(function ($req, $res, $next) {
-            return $next($req, $res);
+        $middlewareQueue->add(function ($request, $handler) {
+            return $handler->handle($request);
         });
 
         return $middlewareQueue;

tests/test_app/TestApp/Application.php

@@ -63,11 +63,8 @@ class Application extends BaseApplication
      */
     public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue
     {
-        $middlewareQueue->add(function ($req, $res, $next) {
-            /** @var \Cake\Http\ServerRequest $res */
-            $res = $next($req, $res);
-
-            return $res->withHeader('X-Middleware', 'true');
+        $middlewareQueue->add(function ($request, $handler) {
+            return $handler->handle($request)->withHeader('X-Middleware', 'true');
         });
         $middlewareQueue->add(new ErrorHandlerMiddleware(Configure::read('Error', [])));
         $middlewareQueue->add(new RoutingMiddleware($this));

tests/test_app/TestApp/Http/EventApplication.php

@@ -18,8 +18,6 @@ use Cake\Console\CommandCollection;
 use Cake\Event\EventManagerInterface;
 use Cake\Http\BaseApplication;
 use Cake\Http\MiddlewareQueue;
-use Psr\Http\Message\ResponseInterface;
-use Psr\Http\Message\ServerRequestInterface;
 use TestApp\Command\DemoCommand;
 
 class EventApplication extends BaseApplication
@@ -41,9 +39,4 @@ class EventApplication extends BaseApplication
     {
         return $commands->addMany(['ex' => DemoCommand::class]);
     }
-
-    public function __invoke(ServerRequestInterface $req, ResponseInterface $res, callable $next): ResponseInterface
-    {
-        return $res;
-    }
 }

tests/test_app/TestApp/Http/MiddlewareApplication.php

@@ -18,24 +18,20 @@ class MiddlewareApplication extends BaseApplication
     public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue
     {
         $middlewareQueue
-            ->add(function ($req, $res, $next) {
-                $res = $next($req, $res);
-
-                return $res->withHeader('X-First', 'first');
+            ->add(function ($request, $handler) {
+                return $handler->handle($request)->withHeader('X-First', 'first');
             })
-            ->add(function ($req, $res, $next) {
-                $res = $next($req, $res);
-
-                return $res->withHeader('X-Second', 'second');
+            ->add(function ($request, $handler) {
+                return $handler->handle($request)->withHeader('X-Second', 'second');
             })
-            ->add(function ($req, $res, $next) {
-                $res = $next($req, $res);
+            ->add(function ($request, $handler) {
+                $response = $handler->handle($request);
 
-                if ($req->hasHeader('X-pass')) {
-                    $res = $res->withHeader('X-pass', $req->getHeaderLine('X-pass'));
+                if ($request->hasHeader('X-pass')) {
+                    $response = $response->withHeader('X-pass', $request->getHeaderLine('X-pass'));
                 }
 
-                return $res->withHeader('X-Second', 'second');
+                return $response->withHeader('X-Second', 'second');
             });
 
         return $middlewareQueue;

tests/test_app/TestApp/Middleware/DumbMiddleware.php

@@ -18,14 +18,16 @@ namespace TestApp\Middleware;
 
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Server\MiddlewareInterface;
+use Psr\Http\Server\RequestHandlerInterface;
 
 /**
  * Testing stub for middleware tests.
  */
-class DumbMiddleware
+class DumbMiddleware implements MiddlewareInterface
 {
-    public function __invoke(ServerRequestInterface $req, ResponseInterface $res, callable $next)
+    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
     {
-        return $next($req, $res);
+        return $handler->handle($request);
     }
 }

tests/test_app/TestApp/Middleware/SampleMiddleware.php

@@ -16,12 +16,18 @@ declare(strict_types=1);
  */
 namespace TestApp\Middleware;
 
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Server\MiddlewareInterface;
+use Psr\Http\Server\RequestHandlerInterface;
+
 /**
  * Testing stub for middleware tests.
  */
-class SampleMiddleware
+class SampleMiddleware implements MiddlewareInterface
 {
-    public function __invoke(ServerRequestInterface $req, ResponseInterface $res, callable $next)
+    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
     {
+        return $handler->handle($request);
     }
 }

tests/test_app/TestApp/Middleware/ThrowsExceptionMiddleware.php

@@ -19,13 +19,15 @@ namespace TestApp\Middleware;
 use Cake\Http\Exception\ForbiddenException;
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Server\MiddlewareInterface;
+use Psr\Http\Server\RequestHandlerInterface;
 
 /**
  * Testing stub for middleware tests.
  */
-class ThrowsExceptionMiddleware
+class ThrowsExceptionMiddleware implements MiddlewareInterface
 {
-    public function __invoke(ServerRequestInterface $req, ResponseInterface $res, callable $next)
+    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
     {
         throw new ForbiddenException('Sample Message');
     }