PHP: rfc:apache_tail_request

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== New apache_tail_request() function ======
  * Version: 0.9
  * Date: 2015-03-25
  * Author: Patrick Schaaf, php@bof.de
  * Status: Draft
  * First Published at: http://wiki.php.net/rfc/apache_tail_request

===== Introduction =====

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 [[http://php.net/manual/en/function.virtual.php|virtual()]] function, proving a safer way to handle most of its use cases.

===== Proposal =====

A new function is proposed:

<code php>
bool apache_tail_request(string $uri)
</code>

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 [[http://php.net/manual/en/function.apache-lookup-uri.php|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.

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

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.

===== Proposed PHP Version(s) =====

The function is proposed to be added to all currently maintained PHP versions, at the
discretion of the respective release managers.

===== RFC Impact =====

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.

===== Open Issues =====

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:
  * return a stdClass object, like apache_lookup_uri() does, on success
  * when called without an URI argument, return the currently registered tail request
  * when called with a **false** URI argument, cancel the currently registered tail request

===== Proposed Voting Choices =====
If voting is required, it will probably need a 50%+1 majority.

===== Patches and Tests =====
There is a [[http://bei.bof.de/php/sapi_apache2.noreentry.v3.patch|proof of concept]] implementation, as a patch against PHP 5.6.7

The existing [[http://php.net/manual/en/function.virtual.php|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 [[http://bugs.php.net/bug.php?id=68486|PHP Bug #68486 Investigation]]

===== Implementation =====

===== References =====

===== Rejected Features =====
Page Tools
