New HTTP Cache Method

[EG-Mohamed]

I would like to propose adding opt-in response caching to Laravel's HTTP Client.

Problem

When consuming external APIs, it is common to cache stable GET responses to reduce network calls, avoid rate limits, and improve performance.

Today this usually requires wrapping HTTP requests manually:

$response = Cache::remember('products-api', 600, function () {
    return Http::get('https://api.example.com/products');
});

This works, but it separates cache behavior from the HTTP request definition.

Proposed API

$response = Http::cache('products-api', 600)
    ->get('https://api.example.com/products');

$response->fromCache(); // true or false

For stale-while-revalidate caching, an array TTL would use Laravel's existing Cache::flexible() behavior:

$response = Http::cache('products-api', [60, 300])
    ->get('https://api.example.com/products');

Design

The cache key is mandatory:

Http::cache(string $key, DateTimeInterface|DateInterval|int|array $ttl)

Making the key mandatory keeps the feature explicit and avoids the risk of automatically generating unsafe or surprising cache keys.

Default behavior

• Only GET requests are cached by default.
• Only successful responses are cached by default.
• Failed responses are not cached by default.
• Non-GET requests are not cached by default.
• If the TTL is an array, the HTTP Client uses Cache::flexible().
• If the TTL is not an array, the HTTP Client uses normal cache behavior.
• The returned response exposes fromCache() to determine if it was served from cache.

Example

$response = Http::cache('github-releases', [60, 300])
    ->get('https://api.github.com/repos/laravel/framework/releases');

if ($response->fromCache()) {
    // Response was served from cache.
}

Scope

The first implementation would intentionally avoid advanced features such as cache tags, automatic key generation, custom invalidation, stale lock customization, or POST request caching.

The goal is to provide a small, explicit, Laravel-style API for the common case of caching successful external GET responses.

[EG-Mohamed]

I have opened a PR with an initial implementation here:

#60454

Happy to adjust the API or implementation based on maintainer feedback.

[Cellard]

What if response carries Cache-Control headers?

Take a look on kevinrob/guzzle-cache-middleware
It provides a guzzle middleware that handles Cache-Control response headers to manage local cache. And it allows to setup fallback caching strategy too.