Add Message cloner

[joelwurtz]

Q	A
Bug fix?	no
New feature?	yes
BC breaks?	no
Deprecations?	no
Related tickets	mentioned in #46
Documentation	Does the phpdoc is enough ?
License	MIT

What's in this PR?

Add a class to copy a request including it's body

Why?

IMO cloning a request with its stream his something that is shared by some concepts (like logging, caching, ....)

Example Usage

$cloner = new MessageCloner();

$clonedResponse = $cloner->cloneMessage($response);

// If original stream is not seekable, cloned it a second time to ensure that we can read it
if (!$response->getBody()->isSeekable()) {
    $response = $cloner->cloneMessage($clonedResponse);
}

Checklist

• Updated CHANGELOG.md to describe new feature
• Documentation pull request created
• Add a plugin "EnsureSeekable" : Goal is to have a plugin that ensure that the body of a request or response is always seekable.

[sagikazarmark]

Can you add type hints here too for internal usage?

[sagikazarmark]

What about memory usage in case of huge bodies? We should add a warning somewhere about that.

[joelwurtz]

It's in the header of the MemoryClonedStream, by default it use a php://temp stream with a 2mb memory buffer, so the memory footprint of a cloned stream will, by default, have a max memory size of 2mb, when the body is higher, all data over the limit is written into a file.

[Nyholm]

I like this. It could help on all the places we do some ugly hack to rewind streams and make sure they are seekable.

@joelwurtz could you address the comments?

[Nyholm]

Same here

[joelwurtz]

Finally i'm not a fan of this implementation, message cloner is useless and the cloned stream enforce stream reading where i'm not a fan, will do a better implementation for the wanted use case.