PHP: rfc:http-last-response-headers

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== PHP RFC: Add http_(get|clear)_last_response_headers() function ======

  * Version: 0.2
  * Date: 2024-01-03
  * Author: Gina Peter Banyard <girgias@php.net>
  * Status: Implemented in PHP 8.4: https://github.com/php/php-src/commit/47a199c8b43dbf84e66ff6b63f665541ab4eb1d0
  * Target Version: PHP 8.4
  * Implementation: [[https://github.com/php/php-src/pull/12500|https://github.com/php/php-src/pull/12500]]
  * First Published at: [[rfc:http-last-response-headers|http://wiki.php.net/rfc/http-last-response-headers]]

===== Introduction =====

The [[https://www.php.net/manual/en/reserved.variables.httpresponseheader.php|$http_response_header]]
variable is magically created in the local scope whenever an HTTP request is performed through PHP's stream layer,
i.e. when using the [[https://www.php.net/manual/en/wrappers.http.php|HTTP wrapper]].
One such usage is using <php>file_get_contents()</php> to retrieve the content of a URL.

The [[https://www.php.net/manual/en/reserved.variables.httpresponseheader.php|$http_response_header]]
variable will contain all the HTTP headers that were encountered during the request performed via the HTTP wrapper.

All other features using this operating principle,
such as [[https://www.php.net/manual/en/reserved.variables.phperrormsg.php|$php_errormsg]],
have been removed because creating a variable in the local scope is a terrible way of returning additional information.
This variable itself was initially slated [[rfc:deprecations_php_8_1#predefined_variable_http_response_header|to be deprecated in PHP 8.1]],
but due to a lack of convenient alternatives, it was removed from the proposal at that time.

This variable is created and populated even if the HTTP request fails,
a behaviour that requires dropping down to the stream layer, providing an additional
stream context to ignore errors.
Subsequently, the user can manually parse the response header and detect if the HTTP request failed or not.
This is impractical and a better interface would be simply checking if the return value of the initial call was <php>false</php>.

As a replacement, we propose adding functions similar to <php>error_get_last()</php>/<php>error_clear_last()</php> which replaced
[[https://www.php.net/manual/en/reserved.variables.phperrormsg.php|$php_errormsg]].

===== Motivation =====

The primary motivation for adding this function, is to be able to remove the [[https://www.php.net/manual/en/reserved.variables.httpresponseheader.php|$http_response_header]]
variable completely. To create this variable one needs to use the <php>zend_set_local_var_str()</php> engine function.
This is also the last usage of this engine function and its sibling function <php>zend_set_local_var()</php>.

Moreover, this variable needs to be special cased in the optimizer/JIT
(via the <php>HTTP_RESPONSE_HEADER_ALIAS</php> enum case of <php>zend_ssa_alias_kind</php>).
Which means that any extension that would use this engine API would misbehave under opcache.

See the [[rfc:http-last-response-headers#backward_incompatible_changes|Backward Incompatible Changes]]
section for an impact analysis of the removal of this feature.

===== Proposal =====

Add the following two functions:
  * <php>function http_get_last_response_header(): ?array</php>
  * <php>function http_clear_last_response_header(): void</php>

<php>http_get_last_response_header()</php> would provide the same information as
[[https://www.php.net/manual/en/reserved.variables.httpresponseheader.php|$http_response_header]]
if a request via the HTTP wrapper is made, and also return the headers as an array even when the request fails.
If no request via the HTTP wrapper is made, or the last headers have been cleared by calling
<php>http_clear_last_response_header()</php>, then <php>null</php> is returned.

===== Backward Incompatible Changes =====

As this RFC does not yet propose deprecating
[[https://www.php.net/manual/en/reserved.variables.httpresponseheader.php|$http_response_header]]
there are no backward incompatible changes.

Considering the possible simplification to the engine and the optimizer by removing
this last usage of the capability to create a variable in this way, we have conducted a usage analysis of the feature.
We found only 65 usages in 30 projects across a sample of over 900 projects
(composer packages, standalone open source projects, and private codebases) which were analyzed with [[https://www.exakat.io|Exakat]]. [1]
Most of those usages stem from packages like Guzzle or OAuth client libraries.

It is impossible to polyfill this feature, however it is possible to write cross version compatible code
in the following way:
<PHP>
$content = file_get_contents('http://example.com/');
if (function_exists('http_get_last_response_headers')) {
    $http_response_header = http_get_last_response_headers();
}
// Use $http_response_header as before
</PHP>

Considering the sparse usage of this feature, the possibility to write cross version compatible code,
and the possible engine and optimizer simplifications,
it seems reasonable to slate this feature for removal even without a deprecation notice if the need arises.

===== Rejected ideas =====

One suggested idea was to provide those headers via a by-reference entry to the stream context.
This idea was rejected by us, and other members of the PHP Foundation,
as we wish to maintain stream contexts as a stateless configuration data structure passed to the stream.

This one-to-one feature replacement does not prevent the introduction of a more generic solution for other stream wrappers.
And this pair of new functions can always be slated for future deprecation and removal.

===== Version =====

Next minor version, PHP 8.4.

===== Vote =====

As per the voting RFC a yes/no vote with a 2/3 majority is needed for this proposal to be accepted.

Voting started on 2024-01-29 and will end on 2024-02-14.
 
<doodle title="Accept Add http_(get|clear)_last_response_headers() function RFC?" auth="girgias" voteType="single" closed="true">
   * Yes
   * No
</doodle>

===== References =====

[1] https://gist.github.com/exakat/454e503458e231dc0695837ad2561540
Page Tools
