[11.x] Add resource() method to Illuminate\Http\Client\Response

[einar-hansen]

This PR introduces a new resource() method to the Response class in Laravel. This method allows users to directly obtain a PHP stream resource from the response body, simplifying workflows that involve stream operations.

Motivation
Working with stream resources in Laravel, especially when dealing with external services or large datasets, can sometimes be verbose and require multiple steps. This new method aims to simplify this process, making it more intuitive and reducing the amount of boilerplate code needed.

Changes

• Added a new resource() method to the Response class.
• Implemented a corresponding test case to ensure the new functionality works as expected.

New Functionality
The resource() method returns a PHP stream resource from the response body. It uses the amazing GuzzleHttp\Psr7\StreamWrapper that comes with the guzzlehttp/psr7 package, that is required by the framework as a requirement in guzzlehttp/guzzle:

use GuzzleHttp\Psr7\StreamWrapper;

/**
 * Get the body of the response as a PHP stream resource.
 *
 * @return resource
 *
 * @throws \InvalidArgumentException if stream is not readable or writable
 */
public function resource()
{
    return StreamWrapper::getResource($this->response->getBody());
}

Usage Examples

Writing to S3

Before:

use GuzzleHttp\Psr7\StreamWrapper;

$response = Http::get($imageUrl);
Storage::disk('s3')->writeStream(
    'thumbnail.png',
    StreamWrapper::getResource($response->toPsrResponse()->getBody()),
);

After:

$response = Http::get($imageUrl);
Storage::disk('s3')->writeStream('thumbnail.png', $response->resource());

Streaming large JSON responses

My favorite way to work with JSON data from external api's, using halaxa/json-machine.

Before:

use GuzzleHttp\Psr7\StreamWrapper;
use JsonMachine\Items;

$response = Http::get('https://jsonplaceholder.typicode.com/todos/1');
$phpStream = StreamWrapper::getResource($response->toPsrResponse()->getBody());

foreach (Items::fromStream($phpStream) as $key => $value) {
    var_dump($value);
}

After:

use JsonMachine\Items;

$response = Http::get('https://jsonplaceholder.typicode.com/todos/1');

foreach (Items::fromStream($response->resource()) as $key => $value) {
    var_dump($value);
}

I'll make a PR to the docs to include information about the new resource() method.