Allow cache_flexible() to use a callback (#834)

* Allow cache_flexible() to use a callback

* Rector fix

* Test for ok

* CHANGELOG

* Allow key customization for http client caching

* CHANGELOG

Author: srtfisher

CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+
+### Added
+
+- Added closure support for the stale and expire TTLs in the flexible cache
+  middleware.
+- Added custom cache key support to the HTTP Client cache middleware and flexible cache
+  middleware.
+
 ## v1.14.0
 
 ### Added

rector.php

@@ -20,6 +20,7 @@
 
 use Rector\EarlyReturn\Rector\If_\ChangeOrIfContinueToMultiContinueRector;
 use Rector\EarlyReturn\Rector\Return_\ReturnBinaryOrToEarlyReturnRector;
+use Rector\Php70\Rector\StmtsAwareInterface\IfIssetToCoalescingRector;
 use Rector\Php71\Rector\FuncCall\RemoveExtraParametersRector;
 use Rector\Php80\Rector\Class_\ClassPropertyAssignToConstructorPromotionRector;
 use Rector\Php80\Rector\NotIdentical\StrContainsRector;
@@ -124,4 +125,5 @@
 		FlipTypeControlToUseExclusiveTypeRector::class,
 		FunctionLikeToFirstClassCallableRector::class,
 		RemoveNullArgOnNullDefaultParamRector::class,
+		IfIssetToCoalescingRector::class,
 	] );

src/mantle/http-client/class-cache-flexible-middleware.php

