Add notes about closing streams after use (#3128)

[andrewnicols]

As noted in #3128, it would be helpful to add a note about the need to close streams after using them. Failure to do so can cause issues, particularly on Windows.

[GrahamCampbell]

Streams are, in general, closed automatically https://github.com/guzzle/psr7/blob/2.5.0/src/Stream.php#L69-L75, unless they stay referenced by your code or a previous response middleware.

[andrewnicols]

Hi @GrahamCampbell ,

Thanks for your reply on this.

Whilst this may be the intent, something is preventing this from working properly on Windows. See the following testcase and it's GHA Run.

In this test I'm creating a file using file_put_contents(), obtaining a file handle, and then using a Guzzle Client to make a Request. I use Utils::streamFor(fopen(...)) to create the handle and do not store any reference to either the stream, or the file handle.

The first time that the test runs, everything works correctly.
Any subsequent time, it is not possible to create the file using file_put_contents. No reference is kept to either the stream, or the client, within the test code. I believe that happens because the file handle is still open to it.

I've added a second test to the same testcase which is almost identical except that a reference is stored, and is explicitly closed. This test passes on every iteration.

I would also argue that the intended behaviour also should be documented. That is, that a note should be added to explain that the file handle will be closed when the reference to the stream is unset and that, if you keep a handle to the stream, then it will not be closed until you dispose of the handle.