1.. include:: ../../Includes.txt
2
3=======================================================================
4Deprecation: #94316 - HTTP header manipulating methods from HttpUtility
5=======================================================================
6
7See :issue:`94316`
8
9Description
10===========
11
12In order to properly handle PSR-7 response objects, explicit :php:`die()`
13or :php:`exit()` calls, as well as directly manipulating HTTP headers with
14:php:`header()` should be avoided. Therefore following methods from
15:php:`\TYPO3\CMS\Core\Utility\HttpUtility` have been marked as deprecated:
16
17*  :php:`redirect()`
18*  :php:`setResponseCode()`
19*  :php:`setResponseCodeAndExit()`
20
21The TYPO3 Core already provides a couple of possibilities to properly handle
22such events in a PSR-7 conform way. Most of the time, a proper PSR-7 response
23can be passed back to the call stack (request handler). Unfortunately there
24might still be some places, inside the call stack, where it's not possible to
25directly return a PSR-7 response. In such case, the
26:php:`\TYPO3\CMS\Core\Http\PropagateResponseException`
27could be thrown. It will automatically be caught by a PSR-15 middleware and the
28given PSR-7 response will then directly be returned, making any :php:`die()`
29or :php:`exit()` call obsolete.
30
31The usage is as following:
32
33.. code-block:: php
34
35   // Before
36   HttpUtility::redirect('https://example.com', HttpUtility::HTTP_STATUS_303);
37
38   // After
39
40   // Inject PSR-17 ResponseFactoryInterface
41   public function __construct(ResponseFactoryInterface $responseFactory)
42   {
43      $this->responseFactory = $responseFactory
44   }
45
46   // Create redirect response
47   $response = $this->responseFactory
48      ->createResponse(303)
49      ->withAddedHeader('location', 'https://example.com')
50
51   // Return Response directly
52   return $reponse;
53
54   // or throw PropagateResponseException
55   new PropagateResponseException($response);
56
57.. note::
58
59   Throwing exceptions for returning an immediate PSR-7 Response is considered
60   as an intermediate solution only, until it's possible to return PSR-7
61   responses in every relevant place. Therefore, the exception is marked
62   as :php:`@internal` and will most likely vanish again in the future.
63
64Impact
65======
66
67Calling one of those methods will trigger a PHP :php:`E_USER_DEPRECATED` error.
68
69Affected Installations
70======================
71
72All TYPO3 installations calling those methods in custom code. The extension
73scanner will find all usages as strong match.
74
75Migration
76=========
77
78Replace all occurrences in custom extension code. Therefore, create a redirect
79response with the PSR-17 ResponseFactoryInterface, and pass it back to the call
80stack (request handler). In case, it's not possible to directly return a PSR-7
81Response, you can use the :php:`\TYPO3\CMS\Core\Http\PropagateResponseException`
82as an intermediate solution.
83
84.. index:: PHP-API, FullyScanned, ext:core
85