feat(router): allow error responses to carry headers

[osbre]

Problem

Returning response with headers works from a controller:

return new Json(body: ['message' => 'Slow down.'], status: Status::TOO_MANY_REQUESTS)
    ->addHeader('Retry-After', '30');

But when using throw HttpRequestFailed to return an error response from a different place, there is no way of passing headers, which leads to a few statuses that can only be sent correctly from inside a controller:

• 429 needs Retry-After, otherwise the client has no idea when to come back
• 401 needs WWW-Authenticate as per RFC 9110; the response is malformed without it
• 405 needs Allow
• (same for custom headers such as X-RateLimit-*)

Solution

HttpRequestFailed gains a headers parameter, and the handler applies it to whatever the renderer returned:

throw new HttpRequestFailed(
    status: Status::TOO_MANY_REQUESTS,
    headers: ['retry-after' => '60'],
);

Values may be a string or a list of strings, so multi-value headers work:

throw new HttpRequestFailed(
    status: Status::METHOD_NOT_ALLOWED,
    headers: ['allow' => ['GET', 'HEAD']],
);

Declared headers replace whatever the renderer set rather than adding to it: they describe the failure, which outranks anything assembled for the body. The lookup is case-insensitive, so a header the renderer spelled Retry-After and a throw site spelling it retry-after resolve to one header rather than two.

This mirrors Symfony's HttpExceptionInterface::getHeaders(), which Laravel reuses and also exposes as abort($status, $message, $headers).

[github-actions]

Benchmark Results

Comparison of feat/failed-request-headers against 3.x (14514adb5b0a78dbb1409751aefa3f6f1b88be53).

Open to see the benchmark results

No benchmark changes above ±5%.

_{Generated by phpbench against commit 356bd6c}

[brendt]

Great, thanks!