JezK

Edit File: RestApiCache.php

<?php
declare(strict_types=1);

namespace Automattic\WooCommerce\Internal\Traits;

use Automattic\WooCommerce\Internal\Caches\VersionStringGenerator;
use Automattic\WooCommerce\Internal\Features\FeaturesController;
use Automattic\WooCommerce\Proxies\LegacyProxy;
use Automattic\WooCommerce\Utilities\CallbackUtil;
use WP_REST_Request;
use WP_REST_Response;

/**
 * This trait provides caching capabilities for REST API endpoints using the WordPress cache.
 *
 * - The output of all the REST API endpoints whose callback declaration is wrapped
 *   in a call to 'with_cache' will be cached using wp_cache_* functions.
 * - Response headers are cached together with the response data, excluding certain fixed
 *   headers (like Set-Cookie) and optionally others specified via configuration
 *   (per-controller or per-endpoint).
 * - For the purposes of caching, a request is uniquely identified by its route,
 *   HTTP method, query string, and user ID.
 * - The VersionStringGenerator class is used to track versions of entities included
 *   in the responses (an "entity" is any object that is uniquely identified by type and id
 *   and contributes with information to be included in the response),
 *   so that when those entities change, the relevant cached responses become invalid.
 *   Modification of entity versions must be done externally by the code that modifies
 *   those entities (via calls to VersionStringGenerator::generate_version).
 * - Various parameters (cached outputs TTL, entity type for a given response, hooks that affect
 *   the response) can be configured globally for the controller (via overriding protected methods)
 *   or per-endpoint (via arguments passed to with_cache).
 * - Caching can be disabled for a given request by adding a '_skip_cache=true|1'
 *   to the query string.
 * - A X-WC-Cache HTTP header is added to responses to indicate cache status:
 *   HIT, MISS, or SKIP.
 *
 * Additionally to caching, this trait also handles the sending of appropriate
 * Cache-Control and ETag headers to instruct clients and proxies on how to cache responses.
 * The ETag is generated based on the cached response data and cache key, and a request
 * containing an If-None-Match header with a matching ETag will receive a 304 Not Modified response.
 *
 * Usage: Wrap endpoint callbacks with the `with_cache()` method when registering routes.
 *
 * Example:
 *
 * class WC_REST_Products_Controller extends WC_REST_Products_V2_Controller {
 *     use RestApiCache;
 *
 *     public function __construct() {
 *         parent::__construct();
 *         $this->initialize_rest_api_cache();  // REQUIRED
 *     }
 *
 *     protected function get_default_response_entity_type(): ?string {
 *         return 'product';  // REQUIRED (or specify entity_type in each with_cache call)
 *     }
 *
 *     public function register_routes() {
 *         register_rest_route(
 *             $this->namespace,
 *             '/' . $this->rest_base . '/(?P<id>[\d]+)',
 *             array(
 *                 'methods'  => WP_REST_Server::READABLE,
 *                 'callback' => $this->with_cache(
 *                     array( $this, 'get_item' ),
 *                     array(
 *                         // String, optional if get_default_response_entity_type() is overridden.
 *                         'entity_type'    => 'product',
 *                         // Optional int, defaults to the controller's get_ttl_for_cached_response().
 *                         'cache_ttl'      => HOUR_IN_SECONDS,
 *                         // Optional array, defaults to the controller's get_hooks_relevant_to_caching().
 *                         'relevant_hooks'  => array( 'filter_name_1', 'filter_name_2' ),
 *                         // Optional array, defaults to the controller's get_files_relevant_to_response_caching().
 *                         // Paths can be absolute or relative to the first directory from
 *                         // get_allowed_directories_for_file_based_response_caching() (WC_ABSPATH by default).
 *                         'relevant_files'  => array( 'data/config.json', '/absolute/path/to/file.php' ),
 *                         // Optional array, defaults to the controller's get_version_strings_relevant_to_caching().
 *                         // Version string IDs to track; cache is invalidated when any version string changes.
 *                         'relevant_version_strings' => array( 'list_products' ),
 *                         // Optional bool, defaults to the controller's response_cache_vary_by_user().
 *                         'vary_by_user'    => true,
 *                         // Optional array, defaults to the controller's get_response_headers_to_include_in_caching().
 *                         'include_headers' => array( 'X-Custom-Header' ),
 *                         // Optional array, defaults to the controller's get_response_headers_to_exclude_from_caching().
 *                         'exclude_headers' => array( 'X-Private-Header' ),
 *                         // Optional, this will be passed to all the caching-related methods.
 *                         'endpoint_id'     => 'get_product'
 *                     )
 *                 ),
 *             )
 *         );
 *     }
 * }
 *
 * Override these methods in your controller as needed:
 * - get_default_response_entity_type(): Default entity type for endpoints without explicit config.
 * - response_cache_vary_by_user(): Whether cache should be user-specific.
 * - get_hooks_relevant_to_caching(): Hook names to track for cache invalidation.
 * - get_files_relevant_to_response_caching(): File paths to track for cache invalidation.
 * - get_version_strings_relevant_to_caching(): Version string IDs to track for cache invalidation.
 * - get_allowed_directories_for_file_based_response_caching(): Directories allowed for file tracking.
 * - get_file_check_interval_for_response_caching(): How long to cache file modification checks (default 10 minutes).
 * - get_ttl_for_cached_response(): TTL for cached outputs in seconds.
 * - get_response_headers_to_include_in_caching(): Headers to include in cache (false = use exclusion mode).
 * - get_response_headers_to_exclude_from_caching(): Headers to exclude from cache (when in exclusion mode).
 *
 * Cache invalidation happens when:
 * - Entity versions change (tracked via VersionStringGenerator).
 * - Hook callbacks change
 *   (if the `get_hooks_relevant_to_caching()` call result or the 'relevant_hooks' array isn't empty).
 * - Tracked files change or are deleted
 *   (if the `get_files_relevant_to_response_caching()` call result or the 'relevant_files' array isn't empty).
 * - Relevant version strings change or are deleted
 *   (if the `get_version_strings_relevant_to_caching()` call result or the 'relevant_version_strings' array isn't empty).
 * - Cached response TTL expires.
 *
 * NOTE: This caching mechanism uses the WordPress cache (wp_cache_* functions).
 * By default caching is only enabled when an external object cache is enabled
 * (checked via call to VersionStringGenerator::can_use()), so the cache is persistent
 * across requests and not just for the current request.
 *
 * @since 10.5.0
 */
