1	<?php
2	declare(strict_types=1);
3	/**
4	* Pop PHP Framework (https://www.popphp.org/)
5	*
6	* @link       https://github.com/popphp/popphp-framework
7	* @author     Nick Sagona, III <nick@popphp.org>
8	* @copyright  Copyright (c) 2009-2026 Nick Sagona, III
9	* @license    https://www.popphp.org/license     New BSD License
10	*/
11
12	/**
13	* @namespace
14	*/
15	namespace Pop\Http\Client\Middleware;
16
17	use Psr\Http\Message\RequestInterface;
18	use Psr\Http\Message\ResponseInterface;
19
20	/**
21	* Client middleware interface - a PSR-15-style interceptor for Client's outbound
22	* dispatch. Not a literal PSR-15 implementation: PSR-15's real interfaces are typed
23	* to ServerRequestInterface (server-side only) and cannot apply to a Client's
24	* outbound RequestInterface flow, so this mirrors PSR-15's shape with the request
25	* type swapped.
26	*
27	* @category   Pop
28	* @package    Pop\Http
29	* @author     Nick Sagona, III <nick@popphp.org>
30	* @copyright  Copyright (c) 2009-2026 Nick Sagona, III
31	* @license    https://www.popphp.org/license     New BSD License
32	* @version    6.0.0
33	*/
34	interface MiddlewareInterface
35	{
36
37	/**
38	* Process the request, optionally passing it (or a modified copy) to $handler
39	* to continue the chain, or returning a response directly to short-circuit
40	*
41	* Typed to the broader PSR-7 ResponseInterface for interface parity with
42	* RequestHandlerInterface::handle(), but for use with Pop\Http\Client, the
43	* response returned here (whether from $handler->handle() or a short-circuit)
44	* must be a Pop\Http\Client\Response (or something that satisfies it) -
45	* Client\Response is the concrete type this pipeline's terminal handler and
46	* Client's internals require, not an arbitrary ResponseInterface. Client
47	* enforces this at the end of the pipeline and throws a Client\Exception with
48	* a clear message if it's violated.
49	*
50	* @param  RequestInterface        $request
51	* @param  RequestHandlerInterface $handler
52	* @return ResponseInterface
53	*/
54	public function process(RequestInterface $request, RequestHandlerInterface $handler): ResponseInterface;
55
56	}