@@ -32,10 +32,11 @@ class Cache_Flexible_Middleware extends Cache_Middleware {
 	/**
 	 * Constructor.
 	 *
-	 * @param int|\DateInterval|\DateTimeInterface $stale Time to consider a cached response stale.
-	 * @param int|\DateInterval|\DateTimeInterface $expire Time to consider a cached response expired.
+	 * @param int|\DateInterval|\DateTimeInterface|\Closure $stale Time to consider a cached response stale.
+	 * @param int|\DateInterval|\DateTimeInterface|\Closure $expire Time to consider a cached response expired.
+	 * @param string|null                                   $key Cache key to use.
 	 */
-	public function __construct( protected int|\DateInterval|\DateTimeInterface $stale, protected int|\DateInterval|\DateTimeInterface $expire ) {}
+	public function __construct( protected int|\DateInterval|\DateTimeInterface|\Closure $stale, protected int|\DateInterval|\DateTimeInterface|\Closure $expire, public readonly ?string $key = null ) {}
 
 	/**
 	 * Invoke the middleware.
@@ -57,7 +58,9 @@ public function __invoke( Pending_Request $request, Closure $next ): Response {
 			if ( $cache->is_stale() ) {
 				$fresh_request = ( clone $request )->without_middleware( Cache_Middleware::class );
 
-				defer( fn () => $this->store_response( $fresh_request->send() ) );
+				defer(
+					fn () => $this->store_response( $fresh_request, $fresh_request->send() ),
+				);
 			}
 
 			$response->cached = true;
@@ -69,15 +72,13 @@ public function __invoke( Pending_Request $request, Closure $next ): Response {
 
 		assert( $response instanceof Response );
 
-		$this->store_response( $response );
+		$this->store_response( request: $request, response: $response );
 
 		return $response;
 	}
 
 	/**
 	 * Retrieve a cached response if available.
-	 *
-	 * @return SWR_Storage|null Cached response or null if not found.
 	 */
 	private function get_cached_response(): ?SWR_Storage {
 		try {
@@ -98,9 +99,18 @@ private function get_cached_response(): ?SWR_Storage {
 	 *
 	 * @throws \InvalidArgumentException If the stale time is not less than the expire time.
 	 *
-	 * @param Response $response Response to store.
+	 * @param Pending_Request $request Request associated with the response.
+	 * @param Response        $response Response to store.
 	 */
-	private function store_response( Response $response ): bool {
+	private function store_response( Pending_Request $request, Response $response ): bool {
+		if ( $this->stale instanceof Closure ) {
+			$this->stale = $this->invoke_expiration_callback( $this->stale, $request, $response );
+		}
+
+		if ( $this->expire instanceof Closure ) {
+			$this->expire = $this->invoke_expiration_callback( $this->expire, $request, $response );
+		}
+
 		$stale_time  = normalize_cache_ttl( $this->stale );
 		$expire_time = normalize_cache_ttl( $this->expire );
 

src/mantle/http-client/class-cache-middleware.php

@@ -26,17 +26,10 @@ class Cache_Middleware {
 	/**
 	 * Constructor.
 	 *
-	 * @throws \InvalidArgumentException If the TTL is not valid.
-	 *
-	 * @param int|DateTimeInterface|callable $ttl Time to live for the cache.
+	 * @param int|DateTimeInterface|Closure $ttl Time to live for the cache.
+	 * @param string|null                   $key Cache key to use.
 	 */
-	public function __construct( protected mixed $ttl ) {
-		if ( ! is_int( $ttl ) && ! $ttl instanceof DateTimeInterface && ! is_callable( $ttl ) ) { // @phpstan-ignore-line
-			throw new \InvalidArgumentException(
-				'TTL must be an integer, DateTimeInterface, or a callable that returns an integer.'
-			);
-		}
-	}
+	public function __construct( protected int|DateTimeInterface|Closure $ttl, public readonly ?string $key = null ) {}
 
 	/**
 	 * Invoke the middleware.
@@ -77,7 +70,7 @@ public function purge( Pending_Request $request ): bool {
 	 * @param Pending_Request $request Request to retrieve the cache key for.
 	 */
 	protected function get_cache_key( Pending_Request $request ): string {
-		return md5( (string) json_encode( [ // phpcs:ignore WordPress.WP.AlternativeFunctions.json_encode_json_encode
+		return $this->key ?? md5( (string) json_encode( [ // phpcs:ignore WordPress.WP.AlternativeFunctions.json_encode_json_encode
 			$request->base_url(),
 			$request->url(),
 			$request->method(),
@@ -89,24 +82,35 @@ protected function get_cache_key( Pending_Request $request ): string {
 	/**
 	 * Calculate the time to live for the cache in seconds.
 	 *
-	 * @throws \InvalidArgumentException If the TTL callback returns an invalid value.
-	 *
 	 * @param Pending_Request $request Request to calculate the TTL for.
 	 * @param Response        $response Response to calculate the TTL for.
 	 */
 	private function calculate_ttl( Pending_Request $request, Response $response ): int {
-		if ( is_callable( $this->ttl ) ) {
-			$callback = $this->ttl;
+		$ttl = $this->ttl;
 
-			$value = $callback( $request, $response );
+		if ( $ttl instanceof Closure ) {
+			$ttl = $this->invoke_expiration_callback( $ttl, $request, $response );
+		}
 
-			if ( ! is_numeric( $value ) || (int) $value < 0 ) {
-				throw new \InvalidArgumentException( 'TTL callback must return a non-negative integer.' );
-			}
+		return normalize_cache_ttl( $ttl );
+	}
+
+	/**
+	 * Invoke the callback with the request and response and validate the return type.
+	 *
+	 * @throws \InvalidArgumentException If the callback does not return an integer or DateTimeInterface.
+	 *
+	 * @param Closure         $callback Callback to invoke.
+	 * @param Pending_Request $request Request to pass to the callback.
+	 * @param Response        $response Response to pass to the callback.
+	 */
+	protected function invoke_expiration_callback( Closure $callback, Pending_Request $request, Response $response ): int|DateTimeInterface {
+		$value = $callback( $request, $response );
 
-			return (int) $value;
+		if ( ! is_int( $value ) && ! $value instanceof DateTimeInterface ) {
+			throw new \InvalidArgumentException( 'Callback must return an integer or DateTimeInterface.' );
 		}
 
-		return normalize_cache_ttl( $this->ttl );
+		return $value;
 	}
 }

src/mantle/http-client/concerns/trait-caches-requests.php

@@ -7,6 +7,7 @@
 
 namespace Mantle\Http_Client\Concerns;
 
+use Closure;
 use DateTimeInterface;
 use InvalidArgumentException;
 use Mantle\Http_Client\Cache_Flexible_Middleware;
@@ -26,13 +27,14 @@ trait Caches_Requests {
 	/**
 	 * Enable caching for the request.
 	 *
-	 * @param int|DateTimeInterface|callable $ttl Time to live for the cache.
-	 * @phpstan-param int|DateTimeInterface|(callable(Pending_Request $request, Response $response): int) $ttl
+	 * @param int|DateTimeInterface|Closure $ttl Time to live for the cache.
+	 * @param string|null                   $key Cache key to use.
+	 * @phpstan-param int|DateTimeInterface|(Closure(Pending_Request $request, Response $response): int|DateTimeInterface) $ttl
 	 */
-	public function cache( int|DateTimeInterface|callable $ttl = 3600 ): static {
+	public function cache( int|DateTimeInterface|Closure $ttl = 3600, ?string $key = null ): static {
 		return $this
 			->filter_middleware( fn ( callable $middleware ) => ! $middleware instanceof Cache_Middleware )
-			->prepend_middleware( new Cache_Middleware( $ttl ) );
+			->prepend_middleware( new Cache_Middleware( $ttl, $key ) );
 	}
 
 	/**
@@ -41,13 +43,17 @@ public function cache( int|DateTimeInterface|callable $ttl = 3600 ): static {
 	 * This will use a stale-while-revalidate strategy to return a cached response if it exists,
 	 * even if it is stale, while refreshing the cache in the background.
 	 *
-	 * @param int|\DateInterval|\DateTimeInterface $stale Time to consider a cached response stale.
-	 * @param int|\DateInterval|\DateTimeInterface $expire Time to consider a cached response expired.
+	 * @param int|\DateInterval|\DateTimeInterface|Closure $stale Time to consider a cached response stale.
+	 * @param int|\DateInterval|\DateTimeInterface|Closure $expire Time to consider a cached response expired.
+	 * @param string|null                                  $key Cache key to use.
+	 *
+	 * @phpstan-param int|DateTimeInterface|(Closure(Pending_Request $request, Response $response): int|DateTimeInterface) $stale
+	 * @phpstan-param int|DateTimeInterface|(Closure(Pending_Request $request, Response $response): int|DateTimeInterface) $expire
 	 */
-	public function cache_flexible( int|\DateInterval|\DateTimeInterface $stale, int|\DateInterval|\DateTimeInterface $expire ): static {
+	public function cache_flexible( int|\DateInterval|\DateTimeInterface|Closure $stale, int|\DateInterval|\DateTimeInterface|Closure $expire, ?string $key = null ): static {
 		return $this
 			->filter_middleware( fn ( callable $middleware ) => ! $middleware instanceof Cache_Middleware )
-			->prepend_middleware( new Cache_Flexible_Middleware( $stale, $expire ) );
+			->prepend_middleware( new Cache_Flexible_Middleware( $stale, $expire, $key ) );
 	}
 
 	/**

tests/HttpClient/CachedHttpClientTest.php

@@ -199,4 +199,73 @@ public function test_it_throws_an_exception_when_passing_a_lower_stale_time_than
 
 		$this->client->get( 'https://example.com' );
 	}
+
+	public function test_it_can_cache_flexible_with_a_callback(): void {
+		$stale_called  = false;
+		$expire_called = false;
+
+		$this->client = Factory::create()->cache_flexible(
+			stale: function ( Pending_Request $request, Response $response ) use ( &$stale_called ): \DateTimeInterface {
+				$stale_called = true;
+
+				$this->assertEquals( 'https://example.com', $request->url() );
+
+				return now()->addHour();
+			},
+			expire: function ( Pending_Request $request, Response $response ) use ( &$expire_called ): \DateTimeInterface {
+				$expire_called = true;
+
+				$this->assertEquals( 'https://example.com', $request->url() );
+
+				return now()->addDay();
+			},
+		);
+
+		$i = 0;
+
+		$this->fake_request( function () use ( &$i ) {
+			$i++;
+
+			return mock_http_response()->with_json( [ 'request' => $i ] );
+		} );
+
+		$this->client->get( 'https://example.com' );
+		$this->client->get( 'https://example.com' );
+
+		$this->assertRequestCount( 1 );
+		$this->assertTrue( $stale_called );
+		$this->assertTrue( $expire_called );
+	}
+
+	public function test_it_can_use_a_custom_cache_key(): void {
+		$this->client = Factory::create()->cache( key: 'custom-cache-key' );
+
+		$this->fake_request( mock_http_response()->with_json( [ 'example' => 'value' ] ) );
+
+		$this->assertEmpty( wp_cache_get( 'custom-cache-key', Cache_Middleware::CACHE_GROUP ) );
+
+		$this->client->get( 'https://example.com' );
+		$this->client->get( 'https://example.com' );
+
+		$this->assertRequestCount( 1 );
+		$this->assertNotEmpty( wp_cache_get( 'custom-cache-key', Cache_Middleware::CACHE_GROUP ) );
+	}
+
+	public function test_it_can_use_a_custom_cache_key_with_flexible_caching(): void {
+		$this->client = Factory::create()->cache_flexible(
+			stale: now()->addHour(),
+			expire: now()->addDay(),
+			key: 'custom-flexible-cache-key',
+		);
+
+		$this->fake_request( mock_http_response()->with_json( [ 'example' => 'value' ] ) );
+
+		$this->assertEmpty( wp_cache_get( 'custom-flexible-cache-key', Cache_Middleware::CACHE_GROUP ) );
+
+		$this->client->get( 'https://example.com' );
+		$this->client->get( 'https://example.com' );
+
+		$this->assertRequestCount( 1 );
+		$this->assertNotEmpty( wp_cache_get( 'custom-flexible-cache-key', Cache_Middleware::CACHE_GROUP ) );
+	}
 }

tests/HttpClient/HttpClientTest.php

@@ -321,6 +321,8 @@ public function test_wp_error_response() {
 
 		$this->assertTrue( $response->is_wp_error() );
 		$this->assertTrue( $response->failed() );
+		$this->assertFalse( $response->successful() );
+		$this->assertFalse( $response->ok() );
 
 		$this->assertEquals( 'An error occurred.', $response->body() );
 	}