This RFC is about a new function apache_tail_request(), available for PHP running under the apache2handler SAPI. Using this function, you can request a given URI on your server to be included by Apache after the current PHP request finishes, still in the context of the same client HTTP request.
The new function is similar to the virtual() function, proving a safer way to handle most of its use cases.
A new function is proposed:
bool apache_tail_request(string $uri)
Calling the function requests that the given URI should be included, as an Apache subrequest, after the PHP current script run finishes. The URI is immediately parsed by Apache, similar to what the existing function apache_lookup_uri() does. The resolved subrequest is then stored internally, so that it can be executed when the current script run is done.
If the immediate URI parsing fails, the function returns false, otherwise it returns true.
If the function is called repeatedly, the last URI requested will be run, and a warning will be shown telling you that a previous request was overruled.
Apart from clashing with a hypothetical user defined function named apache_tail_request(), no other backward incompatible changes are anticipated.
There are some BC issues associated with the current proof-of-concept patch; see below.
The function is proposed to be added to all currently maintained PHP versions, at the discretion of the respective release managers.
The function is added to the apache2handler SAPI as a single C level function, and a small number of lines added to the base php_handler function. The impact on code complexity is minimal.
No other SAPI is affected.
There is no impact to existing extensions, no added constants, php.ini directives, or anything else.
The current implementation fails to flush output of the currently running script before running the subsequent request / showing that request's output. User code can explicitly call ob_flush() to effect such a flush, before terminating the current script.
The current implementation forces the HTTP status of the original request to be sent to the client; the tail request cannot modify the HTTP status, and probably cannot modify any other header, either.
It is tempting to complicate the function usage a bit:
If voting is required, it will probably need a 50%+1 majority.
There is a proof of concept implementation, as a patch against PHP 5.6.7
The existing virtual() function is modified by the present proof-of-concept implementation, to no longer enable running a virtual PHP script as a subrequest. This change is not part of this RFC proposal, and will be remedied before the RFC leaves the draft phase.
Also, all other PHP interpreter reentry cases are disabled by the present proof-of-concept patch, due to it being the result of an ongoing PHP Bug #68486 Investigation