Deprecation: #94316 - HTTP header manipulating methods from HttpUtility

Description

In order to properly handle PSR-7 response objects, explicit die() or exit() calls, as well as directly manipulating HTTP headers with header() should be avoided. Therefore following methods from \TYPO3\CMS\Core\Utility\HttpUtility have been marked as deprecated:

redirect()
setResponseCode()
setResponseCodeAndExit()

The TYPO3 Core already provides a couple of possibilities to properly handle such events in a PSR-7 conform way. Most of the time, a proper PSR-7 response can be passed back to the call stack (request handler). Unfortunately there might still be some places, inside the call stack, where it's not possible to directly return a PSR-7 response. In such case, the \TYPO3\CMS\Core\Http\PropagateResponseException could be thrown. It will automatically be caught by a PSR-15 middleware and the given PSR-7 response will then directly be returned, making any die() or exit() call obsolete.

The usage is as following:

// Before
HttpUtility::redirect('https://example.com', HttpUtility::HTTP_STATUS_303);

// After

// Inject PSR-17 ResponseFactoryInterface
public function __construct(ResponseFactoryInterface $responseFactory)
{
   $this->responseFactory = $responseFactory
}

// Create redirect response
$response = $this->responseFactory
   ->createResponse(303)
   ->withAddedHeader('location', 'https://example.com')

// Return Response directly
return $reponse;

// or throw PropagateResponseException
throw new PropagateResponseException($response);

Note

Throwing exceptions for returning an immediate PSR-7 Response is considered as an intermediate solution only, until it's possible to return PSR-7 responses in every relevant place. Therefore, the exception is marked as @internal and will most likely vanish again in the future.

Impact

Calling one of those methods will trigger a PHP E_USER_DEPRECATED error.

Affected Installations

All TYPO3 installations calling those methods in custom code. The extension scanner will find all usages as strong match.

Migration

Replace all occurrences in custom extension code. Therefore, create a redirect response with the PSR-17 ResponseFactoryInterface, and pass it back to the call stack (request handler). In case, it's not possible to directly return a PSR-7 Response, you can use the \TYPO3\CMS\Core\Http\PropagateResponseException as an intermediate solution.