trait RestApiCache {
	/**
	 * Cache group name for REST API responses.
	 *
	 * @var string
	 */
	private static string $cache_group = 'woocommerce_rest_api_cache';

/**
	 * Response headers that are always excluded from caching.
	 *
	 * @var array
	 */
	private static array $always_excluded_headers = array(
		'X-WC-Cache',
		'Set-Cookie',
		'Date',
		'Expires',
		'Last-Modified',
		'Age',
		'ETag',
		'Cache-Control',
		'Pragma',
	);

/**
	 * Cache group for warning suppression (separate from main cache to avoid interference).
	 *
	 * @var string
	 */
	private static string $warning_cache_group = 'woocommerce_rest_api_cache_warnings';

/**
	 * TTL for suppressing duplicate file tracking warnings (1 hour).
	 *
	 * @var int
	 */
	private static int $file_warning_suppression_ttl = HOUR_IN_SECONDS;

/**
	 * The instance of VersionStringGenerator to use, or null if caching is disabled.
	 *
	 * @var VersionStringGenerator|null
	 */
	private ?VersionStringGenerator $version_string_generator = null;

/**
	 * Whether we are currently handling a cached endpoint.
	 *
	 * @var bool
	 */
	private $is_handling_cached_endpoint = false;

/**
	 * Whether the REST API caching feature is enabled.
	 *
	 * @var bool
	 */
	private bool $rest_api_caching_feature_enabled = false;

/**
	 * Initialize the trait.
	 * This MUST be called from the controller's constructor.
	 *
	 * @since 10.5.0
	 */
	protected function initialize_rest_api_cache(): void {
		// Guard against early instantiation before WooCommerce is fully initialized.
		// Some third-party plugins instantiate REST controllers during plugin loading,
		// before the WooCommerce container is available.
		if ( ! function_exists( 'wc_get_container' ) ) {
			return;
		}

$features_controller = wc_get_container()->get( FeaturesController::class );

$this->rest_api_caching_feature_enabled = $features_controller->feature_is_enabled( 'rest_api_caching' );
		if ( ! $this->rest_api_caching_feature_enabled ) {
			return;
		}

$generator = wc_get_container()->get( VersionStringGenerator::class );

$backend_caching_enabled        = 'yes' === get_option( 'woocommerce_rest_api_enable_backend_caching', 'no' );
		$this->version_string_generator = ( $backend_caching_enabled && $generator->can_use() ) ? $generator : null;

add_filter( 'rest_send_nocache_headers', array( $this, 'handle_rest_send_nocache_headers' ), 10, 1 );
	}

/**
	 * Wrap an endpoint callback declaration with caching logic.
	 * Usage: `'callback' => $this->with_cache( array( $this, 'endpoint_callback_method' ) )`
	 *        `'callback' => $this->with_cache( array( $this, 'endpoint_callback_method' ), [ 'entity_type' => 'product' ] )`
	 *
	 * @since 10.5.0
	 *
	 * @param callable $callback The original endpoint callback.
	 * @param array    $config   Caching configuration:
	 *                           - entity_type: string (falls back to get_default_response_entity_type()).
	 *                           - vary_by_user: bool (defaults to response_cache_vary_by_user()).
	 *                           - endpoint_id: string|null (optional friendly identifier for the endpoint).
	 *                           - cache_ttl: int (defaults to get_ttl_for_cached_response()).
	 *                           - relevant_hooks: array (defaults to get_hooks_relevant_to_caching()).
	 *                           - relevant_files: array (defaults to get_files_relevant_to_response_caching()).
	 *                           - relevant_version_strings: array (defaults to get_version_strings_relevant_to_caching()).
	 *                           - include_headers: array|false (defaults to get_response_headers_to_include_in_caching()).
	 *                           - exclude_headers: array (defaults to get_response_headers_to_exclude_from_caching()).
	 * @return callable Wrapped callback.
	 */
	protected function with_cache( callable $callback, array $config = array() ): callable {
		return $this->rest_api_caching_feature_enabled
			? fn( $request ) => $this->handle_cacheable_request( $request, $callback, $config )
			: fn( $request ) => call_user_func( $callback, $request );
	}

/**
	 * Handle a request with caching logic.
	 *
	 * Strategy:
	 * - If backend caching is enabled: Try to use cached response if available, otherwise execute
	 *   the callback and cache the response.
	 * - If only cache headers are enabled: Execute the callback, generate ETag, and return 304
	 *   if the client's ETag matches.
	 *
	 * @param WP_REST_Request<array<string, mixed>> $request  The request object.
	 * @param callable                              $callback The original endpoint callback.
	 * @param array                                 $config   Caching configuration specified for the endpoint.
	 *
	 * @return WP_REST_Response|\WP_Error The response.
	 */
	private function handle_cacheable_request( WP_REST_Request $request, callable $callback, array $config ) { // phpcs:ignore Squiz.Commenting.FunctionComment.IncorrectTypeHint
		$backend_caching_enabled = ! is_null( $this->version_string_generator );
		$cache_headers_enabled   = 'yes' === get_option( 'woocommerce_rest_api_enable_cache_headers', 'yes' );

if ( ! $backend_caching_enabled && ! $cache_headers_enabled ) {
			return call_user_func( $callback, $request );
		}

if ( ! $this->should_use_cache_for_request( $request ) ) {
			$response = call_user_func( $callback, $request );
			if ( ! is_wp_error( $response ) ) {
				$response = rest_ensure_response( $response );
				$response->header( 'X-WC-Cache', 'SKIP' );
			}
			return $response;
		}

$cached_config = $this->build_cache_config( $request, $config );

$this->is_handling_cached_endpoint = true;

if ( $backend_caching_enabled ) {
			$cached_response = $this->get_cached_response( $request, $cached_config, $cache_headers_enabled );

if ( $cached_response ) {
				$cached_response->header( 'X-WC-Cache', 'HIT' );
				return $cached_response;
			}
		}

$authoritative_response = call_user_func( $callback, $request );

return $backend_caching_enabled
			? $this->maybe_cache_response( $request, $authoritative_response, $cached_config, $cache_headers_enabled )
			: $this->maybe_add_cache_headers( $request, $authoritative_response, $cached_config );
	}

/**
	 * Check if caching should be used for a particular incoming request.
	 *
	 * @param WP_REST_Request<array<string, mixed>> $request The request object.
	 *
	 * @return bool True if caching should be used, false otherwise.
	 */
	private function should_use_cache_for_request( WP_REST_Request $request ): bool { // phpcs:ignore Squiz.Commenting.FunctionComment.IncorrectTypeHint
		$skip_cache   = $request->get_param( '_skip_cache' );
		$should_cache = ! ( 'true' === $skip_cache || '1' === $skip_cache );

/**
		 * Filter whether to enable response caching for a given REST API controller.
		 *
		 * @since 10.5.0
		 *
		 * @param bool            $enable_caching Whether to enable response caching (result of !_skip_cache evaluation).
		 * @param object          $controller     The controller instance.
		 * @param WP_REST_Request<array<string, mixed>> $request        The request object.
		 * @return bool True to enable response caching, false to disable.
		 */
		return apply_filters(
			'woocommerce_rest_api_enable_response_caching',
			$should_cache,
			$this,
			$request
		);
	}

/**
	 * Build the output cache entry configuration from the request and per-endpoint config.
	 *
	 * @param WP_REST_Request<array<string, mixed>> $request The request object.
	 * @param array                                 $config  Raw configuration array passed to with_cache.
	 *
	 * @return array Normalized cache config with keys: endpoint_id, entity_type, vary_by_user, cache_ttl, relevant_hooks, relevant_files, include_headers, exclude_headers, cache_key.
	 *
	 * @throws \InvalidArgumentException If entity_type is not provided and no default is available, or if include_headers is not false or an array.
	 */
	private function build_cache_config( WP_REST_Request $request, array $config ): array { // phpcs:ignore Squiz.Commenting.FunctionComment.IncorrectTypeHint
		$endpoint_id  = $config['endpoint_id'] ?? null;
		$entity_type  = $config['entity_type'] ?? $this->get_default_response_entity_type();
		$vary_by_user = $config['vary_by_user'] ?? $this->response_cache_vary_by_user( $request, $endpoint_id );

if ( ! $entity_type ) {
			throw new \InvalidArgumentException(
				'REST API cache: No entity type provided in with_cache() config and no default entity type available from get_default_response_entity_type(). ' .
				'Either pass "entity_type" in the config array or override get_default_response_entity_type() in your controller.'
			);
		}

$include_headers = $config['include_headers'] ?? $this->get_response_headers_to_include_in_caching( $request, $endpoint_id );
		if ( false !== $include_headers && ! is_array( $include_headers ) ) {
			throw new \InvalidArgumentException(
				'include_headers must be either false or an array, ' . gettype( $include_headers ) . ' given.' // phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped
			);
		}

return array(
			'endpoint_id'              => $endpoint_id,
			'entity_type'              => $entity_type,
			'vary_by_user'             => $vary_by_user,
			'cache_ttl'                => $config['cache_ttl'] ?? $this->get_ttl_for_cached_response( $request, $endpoint_id ),
			'relevant_hooks'           => $config['relevant_hooks'] ?? $this->get_hooks_relevant_to_caching( $request, $endpoint_id ),
			'relevant_files'           => $config['relevant_files'] ?? $this->get_files_relevant_to_response_caching( $request, $endpoint_id ),
			'relevant_version_strings' => $config['relevant_version_strings'] ?? $this->get_version_strings_relevant_to_caching( $request, $endpoint_id ),
			'include_headers'          => $include_headers,
			'exclude_headers'          => $config['exclude_headers'] ?? $this->get_response_headers_to_exclude_from_caching( $request, $endpoint_id ),
			'cache_key'                => $this->get_key_for_cached_response( $request, $entity_type, $vary_by_user, $endpoint_id ),
		);
	}

/**
	 * Cache the response if it's successful and optionally add cache headers.
	 *
	 * Only caches responses with 2xx status codes. Always adds the X-WC-Cache header
	 * with value MISS if the response was cached, or SKIP if it was not cached.
	 *
	 * Supports both WP_REST_Response objects and raw data (which will be wrapped in a response object).
	 * Error objects are returned as-is without caching.
	 *
	 * @param WP_REST_Request<array<string, mixed>>   $request            The request object.
	 * @param WP_REST_Response|\WP_Error|array|object $response           The response to potentially cache.
	 * @param array                                   $cached_config      Caching configuration from build_cache_config().
	 * @param bool                                    $add_cache_headers  Whether to add cache control headers.
	 *
	 * @return WP_REST_Response|\WP_Error The response with appropriate cache headers.
	 */
	private function maybe_cache_response( WP_REST_Request $request, $response, array $cached_config, bool $add_cache_headers ) { // phpcs:ignore Squiz.Commenting.FunctionComment.IncorrectTypeHint
		if ( is_wp_error( $response ) ) {
			return $response;
		}

$response = rest_ensure_response( $response );

$cached = false;

$status = $response->get_status();
		if ( $status >= 200 && $status <= 299 ) {
			$data       = $response->get_data();
			$entity_ids = is_array( $data ) ? $this->extract_entity_ids_from_response( $data, $request, $cached_config['endpoint_id'] ) : array();

$response_headers  = $response->get_headers();
			$cacheable_headers = $this->get_headers_to_cache(
				$response_headers,
				$cached_config['include_headers'],
				$cached_config['exclude_headers'],
				$request,
				$response,
				$cached_config['endpoint_id']
			);

$etag_data = is_array( $data ) ? $this->get_data_for_etag( $data, $request, $cached_config['endpoint_id'] ) : $data;
			$etag      = '"' . md5( $cached_config['cache_key'] . wp_json_encode( $etag_data ) ) . '"';

$this->store_cached_response(
				array_merge(
					$cached_config,
					array(
						'data'        => $data,
						'status_code' => $status,
						'entity_ids'  => $entity_ids,
						'headers'     => $cacheable_headers,
						'etag'        => $etag,
					)
				)
			);

$cached = true;
		}

$response->header( 'X-WC-Cache', $cached ? 'MISS' : 'SKIP' );

return $add_cache_headers ?
			$this->maybe_add_cache_headers( $request, $response, $cached_config ) :
			$response;
	}

/**
	 * Add cache control headers to a response.
	 *
	 * This method generates an ETag from the response data and returns a 304 Not Modified
	 * if the client's If-None-Match header matches. It can be used both with and without
	 * backend caching.
	 *
	 * @param WP_REST_Request<array<string, mixed>>   $request       The request object.
	 * @param WP_REST_Response|\WP_Error|array|object $response      The response to add headers to.
	 * @param array                                   $cached_config Caching configuration from build_cache_config().
	 *
	 * @return WP_REST_Response|\WP_Error The response with cache headers.
	 */
	private function maybe_add_cache_headers( WP_REST_Request $request, $response, array $cached_config ) { // phpcs:ignore Squiz.Commenting.FunctionComment.IncorrectTypeHint
		if ( is_wp_error( $response ) ) {
			return $response;
		}

$response = rest_ensure_response( $response );

$status = $response->get_status();
		if ( $status < 200 || $status > 299 ) {
			return $response;
		}

$response_data      = $response->get_data();
		$response_etag_data = is_array( $response_data ) ? $this->get_data_for_etag( $response_data, $request, $cached_config['endpoint_id'] ) : $response_data;
		$response_etag      = '"' . md5( $cached_config['cache_key'] . wp_json_encode( $response_etag_data ) ) . '"';

$request_etag = $request->get_header( 'if-none-match' );

$legacy_proxy        = wc_get_container()->get( LegacyProxy::class );
		$is_user_logged_in   = $legacy_proxy->call_function( 'is_user_logged_in' );
		$cache_visibility    = $cached_config['vary_by_user'] && $is_user_logged_in ? 'private' : 'public';
		$cache_control_value = $cache_visibility . ', must-revalidate, max-age=' . $cached_config['cache_ttl'];

if ( $request_etag === $response_etag ) {
			$not_modified_response = $this->create_not_modified_response( $response_etag, $cache_control_value, $request, $cached_config['endpoint_id'] );
			if ( $not_modified_response ) {
				return $not_modified_response;
			}
		}

$response->header( 'ETag', $response_etag );
		$response->header( 'Cache-Control', $cache_control_value );

if ( ! array_key_exists( 'X-WC-Cache', $response->get_headers() ) ) {
			$response->header( 'X-WC-Cache', 'HEADERS' );
		}

return $response;
	}

/**
	 * Create a 304 Not Modified response if allowed by filters.
	 *
	 * @param string                                $etag                The ETag value.
	 * @param string                                $cache_control_value The Cache-Control header value.
	 * @param WP_REST_Request<array<string, mixed>> $request             The request object.
	 * @param string|null                           $endpoint_id         The endpoint identifier.
	 *
	 * @return WP_REST_Response|null 304 response if allowed, null otherwise.
	 */
	private function create_not_modified_response( string $etag, string $cache_control_value, WP_REST_Request $request, ?string $endpoint_id ): ?WP_REST_Response { // phpcs:ignore Squiz.Commenting.FunctionComment.IncorrectTypeHint
		$response = new WP_REST_Response( null, 304 );
		$response->header( 'ETag', $etag );
		$response->header( 'Cache-Control', $cache_control_value );
		$response->header( 'X-WC-Cache', 'MATCH' );

/**
		 * Filter the 304 Not Modified response before sending.
		 *
		 * @since 10.5.0
		 *
		 * @param WP_REST_Response|false $response    The 304 response object, or false to prevent sending it.
		 * @param WP_REST_Request        $request     The request object.
		 * @param string|null            $endpoint_id The endpoint identifier.
		 */
		$filtered_response = apply_filters( 'woocommerce_rest_api_not_modified_response', $response, $request, $endpoint_id );

return false === $filtered_response ? null : rest_ensure_response( $filtered_response );
	}

/**
	 * Get the default type for entities included in responses.
	 *
	 * This can be customized per-endpoint via the config array
	 * passed to with_cache() ('entity_type' key).
	 *
	 * @since 10.5.0
	 *
	 * @return string|null Entity type (e.g., 'product', 'order'), or null if no controller-wide default.
	 */
	protected function get_default_response_entity_type(): ?string {
		return null;
	}

/**
	 * Get data for ETag generation.
	 *
	 * Override in classes to exclude fields that change on each request
	 * (e.g., random recommendations, timestamps).
	 *
	 * @since 10.5.0
	 *
	 * @param array                                 $data        Response data.
	 * @param WP_REST_Request<array<string, mixed>> $request     The request object.
	 * @param string|null                           $endpoint_id Optional friendly identifier for the endpoint.
	 *
	 * @return array Cleaned data for ETag generation.
	 */
	protected function get_data_for_etag( array $data, WP_REST_Request $request, ?string $endpoint_id = null ): array { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed, Squiz.Commenting.FunctionComment.IncorrectTypeHint
		return $data;
	}

/**
	 * Whether the response cache should vary by user.
	 *
	 * When true, each user gets their own cached version of the response.
	 * When false, the same cached response is shared across all users.
	 *
	 * This can be customized per-endpoint via the config array
	 * passed to with_cache() ('vary_by_user' key).
	 *
	 * @since 10.5.0
	 *
	 * @param WP_REST_Request<array<string, mixed>> $request     The request object.
	 * @param string|null                           $endpoint_id Optional friendly identifier for the endpoint.
	 *
	 * @return bool True to make cache user-specific, false otherwise.
	 */
	protected function response_cache_vary_by_user( WP_REST_Request $request, ?string $endpoint_id = null ): bool { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed, Squiz.Commenting.FunctionComment.IncorrectTypeHint
		return true;
	}

/**
	 * Get the cache TTL (time to live) for cached responses.
	 *
	 * This can be customized per-endpoint via the config array
	 * passed to with_cache() ('cache_ttl' key).
	 *
	 * @since 10.5.0
	 *
	 * @param WP_REST_Request<array<string, mixed>> $request     The request object.
	 * @param string|null                           $endpoint_id Optional friendly identifier for the endpoint.
	 *
	 * @return int Cache TTL in seconds.
	 */
	protected function get_ttl_for_cached_response( WP_REST_Request $request, ?string $endpoint_id = null ): int { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed, Squiz.Commenting.FunctionComment.IncorrectTypeHint
		return HOUR_IN_SECONDS;
	}

/**
	 * Get the names of hooks (filters and actions) that can customize the response.
	 *
	 * All the existing instances of add_action/add_filter for these hooks
	 * will be included in the information that gets cached together with the response,
	 * and if any of these has changed when the cached response is retrieved,
	 * the cache entry will be invalidated.
	 *
	 * This can be customized per-endpoint via the config array
	 * passed to with_cache() ('relevant_hooks' key).
	 *
	 * @since 10.5.0
	 *
	 * @param WP_REST_Request<array<string, mixed>> $request     Request object.
	 * @param string|null                           $endpoint_id Optional friendly identifier for the endpoint.
	 *
	 * @return array Array of hook names to track.
	 */
	protected function get_hooks_relevant_to_caching( WP_REST_Request $request, ?string $endpoint_id = null ): array { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed, Squiz.Commenting.FunctionComment.IncorrectTypeHint
		return array();
	}

/**
	 * Get the paths of files whose modification affects the response.
	 *
	 * All the returned files will be tracked for changes: whenever a response is cached,
	 * each file's modification time is recorded, and if any file has changed or disappeared
	 * when the cached response is retrieved, the cache entry will be invalidated.
	 *
	 * Paths can be absolute or relative. Relative paths are resolved relative to the first
	 * directory returned by get_allowed_directories_for_file_based_response_caching().
	 *
	 * This can be customized per-endpoint via the config array
	 * passed to with_cache() ('relevant_files' key).
	 *
	 * @since 10.6.0
	 *
	 * @param WP_REST_Request<array<string, mixed>> $request     Request object.
	 * @param string|null                           $endpoint_id Optional friendly identifier for the endpoint.
	 *
	 * @return array Array of file paths to track.
	 */
	protected function get_files_relevant_to_response_caching( WP_REST_Request $request, ?string $endpoint_id = null ): array { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed, Squiz.Commenting.FunctionComment.IncorrectTypeHint
		return array();
	}

/**
	 * Get the identifiers of version strings that affect the response.
	 *
	 * All returned version strings will be tracked for changes: whenever a response is cached,
	 * each version string's current value is recorded, and if any has changed or disappeared
	 * when the cached response is retrieved, the cache entry will be invalidated.
	 *
	 * This is useful for collection endpoints where entities outside the current page
	 * could affect the response (e.g., a deleted entity shifts pagination).
	 *
	 * This can be customized per-endpoint via the config array
	 * passed to with_cache() ('relevant_version_strings' key).
	 *
	 * @since 10.6.0
	 *
	 * @param WP_REST_Request<array<string, mixed>> $request     Request object.
	 * @param string|null                           $endpoint_id Optional friendly identifier for the endpoint.
	 *
	 * @return array Array of version string identifiers to track.
	 */
	protected function get_version_strings_relevant_to_caching( WP_REST_Request $request, ?string $endpoint_id = null ): array { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed, Squiz.Commenting.FunctionComment.IncorrectTypeHint
		return array();
	}

/**
	 * Get directories allowed for file-based response caching.
	 *
	 * Returns an array of directory paths that are allowed to contain files tracked
	 * for cache invalidation. The first directory in the array is also used as the
	 * base path for resolving relative file paths.
	 *
	 * @since 10.6.0
	 *
	 * @return array Array of absolute directory paths.
	 */
	protected function get_allowed_directories_for_file_based_response_caching(): array {
		return defined( 'WC_ABSPATH' ) ? array( WC_ABSPATH ) : array();
	}

/**
	 * Get the interval for caching file modification checks.
	 *
	 * To avoid checking file modification times on every request, file checks are cached
	 * for this interval. During this period, files are assumed to be unchanged.
	 *
	 * Override this method to customize the interval. Return 0 to disable caching
	 * and check files on every request.
	 *
	 * @since 10.6.0
	 *
	 * @return int Interval in seconds. Default is 10 minutes (600 seconds).
	 */
	protected function get_file_check_interval_for_response_caching(): int {
		return 10 * MINUTE_IN_SECONDS;
	}

/**
	 * Get the names of response headers to include in caching.
	 *
	 * When this returns an array, ONLY the headers whose names are returned
	 * will be included in the cache (subject to always-excluded headers).
	 * When this returns false, all headers will be included except those returned
	 * by get_response_headers_to_exclude_from_caching().
	 *
	 * This can be customized per-endpoint via the config array
	 * passed to with_cache() ('include_headers' key).
	 *
	 * @since 10.5.0
	 *
	 * @param WP_REST_Request<array<string, mixed>> $request     Request object.
	 * @param string|null                           $endpoint_id Optional friendly identifier for the endpoint.
	 *
	 * @return array|false Array of header names to include (case-insensitive), or false to use exclusion logic.
	 */
	protected function get_response_headers_to_include_in_caching( WP_REST_Request $request, ?string $endpoint_id = null ) { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed, Squiz.Commenting.FunctionComment.IncorrectTypeHint
		return false;
	}

/**
	 * Get the names of response headers to exclude from caching.
	 *
	 * These headers will not be stored in the cache, in addition to the
	 * always-excluded headers (X-WC-Cache, Set-Cookie, Date, Expires, Last-Modified,
	 * Age, ETag, Cache-Control, Pragma).
	 *
	 * This is only used when get_response_headers_to_include_in_caching() returns false.
	 *
	 * This can be customized per-endpoint via the config array
	 * passed to with_cache() ('exclude_headers' key).
	 *
	 * @since 10.5.0
	 *
	 * @param WP_REST_Request<array<string, mixed>> $request     Request object.
	 * @param string|null                           $endpoint_id Optional friendly identifier for the endpoint.
	 *
	 * @return array Array of header names to exclude (case-insensitive).
	 */
	protected function get_response_headers_to_exclude_from_caching( WP_REST_Request $request, ?string $endpoint_id = null ): array { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed, Squiz.Commenting.FunctionComment.IncorrectTypeHint
		return array();
	}

/**
	 * Extract entity IDs from response data.
	 *
	 * This implementation assumes the response is either:
	 * - An array with an 'id' field (single item)
	 * - An array of arrays each having an 'id' field (collection)
	 *
	 * Controllers can override this method to customize entity ID extraction.
	 *
	 * @since 10.5.0
	 *
	 * @param array                                 $response_data Response data.
	 * @param WP_REST_Request<array<string, mixed>> $request       The request object.
	 * @param string|null                           $endpoint_id   Optional friendly identifier for the endpoint.
	 *
	 * @return array Array of entity IDs.
	 */
	protected function extract_entity_ids_from_response( array $response_data, WP_REST_Request $request, ?string $endpoint_id = null ): array { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed, Squiz.Commenting.FunctionComment.IncorrectTypeHint
		$ids = array();

if ( isset( $response_data[0] ) && is_array( $response_data[0] ) ) {
			foreach ( $response_data as $item ) {
				if ( isset( $item['id'] ) ) {
					$ids[] = $item['id'];
				}
			}
		} elseif ( isset( $response_data['id'] ) ) {
			$ids[] = $response_data['id'];
		}

// Filter out false values but keep 0 and empty strings as they could be valid IDs.
		// Note: null values can't exist here because isset() checks above exclude them.
		return array_unique(
			array_filter( $ids, fn ( $id ) => false !== $id )
		);
	}

/**
	 * Filter response headers to get only those that should be cached.
	 *
	 * The filtering process follows these steps:
	 * 1. If $include_headers is an array, only those headers are included (case-insensitive).
	 *    If $include_headers is false, all headers are included except those in $exclude_headers.
	 * 2. Always-excluded headers (X-WC-Cache, Set-Cookie, Date, etc.) are removed.
	 * 3. The woocommerce_rest_api_cached_headers filter is applied, receiving both the candidate
	 *    headers list and all available headers. This allows filters to both add and remove
	 *    headers from the caching list.
	 * 4. Always-excluded headers are enforced again post-filter to prevent filters from
	 *    re-introducing dangerous headers like Set-Cookie.
	 * 5. Only headers from the response that are in the filtered list are returned.
	 *
	 * @param array                                 $nominal_headers Response headers.
	 * @param array|false                           $include_headers Header names to include (false to use exclusion logic).
	 * @param array                                 $exclude_headers Header names to exclude (case-insensitive).
	 * @param WP_REST_Request<array<string, mixed>> $request The request object.
	 * @param WP_REST_Response                      $response        The response object.
	 * @param string|null                           $endpoint_id     Optional friendly identifier for the endpoint.
	 *
	 * @return array Filtered headers array.
	 */
	private function get_headers_to_cache( array $nominal_headers, $include_headers, array $exclude_headers, WP_REST_Request $request, WP_REST_Response $response, ?string $endpoint_id ): array { // phpcs:ignore Squiz.Commenting.FunctionComment.IncorrectTypeHint
		// Step 1: Determine which headers to consider based on include/exclude.
		if ( false !== $include_headers ) {
			$include_headers_lowercase = array_map( 'strtolower', $include_headers );
			$headers_to_cache          = array_filter(
				$nominal_headers,
				fn( $name ) => in_array( strtolower( $name ), $include_headers_lowercase, true ),
				ARRAY_FILTER_USE_KEY
			);
		} else {
			$exclude_headers_lowercase = array_map( 'strtolower', $exclude_headers );
			$headers_to_cache          = array_filter(
				$nominal_headers,
				fn( $name ) => ! in_array( strtolower( $name ), $exclude_headers_lowercase, true ),
				ARRAY_FILTER_USE_KEY
			);
		}

// Step 2: Remove always-excluded headers.
		$always_exclude_lowercase = array_map( 'strtolower', self::$always_excluded_headers );
		$headers_to_cache         = array_filter(
			$headers_to_cache,
			fn( $name ) => ! in_array( strtolower( $name ), $always_exclude_lowercase, true ),
			ARRAY_FILTER_USE_KEY
		);

// Step 3: Apply filter to header names.
		$cached_header_names = array_keys( $headers_to_cache );
		$all_header_names    = array_keys( $nominal_headers );

/**
		 * Filter the list of response header names to cache.
		 *
		 * @since 10.5.0
		 *
		 * @param array            $cached_header_names Candidate list of header names to cache.
		 * @param array            $all_header_names    All header names available in the response.
		 * @param WP_REST_Request  $request             The request object.
		 * @param WP_REST_Response $response            The response object.
		 * @param string|null      $endpoint_id         Optional friendly identifier for the endpoint.
		 * @param object           $controller          The controller instance.
		 *
		 * @return array Filtered list of header names to cache.
		 */
		$filtered_header_names = apply_filters(
			'woocommerce_rest_api_cached_headers',
			$cached_header_names,
			$all_header_names,
			$request,
			$response,
			$endpoint_id,
			$this
		);

// Step 4: Enforce always-excluded headers post-filter.
		$filtered_header_names_lowercase = array_map( 'strtolower', $filtered_header_names );
		$reintroduced_headers            = array_filter(
			$filtered_header_names,
			fn( $name ) => in_array( strtolower( $name ), $always_exclude_lowercase, true )
		);

if ( ! empty( $reintroduced_headers ) ) {
			$legacy_proxy = wc_get_container()->get( LegacyProxy::class );
			$legacy_proxy->call_function(
				'wc_doing_it_wrong',
				__METHOD__,
				sprintf(
					/* translators: %s: comma-separated list of header names */
					'The woocommerce_rest_api_cached_headers filter attempted to cache always-excluded headers: %s. These headers have been removed for security reasons.',
					implode( ', ', $reintroduced_headers )
				),
				'10.5.0'
			);

$filtered_header_names_lowercase = array_filter(
				$filtered_header_names_lowercase,
				fn( $name ) => ! in_array( $name, $always_exclude_lowercase, true )
			);
		}

// Step 5: Return only the headers that are in the filtered list.
		return array_filter(
			$nominal_headers,
			fn( $name ) => in_array( strtolower( $name ), $filtered_header_names_lowercase, true ),
			ARRAY_FILTER_USE_KEY
		);
	}

/**
	 * Get cache key information that uniquely identifies a request.
	 *
	 * @since 10.5.0
	 *
	 * @param WP_REST_Request<array<string, mixed>> $request      The request object.
	 * @param bool                                  $vary_by_user Whether to include user ID in cache key.
	 * @param string|null                           $endpoint_id  Optional friendly identifier for the endpoint.
	 *
	 * @return array Array of cache key information parts.
	 */
	protected function get_key_info_for_cached_response( WP_REST_Request $request, bool $vary_by_user = false, ?string $endpoint_id = null ): array { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed, Squiz.Commenting.FunctionComment.IncorrectTypeHint
		$request_query_params = $request->get_query_params();
		if ( is_array( $request_query_params ) ) {
			ksort( $request_query_params );
		}

$cache_key_parts = array(
			$request->get_route(),
			$request->get_method(),
			wp_json_encode( $request_query_params ),
		);

if ( $vary_by_user ) {
			$legacy_proxy = wc_get_container()->get( LegacyProxy::class );
			// @phpstan-ignore-next-line argument.type -- get_current_user_id returns int at runtime.
			$user_id           = intval( $legacy_proxy->call_function( 'get_current_user_id' ) );
			$cache_key_parts[] = "user_{$user_id}";
		}

return $cache_key_parts;
	}

/**
	 * Generate a cache key for a given request.
	 *
	 * @param WP_REST_Request<array<string, mixed>> $request      The request object.
	 * @param string                                $entity_type  The entity type.
	 * @param bool                                  $vary_by_user Whether to include user ID in cache key.
	 * @param string|null                           $endpoint_id  Optional friendly identifier for the endpoint.
	 *
	 * @return string Cache key.
	 */
	private function get_key_for_cached_response( WP_REST_Request $request, string $entity_type, bool $vary_by_user = false, ?string $endpoint_id = null ): string { // phpcs:ignore Squiz.Commenting.FunctionComment.IncorrectTypeHint
		$cache_key_parts = $this->get_key_info_for_cached_response( $request, $vary_by_user, $endpoint_id );

/**
		 * Filter the information used to generate the cache key for a REST API request.
		 *
		 * Allows customization of what uniquely identifies a request for caching purposes.
		 *
		 * @since 10.5.0
		 *
		 * @param array           $cache_key_parts Array of cache key information parts.
		 * @param WP_REST_Request<array<string, mixed>> $request         The request object.
		 * @param bool            $vary_by_user    Whether user ID is included in cache key.
		 * @param string|null     $endpoint_id     Optional friendly identifier for the endpoint (passed to with_cache).
		 * @param object          $controller      The controller instance.
		 *
		 * @return array Filtered cache key information parts.
		 */
		$cache_key_parts = apply_filters(
			'woocommerce_rest_api_cache_key_info',
			$cache_key_parts,
			$request,
			$vary_by_user,
			$endpoint_id,
			$this
		);

$request_hash = md5( implode( '-', $cache_key_parts ) );
		return "wc_rest_api_cache_{$entity_type}-{$request_hash}";
	}

/**
	 * Generate a hash based on the actual usages of the hooks that affect the response.
	 *
	 * @param array $hook_names Array of hook names to track.
	 *
	 * @return string Hooks hash.
	 */
	private function generate_hooks_hash( array $hook_names ): string {
		if ( empty( $hook_names ) ) {
			return '';
		}

$cache_hash_data = array();

foreach ( $hook_names as $hook_name ) {
			$signatures = CallbackUtil::get_hook_callback_signatures( $hook_name );
			if ( ! empty( $signatures ) ) {
				$cache_hash_data[ $hook_name ] = $signatures;
			}
		}

/**
		 * Filter the data used to generate the hooks hash for REST API response caching.
		 *
		 * @since 10.5.0
		 *
		 * @param array  $cache_hash_data Hook callbacks data used for hash generation.
		 * @param array  $hook_names      Hook names being tracked.
		 * @param object $controller      Controller instance.
		 */
		$cache_hash_data = apply_filters(
			'woocommerce_rest_api_cache_hooks_hash_data',
			$cache_hash_data,
			$hook_names,
			$this
		);

$json = wp_json_encode( $cache_hash_data );
		return md5( false === $json ? '' : $json );
	}

/**
	 * Generate a hash based on the current values of the relevant version strings.
	 *
	 * @since 10.6.0
	 *
	 * @param array $version_string_ids Array of version string identifiers to track.
	 *
	 * @return string Version strings hash, or empty string if no version strings could be tracked.
	 */
	private function generate_version_strings_hash( array $version_string_ids ): string {
		if ( empty( $version_string_ids ) || is_null( $this->version_string_generator ) ) {
			return '';
		}

$version_data = array();
		foreach ( $version_string_ids as $id ) {
			$version = $this->version_string_generator->get_version( $id );
			if ( $version ) {
				$version_data[ $id ] = $version;
			}
		}

if ( empty( $version_data ) ) {
			return '';
		}

/**
		 * Filter the version strings data used for REST API response cache invalidation.
		 *
		 * @since 10.6.0
		 *
		 * @param array  $version_data       Array mapping version string IDs to their current values.
		 * @param array  $version_string_ids Original version string identifiers passed to the method.
		 * @param object $controller         Controller instance.
		 */
		$version_data = apply_filters(
			'woocommerce_rest_api_cache_version_strings_hash_data',
			$version_data,
			$version_string_ids,
			$this
		);

if ( empty( $version_data ) ) {
			return '';
		}

ksort( $version_data );
		$json = wp_json_encode( $version_data );
		return md5( false === $json ? '' : $json );
	}

/**
	 * Get the filtered list of allowed directories for file-based response caching.
	 *
	 * This method retrieves the allowed directories from the protected method
	 * and applies the woocommerce_rest_api_cache_allowed_file_directories filter.
	 *
	 * @since 10.6.0
	 *
	 * @return array Array of absolute directory paths.
	 */
	private function get_filtered_allowed_directories_for_response_caching(): array {
		$allowed_directories = $this->get_allowed_directories_for_file_based_response_caching();

/**
		 * Filter the directories allowed for file-based REST API response caching.
		 *
		 * This filter allows extensions to add additional directories that can contain
		 * files tracked for cache invalidation. The first directory in the array is
		 * used as the base path for resolving relative file paths.
		 *
		 * @since 10.6.0
		 *
		 * @param array  $allowed_directories Array of absolute directory paths.
		 * @param object $controller          The controller instance.
		 *
		 * @return array Filtered array of directory paths.
		 */
		return apply_filters(
			'woocommerce_rest_api_cache_allowed_file_directories',
			$allowed_directories,
			$this
		);
	}

/**
	 * Generate a hash for the given file paths based on their modification times.
	 *
	 * This method resolves relative paths (relative to the first allowed directory),
	 * gets file modification times, and generates a hash for cache invalidation.
	 * Files that cannot be accessed (permissions, non-existent) are logged as warnings
	 * and excluded from tracking.
	 *
	 * To avoid filesystem calls on every request, file check results are cached
	 * for the interval returned by get_file_check_interval_for_response_caching().
	 *
	 * @since 10.6.0
	 *
	 * @param array $file_paths Array of file paths (absolute or relative to the first allowed directory).
	 *
	 * @return string Hash string, or empty string if no files could be tracked.
	 */
	private function generate_files_hash( array $file_paths ): string {
		if ( empty( $file_paths ) ) {
			return '';
		}

$allowed_directories = $this->get_filtered_allowed_directories_for_response_caching();
		if ( empty( $allowed_directories ) ) {
			$this->log_file_tracking_warning( '', 'No allowed directories configured for file tracking' );
			return '';
		}

$files_data     = null;
		$check_interval = $this->get_file_check_interval_for_response_caching();

// Try to get cached file check results to avoid filesystem calls on every request.
		if ( $check_interval > 0 ) {
			$file_check_cache_key = $this->get_file_check_cache_key( $file_paths, $allowed_directories );
			$files_data           = wp_cache_get( $file_check_cache_key, self::$cache_group );
			if ( false === $files_data ) {
				$files_data = null;
			}
		}

// Cache miss or caching disabled - check all files.
		if ( is_null( $files_data ) ) {
			$files_data = $this->check_files( $file_paths, $allowed_directories );

// Cache the results if caching is enabled.
			if ( $check_interval > 0 && ! empty( $files_data ) ) {
				wp_cache_set( $file_check_cache_key, $files_data, self::$cache_group, $check_interval );
			}
		}

/**
		 * Filter the file data used for REST API response cache invalidation.
		 *
		 * This filter allows modification of the file tracking data before it is stored
		 * in the cache and used for invalidation checks.
		 *
		 * @since 10.6.0
		 *
		 * @param array  $files_data Array of file data, each with 'path' and 'time' keys.
		 * @param array  $file_paths Original file paths passed to the method.
		 * @param object $controller Controller instance.
		 */
		$files_data = apply_filters(
			'woocommerce_rest_api_cache_files_hash_data',
			$files_data,
			$file_paths,
			$this
		);

if ( empty( $files_data ) ) {
			return '';
		}

$json = wp_json_encode( $files_data );
		return md5( false === $json ? '' : $json );
	}

/**
	 * Generate a cache key for file check results.
	 *
	 * @param array $file_paths          Array of file paths to track.
	 * @param array $allowed_directories Array of allowed directory paths.
	 *
	 * @return string Cache key.
	 */
	private function get_file_check_cache_key( array $file_paths, array $allowed_directories ): string {
		sort( $file_paths );
		sort( $allowed_directories );
		$key_data = array(
			'files' => $file_paths,
			'dirs'  => $allowed_directories,
		);
		$json     = wp_json_encode( $key_data );
		return 'wc_rest_file_check_' . md5( false === $json ? '' : $json );
	}

/**
	 * Check files and return their tracking data.
	 *
	 * @param array $file_paths          Array of file paths to check.
	 * @param array $allowed_directories Array of allowed directory paths.
	 *
	 * @return array Array of file data, each with 'path' and 'time' keys.
	 */
	private function check_files( array $file_paths, array $allowed_directories ): array {
		$files_data = array();

foreach ( $file_paths as $file_path ) {
			$resolved_path = $this->resolve_file_path( $file_path, $allowed_directories );

if ( is_null( $resolved_path ) ) {
				$this->log_file_tracking_warning( $file_path, 'Path could not be resolved or is outside allowed directories' );
				continue;
			}

$file_entry = $this->get_file_tracking_entry( $resolved_path );
			if ( is_null( $file_entry ) ) {
				$this->log_file_tracking_warning( $resolved_path, 'File does not exist or cannot be accessed' );
				continue;
			}

$files_data[] = $file_entry;
		}

return $files_data;
	}

/**
	 * Resolve a file path to an absolute path.
	 *
	 * Relative paths are resolved relative to the first directory in the allowed directories list.
	 * All paths are converted to physical paths (symlinks resolved) for consistent comparison.
	 * Paths that resolve outside the allowed directories are rejected for security.
	 *
	 * @param string $file_path           The file path to resolve (absolute or relative).
	 * @param array  $allowed_directories Array of allowed directory paths.
	 *
	 * @return string|null The resolved absolute path, or null if the path is invalid or outside allowed directories.
	 */
	private function resolve_file_path( string $file_path, array $allowed_directories ): ?string {
		if ( empty( $allowed_directories ) ) {
			return null;
		}

if ( ! path_is_absolute( $file_path ) ) {
			$base_path = trailingslashit( $allowed_directories[0] );
			$file_path = $base_path . ltrim( $file_path, '/' );
		}

$legacy_proxy = wc_get_container()->get( LegacyProxy::class );

$physical_path = $legacy_proxy->call_function( 'realpath', $file_path );
		if ( false === $physical_path ) {
			return null;
		}

$normalized_path = wp_normalize_path( $physical_path );

foreach ( $allowed_directories as $dir ) {
			$real_dir = $legacy_proxy->call_function( 'realpath', $dir );
			if ( false === $real_dir ) {
				continue;
			}

$normalized_dir = trailingslashit( wp_normalize_path( $real_dir ) );
			if ( 0 === strpos( $normalized_path, $normalized_dir ) ) {
				return $normalized_path;
			}
		}

return null;
	}

/**
	 * Log a warning about a file that couldn't be tracked.
	 *
	 * Each unique file path + reason combination is logged only once per the
	 * suppression TTL period to avoid flooding the log with repeated warnings.
	 * With a persistent object cache (Redis, Memcached), this works across requests.
	 * Without one, it prevents duplicates within the same request.
	 *
	 * @since 10.6.0
	 *
	 * @param string $file_path The file path that couldn't be tracked.
	 * @param string $reason    The reason the file couldn't be tracked.
	 */
	private function log_file_tracking_warning( string $file_path, string $reason ): void {
		/**
		 * Filter the TTL for suppressing duplicate file tracking warnings.
		 *
		 * By default, each unique warning (file path + reason) is logged only once per hour
		 * to avoid flooding the log. Use this filter to customize the suppression period.
		 * Return 0 to disable suppression and log all warnings.
		 *
		 * @since 10.6.0
		 *
		 * @param int    $ttl       The suppression TTL in seconds. Default is HOUR_IN_SECONDS.
		 * @param string $file_path The file path that couldn't be tracked.
		 * @param string $reason    The reason the file couldn't be tracked.
		 */
		$suppression_ttl = apply_filters(
			'woocommerce_rest_api_cache_file_warning_suppression_ttl',
			self::$file_warning_suppression_ttl,
			$file_path,
			$reason
		);

if ( $suppression_ttl > 0 ) {
			$warning_key = 'wc_rest_file_warning_' . md5( $file_path . '|' . $reason );

if ( false !== wp_cache_get( $warning_key, self::$warning_cache_group ) ) {
				return;
			}

wp_cache_set( $warning_key, true, self::$warning_cache_group, $suppression_ttl );
		}

$logger = wc_get_container()->get( LegacyProxy::class )->call_function( 'wc_get_logger' );
		$logger->warning(
			sprintf(
				'REST API cache: Could not track file "%s" for cache invalidation. Reason: %s',
				$file_path,
				$reason
			),
			array( 'source' => 'rest-api-cache' )
		);
	}

/**
	 * Get file tracking entry for a resolved path.
	 *
	 * @since 10.6.0
	 *
	 * @param string $resolved_path The resolved absolute file path.
	 *
	 * @return array{path: string, time: int}|null File entry with path and time, or null if file can't be accessed.
	 */
	private function get_file_tracking_entry( string $resolved_path ): ?array {
		$legacy_proxy = wc_get_container()->get( LegacyProxy::class );

// phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- We handle the error gracefully.
		$mtime = @$legacy_proxy->call_function( 'filemtime', $resolved_path );
		if ( false === $mtime ) {
			return null;
		}

return array(
			'path' => $resolved_path,
			'time' => $mtime,
		);
	}

/**
	 * Get a cached response, but only if it's valid (otherwise the cached response will be invalidated).
	 *
	 * @param WP_REST_Request<array<string, mixed>> $request              The request object.
	 * @param array                                 $cached_config        Built caching configuration from build_cache_config().
	 * @param bool                                  $cache_headers_enabled Whether to add cache control headers.
	 *
	 * @return WP_REST_Response|null Cached response, or null if not available or has been invalidated.
	 */
	private function get_cached_response( WP_REST_Request $request, array $cached_config, bool $cache_headers_enabled ): ?WP_REST_Response { // phpcs:ignore Squiz.Commenting.FunctionComment.IncorrectTypeHint
		$cache_key      = $cached_config['cache_key'];
		$entity_type    = $cached_config['entity_type'];
		$cache_ttl      = $cached_config['cache_ttl'];
		$relevant_hooks = $cached_config['relevant_hooks'];

$cached = wp_cache_get( $cache_key, self::$cache_group );

if ( ! is_array( $cached ) || ! array_key_exists( 'data', $cached ) || ! isset( $cached['entity_versions'], $cached['created_at'] ) ) {
			return null;
		}

$legacy_proxy    = wc_get_container()->get( LegacyProxy::class );
		$current_time    = $legacy_proxy->call_function( 'time' );
		$expiration_time = $cached['created_at'] + $cache_ttl;
		if ( $current_time >= $expiration_time ) {
			wp_cache_delete( $cache_key, self::$cache_group );
			return null;
		}

if ( ! empty( $relevant_hooks ) ) {
			$current_hooks_hash = $this->generate_hooks_hash( $relevant_hooks );
			$cached_hooks_hash  = $cached['hooks_hash'] ?? '';

if ( $current_hooks_hash !== $cached_hooks_hash ) {
				wp_cache_delete( $cache_key, self::$cache_group );
				return null;
			}
		}

// Validate files hash if files are being tracked.
		$relevant_files = $cached_config['relevant_files'];
		if ( ! empty( $relevant_files ) ) {
			$cached_files_hash  = $cached['files_hash'] ?? '';
			$current_files_hash = $this->generate_files_hash( $relevant_files );

if ( $current_files_hash !== $cached_files_hash ) {
				wp_cache_delete( $cache_key, self::$cache_group );
				return null;
			}
		}

// Validate version strings hash if version strings are being tracked.
		$relevant_version_strings = $cached_config['relevant_version_strings'];
		if ( ! empty( $relevant_version_strings ) ) {
			$cached_version_strings_hash  = $cached['version_strings_hash'] ?? '';
			$current_version_strings_hash = $this->generate_version_strings_hash( $relevant_version_strings );

if ( $current_version_strings_hash !== $cached_version_strings_hash ) {
				wp_cache_delete( $cache_key, self::$cache_group );
				return null;
			}
		}

if ( ! is_null( $this->version_string_generator ) ) {
			foreach ( $cached['entity_versions'] as $entity_id => $cached_version ) {
				$version_id      = "{$entity_type}_{$entity_id}";
				$current_version = $this->version_string_generator->get_version( $version_id );
				if ( $current_version !== $cached_version ) {
					wp_cache_delete( $cache_key, self::$cache_group );
					return null;
				}
			}
		}

// At this point the cached response is valid.

// Check if client sent an ETag and it matches - if so, return 304 Not Modified.
		$cached_etag  = $cached['etag'] ?? '';
		$request_etag = $request->get_header( 'if-none-match' );

$response_headers = array();

if ( $cache_headers_enabled ) {
			$legacy_proxy      = wc_get_container()->get( LegacyProxy::class );
			$is_user_logged_in = $legacy_proxy->call_function( 'is_user_logged_in' );
			$cache_visibility  = $cached_config['vary_by_user'] && $is_user_logged_in ? 'private' : 'public';

if ( ! empty( $cached_etag ) ) {
				$response_headers['ETag'] = $cached_etag;
			}
			$response_headers['Cache-Control'] = $cache_visibility . ', must-revalidate, max-age=' . $cache_ttl;

// If the server adds a 'Date' header by itself there will be two such headers in the response.
			// To help disambiguate them, we add also an 'X-WC-Date' header with the proper value.
			// @phpstan-ignore-next-line argument.type -- created_at is int, stored by store_cached_response.
			$created_at                    = gmdate( 'D, d M Y H:i:s', intval( $cached['created_at'] ) ) . ' GMT';
			$response_headers['Date']      = $created_at;
			$response_headers['X-WC-Date'] = $created_at;

if ( ! empty( $cached_etag ) && $request_etag === $cached_etag ) {
				$cache_control         = $response_headers['Cache-Control'];
				$not_modified_response = $this->create_not_modified_response( $cached_etag, $cache_control, $request, $cached_config['endpoint_id'] );
				if ( $not_modified_response ) {
					$not_modified_response->header( 'Date', $response_headers['Date'] );
					$not_modified_response->header( 'X-WC-Date', $response_headers['X-WC-Date'] );
					return $not_modified_response;
				}
			}
		}

$response = new WP_REST_Response( $cached['data'], $cached['status_code'] ?? 200 );

foreach ( $response_headers as $name => $value ) {
			$response->header( $name, $value );
		}

if ( ! empty( $cached['headers'] ) ) {
			foreach ( $cached['headers'] as $name => $value ) {
				$response->header( $name, $value );
			}
		}

return $response;
	}

/**
	 * Store a response in cache.
	 *
	 * @param array $args {
	 *     Arguments for storing the cached response.
	 *
	 *     @type string $cache_key                The cache key.
	 *     @type mixed  $data                     The response data to cache.
	 *     @type int    $status_code              The HTTP status code of the response.
	 *     @type string $entity_type              The entity type.
	 *     @type array  $entity_ids               Array of entity IDs in the response.
	 *     @type int    $cache_ttl                Cache TTL in seconds.
	 *     @type array  $relevant_hooks           Hook names to track for invalidation.
	 *     @type array  $relevant_files           File paths to track for invalidation.
	 *     @type array  $relevant_version_strings Version string IDs to track for invalidation.
	 *     @type array  $headers                  Response headers to cache.
	 *     @type string $etag                     ETag for the response.
	 * }
	 */
	private function store_cached_response( array $args ): void {
		$status_code              = $args['status_code'];
		$relevant_hooks           = $args['relevant_hooks'];
		$relevant_files           = $args['relevant_files'];
		$relevant_version_strings = $args['relevant_version_strings'];
		$headers                  = $args['headers'] ?? array();
		$etag                     = $args['etag'] ?? '';

$entity_versions = array();
		if ( ! is_null( $this->version_string_generator ) ) {
			foreach ( $args['entity_ids'] as $entity_id ) {
				$version_id = "{$args['entity_type']}_{$entity_id}";
				$version    = $this->version_string_generator->get_version( $version_id );
				if ( $version ) {
					$entity_versions[ $entity_id ] = $version;
				}
			}
		}

$legacy_proxy = wc_get_container()->get( LegacyProxy::class );
		$cache_data   = array(
			'data'            => $args['data'],
			'entity_versions' => $entity_versions,
			'created_at'      => $legacy_proxy->call_function( 'time' ),
		);

if ( 200 !== $status_code ) {
			$cache_data['status_code'] = $status_code;
		}

if ( ! empty( $relevant_hooks ) ) {
			$cache_data['hooks_hash'] = $this->generate_hooks_hash( $relevant_hooks );
		}

if ( ! empty( $relevant_files ) ) {
			$files_hash = $this->generate_files_hash( $relevant_files );
			if ( ! empty( $files_hash ) ) {
				$cache_data['files_hash'] = $files_hash;
			}
		}

if ( ! empty( $relevant_version_strings ) ) {
			$version_strings_hash = $this->generate_version_strings_hash( $relevant_version_strings );
			if ( ! empty( $version_strings_hash ) ) {
				$cache_data['version_strings_hash'] = $version_strings_hash;
			}
		}

if ( ! empty( $headers ) ) {
			$cache_data['headers'] = $headers;
		}

if ( ! empty( $etag ) ) {
			$cache_data['etag'] = $etag;
		}

wp_cache_set( $args['cache_key'], $cache_data, self::$cache_group, $args['cache_ttl'] );
	}

/**
	 * Handle rest_send_nocache_headers filter to prevent WordPress from overriding our cache headers.
	 *
	 * @internal
	 *
	 * @param bool $send_no_cache_headers Whether to send no-cache headers.
	 *
	 * @return bool False if we're handling caching for this request, original value otherwise.
	 */
	public function handle_rest_send_nocache_headers( bool $send_no_cache_headers ): bool {
		if ( ! $this->is_handling_cached_endpoint ) {
			return $send_no_cache_headers;
		}

$this->is_handling_cached_endpoint = false;
		return false;
	}
}