Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:108771
Content-Type: text/plain;
	charset=us-ascii
Mime-Version: 1.0 (Mac OS X Mail 13.0 \(3608.60.0.2.5\))
In-Reply-To: <5ec7b4a7-508b-270b-916f-0504a116196c@gmail.com>
Date: Wed, 26 Feb 2020 10:42:29 -0600
Cc: php internals <internals@lists.php.net>
Content-Transfer-Encoding: quoted-printable
Message-ID: <30112AFF-38F9-44D4-9D2F-03A32019764F@pmjones.io>
References: <50BD013E-CF72-414C-BBC0-A7A2E45CBDDB@pmjones.io>
 <CANUQDCiP31aEqULqeGpN66ESHarKxWuXgQt_CqWeCLZc+1L-fA@mail.gmail.com>
 <5904137.fSVIMsojiJ@mcmic-probook>
 <CDBA02D0-07E1-4723-947C-22B403E650C0@pmjones.io>
 <CA+hqhpcOqCqXuOh3bWavJ+pZ5VVhekUO9LkKgd9c+b98VVnZSA@mail.gmail.com>
 <CAG9XoMRm2Nqjg3UbCc5=1_8m2W7qf8QRoSVk6d_qENJCKE1=9A@mail.gmail.com>
 <fcf43463-f9f7-4235-a84b-658074772ed7@www.fastmail.com>
 <3DDBFBA4-8D3A-46C5-9A10-B093A5E2386B@pmjones.io>
 <54493258-B52E-442A-A11D-82E1D4C7DE5E@gmail.com>
 <8264F6CF-AD55-41E2-9F5A-DAE8942E2B79@pmjones.io>
 <f58eea0a-6d71-be57-c0b8-abc4321cdb38@gmail.com>
 <1BF3D29A-04C6-4A82-9216-EAE991A38916@pmjones.io>
 <10388b3a-3402-a6dc-3837-b03d735edf46@gmail.com>
 <CE336F26-F119-49E6-BD7E-43B47B7F4463@pmjones.io>
 <5ec7b4a7-508b-270b-916f-0504a116196c@gmail.com>
To: Rowan Tommins <rowan.collins@gmail.com>
Subject: Re: [PHP-DEV] RFC: Server-Side Request and Response Objects (v2)
From: pmjones@pmjones.io ("Paul M. Jones")

Hi Rowan,

> On Feb 24, 2020, at 15:47, Rowan Tommins <rowan.collins@gmail.com> =
wrote:
>=20
> Hi Paul,
>=20
> I left this thread to settle a bit, because I felt we were going round =
in circles a bit. I think there's some fundamental differences in =
outlook that no amount of discussion is going to resolve, so I've =
trimmed this reply to the more specific points.

I appreciate you taking the trouble; thanks.


>> Which is the purpose of the documentation; it describes the =
differences between $files and $uploads.
>=20
> That's no reason not to *try* for descriptive names, though. I presume =
the idea is that one array is expected to be more useful for new code, =
and the other is mostly there for compatibility with old code? If so, =
perhaps the names could reflect that somehow.

Your presumption is correct! And your point on trying for better names =
is well-taken -- though I think these are "expected" names, based on my =
research into existing implementations. The most-common names are ...

- the word "files" for unparsed or unmodified $_FILES values, leading me =
to think $files is well-understood

- the words "upload(s)", "fileUpload(s)", or "uploadedFile(s)" for =
parsed, transformed, or restructured $_FILES values, leading me to think =
$uploads is well-understood

And the current users of the 1.x version have not reported confusion or =
trouble with the names as they are.

Having said that, I am open to suggestion here. What names do you think =
would be better than the ones presented, contra pre-existing work from =
other authors?


> Incidentally, the current documentation doesn't describe the =
differences particularly well, just saying one is "more like $_POST". =
Some details of the structure, or examples comparing the two arrays, =
would be useful.

Good call! On your suggestion, I have added details at =
<https://github.com/pmjones/ext-request#the-uploads-array>.  Suggestions =
for improvement are welcome.


>>> I was actually thinking of the opposite: given a request body which =
didn't come from global state, but which contains data in =
multipart/form-data format, extract the key-value pairs and attached =
files.
>> Is that something PHP "itself" already does? If not, I have to =
consider it out-of-scope for this RFC.
>=20
>=20
> a) Yes: Every time you submit a form as multipart/form-data, PHP =
parses it into the global state. If this object is aiming to abstract =
away from global state, then having a non-global-state parser for that =
seems consistent.
>=20
> b) No: There is no function which currently takes a string and returns =
an array for this scenario. However, that's true of other features you =
have included, such as parsing accept headers, or even extracting just =
HTTP headers from a copy of the $_SERVER array.

Quite a lot packed into four sentences; I'll try to address all of it.

- First off, "yes and no" is a great answer, the most-accurate one =
possible. It highlights what I'm getting at: PHP transforms the content =
body into $_POST under some circumstances but not others. The RFC =
proposes to honor that existing PHP behavior.

- "If this object is aiming to abstract away from global state" -- well, =
global *mutable* state, anyway, per our last exchange (and noted again =
below).

- "There is no function which currently takes a string and returns an =
array for this scenario." -- True, though (and not to undermine my own =
case) there is json_decode(), which can return an array. But then the =
trouble is how to decide when to apply it, and with what parameters, and =
how to trap & report errors, etc., all of which adds complexity to what =
I think ought to be a simple object. And then once special treatment is =
given to JSON, what about XML? Etc., etc. Given all that, it strikes me =
that the cases not already served by PHP for parsing the body content =
into $_POST are best left to consumers of ServerRequest.

- "However, that's true of other features you have included" -- also =
true, though those are informed by research into existing =
implementations, and provide what appear to be commonly- or =
frequently-needed values and structures. (You may opine this is =
contradictory, in which case I will respond as Whitman: "Do I contradict =
myself? Very well, then I contradict myself. I am large, I contain =
multitudes." ;-)


>> Your point on global state is well-taken; I will try to remember in =
future to phrase it as "global *mutable* state." (AFAICT, php://input is =
not mutable, though as you correctly point out, it is global.)
>=20
> This distinction seems unnecessary. Once created, the object avoids =
global state because it is self-contained, and the fact that it's =
read-only is a separate attribute. We're really just talking about ways =
to construct that self-contained state, and "everything from global =
state" or "nothing from global state" seem like more natural options =
than "one thing from global state, everything else not".

I agree that the default $content value is an exception to everything =
else in ServerRequest. While it stays read-only, it does get read from =
php://input each time you refer to it.

The alternative is to read from php://input once at construction time =
(when the construct $content argument is null) and retain that value in =
$content from the start. But in that case, when you have very large =
content bodies (as when there are PUT file uploads or other large =
payloads), then ServerRequest takes up a lot of memory, when it might =
not ever be used directly. Yes, "it might never be used" could be true =
of every element on ServerRequest, but the maximum memory use for those =
other elements tends to be rather smaller.

In the end, letting $content read from php://input on the fly is a =
reasonable tradeoff; an exception that tests the rule, if you will.

Over to you!


--=20
Paul M. Jones
pmjones@pmjones.io
http://paul-m-jones.com

Modernizing Legacy Applications in PHP
https://leanpub.com/mlaphp

Solving the N+1 Problem in PHP
https://leanpub.com/sn1php