Main goal

My main goal was to allow a route, where the response is based on "query string".

A possible solution

The only way to accomplish this was to add a route with a handler.

$builder->addRoute(
    'GET', '/country/IT', static function (ServerRequestInterface $request): Response {
        if (...) {
            return new Response(200, [], '{"id":"+39","code":"IT","name":"Italy"}');
        }

        if (...) {
            return new Response(200, [], '{"id":"+49","code":"DE","name":"Germany"}');
        }

       ....
    }
);

Pros

Already possible

Cons

1. There is no way to build response out of files/strings
2. A lot of repetitive code

An alternative solution

A route builder could give the possibility to define the route incrementally (add the method, then the HTTP status, then the response, and so on...).

$route = $builder
            ->withMethod('GET')
            ->withPath('/country')
            ->withResponse(new Response(123))
            ->build();

Add this point I should consider a method to add a conditional response, something like:

->withConditionalResponse('page=2&code=it', new Response(200, [], '{"id":"+39","code":"IT","name":"Italy"}'))

Since I don't want the developer to use at the same time withResponse and withConditionalResponse I created to separated builders:

1. RouteBuilder
2. ConditionalRouteBuilder

Final solution

It's not important how many parameters the request has in the query string, and not even the order, each conditional-response will try to match only the specified params/values.

$builder = new ConditionalRouteBuilder(
            Psr17FactoryDiscovery::findResponseFactory(),
            Psr17FactoryDiscovery::findStreamFactory(),
        );

        $route = $builder->withMethod('GET')
            ->withPath('/country')
            ->withConditionalResponse('page=2&code=it', new Response(201))
            ->withConditionalResponse('code=de', new Response(301))
            ->withConditionalResponse('page=4', new Response(401))
            ->withDefaultNotFoundResponse(new Response(123))
            ->build();

        $response = $route->getHandler()(new Request('GET', '/country?nonce=12345&code=fr&page=3'));

The debug could also show each request and answer, including headers as follows:

> GET /get HTTP/1.1
Host: httpbin.org
User-Agent: Guzzle/4.0-dev curl/7.21.4 PHP/5.5.8

< HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/json
Date: Tue, 25 Mar 2014 03:53:27 GMT
Server: gunicorn/0.17.4
Content-Length: 270
Connection: keep-alive

{
  "headers": {
    "Connection": "close",
    "X-Request-Id": "3d0f7d5c-c937-4394-8248-2b8e03fcccdb",
    "User-Agent": "Guzzle/4.0-dev curl/7.21.4 PHP/5.5.8",
    "Host": "httpbin.org"
  },
  "origin": "76.104.247.1",
  "args": {},
  "url": "http://httpbin.org/get"
}

> HEAD /get HTTP/1.1
Host: httpbin.org
User-Agent: Guzzle/4.0-dev curl/7.21.4 PHP/5.5.8

< HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-length: 270
Content-Type: application/json
Date: Tue, 25 Mar 2014 03:53:27 GMT
Server: gunicorn/0.17.4
Connection: keep-alive

Goal

The goal is to simulate a timeout for a certain request in a test.

First solution: sleep for n seconds

A handler with that "sleep" for n seconds, where n > default timeout, I thought it was enough, but apparently, in case of timeout, the client will throw an error.

Second solution: a response with an exception

Having a more generic route with an exception will cover also the timeout scenario. This is a specific example for guzzle:

$rb->new()
         ->withMethod('GET')
         ->withPath('/slow/api')
         ->withException(new ConnectException(
                  'Timed out after 30 seconds',
                  new Request('GET', '/slow/api')
         ))
         ->build()

League's $router->map always rewrites the route to an absolute path. I've added that logic to the createServerRequest so relative routes can now be supported.