Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:97461
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain gmail.com designates 209.85.161.171 as permitted sender)
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: quoted-printable
Mime-Version: 1.0 (Mac OS X Mail 10.2 \(3259\))
Message-ID: <0D388F9E-98FA-4C1F-95FA-759C4D4731C6@gmail.com>
Date: Fri, 23 Dec 2016 11:52:12 -0600
To: PHP Internals List <internals@lists.php.net>
Subject: [RFC] ServerRequest and ServerResponse objects
From: pmjones88@gmail.com (Paul Jones)

Hi all,

I have prepared an RFC on server-side request and response objects:

    wiki.php.net/rfc/request_response

This extension provides server-side request and response objects for =
PHP. These are not HTTP message objects proper. They are more like =
wrappers for existing global PHP variables and functions, with some =
limited additional convenience functionality.

This extension defines two classes in the global namespace:

- ServerRequest, composed of read-only copies of PHP superglobals and =
some other commonly-used values, with methods for adding =
application-specific request information in immutable fashion.

- ServerResponse, essentially a wrapper around (and buffer for) =
response-related PHP functions, with some additional convenience =
methods, and self-sending capability.

The extension is available as a PECL package for installation and =
testing at:

    pecl.php.net/package/request

I want to point out that I am not the author of the C code for this =
extension; John Boehr has done the work there, and I appreciate it a =
great deal.

When I originally raised this topic in September, there were some =
questions left unanswered from Rowan Collins; I'll try to address them =
below.

* * *

Rowan asked why this would need to be implemented to as an extension or =
built into core: "Does it provide functionality that is hard to =
implement in a userland library?"

It does. Among other things, making public read-only properties is =
difficult and hackish in userland. Making them remain read-only when a =
parent class is extended is (as far as I can tell) impossible. Both of =
those aspects figure prominently in ServerRequest.

* * *

Rowan also asked: "You mention that it is not just an HTTP wrapper, but =
although you mention researching other frameworks, I can't see any =
reference to PSR-7. What do you see as the relationship between your =
proposal and that standardisation effort?"

While PSR-7 is not a framework, I get your point. ;-) For what it's =
worth, I was a sponsor on that proposal, so I'm relatively familiar with =
its history and purpose.

I see the relationship as complementary. Those who want something that =
matches a formal HTTP model more closely can use one of the two popular =
PSR-7 implementations, or write their own.  Or they can use `pecl_http`, =
for that matter, which I think PSR-7 ends up mimicking in significant =
ways.

Those who want something that more closely matches core PHP =
functionality, or the way-of-working presented by many extant frameworks =
and libraries, might find this extension more in line with their needs. =
I certainly do.

* * *

Finally, Rowan brought this up: "Why is [ServerRequest] property-only, =
but [ServerResponse] method-only? The asymmetry feels awkward to me."

I get why that would be. It's really an outgrowth of the asymmetry that =
already exists in PHP: $_GET, $_POST, et al. are properties representing =
the request, whereas header(), setcookie(), et al. are all functions for =
sending a response.

Having said that, practical use of ServerRequest the intervening time =
has given rise to some methods for application-related convenience. The =
methods withUrl(), withInput(), and the various withParams() methods =
allow changing of immutable public properties on a clone of =
ServerRequest.

(As a side note, immutability here is relatively strict. ServerRequest =
allows only null, scalar, and array values in these cases, and =
recursively checks that arrays themselves have only null, scalar, and =
array values.)

* * *

I know it's a busy time of year for everyone, so I expect this =
discussion to go on longer than two weeks.

This is not a language change; my understanding is that means a simple =
majority vote is needed to pass.

Thanks in advance for your comments and criticism.


-- pmj