[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * WP AI Client: WP_AI_Client_Cache class
   4   *
   5   * @package WordPress
   6   * @subpackage AI
   7   * @since 7.0.0
   8   */
   9  
  10  use WordPress\AiClientDependencies\Psr\SimpleCache\CacheInterface;
  11  
  12  /**
  13   * WordPress-specific PSR-16 cache adapter for the AI Client.
  14   *
  15   * Bridges PSR-16 cache operations to WordPress object cache functions,
  16   * enabling the AI client to leverage WordPress caching infrastructure.
  17   *
  18   * @since 7.0.0
  19   * @internal Intended only to wire up the PHP AI Client SDK to WordPress's caching system.
  20   * @access private
  21   */
  22  class WP_AI_Client_Cache implements CacheInterface {
  23  
  24      /**
  25       * Cache group used for all cache operations.
  26       *
  27       * @since 7.0.0
  28       * @var string
  29       */
  30      private const CACHE_GROUP = 'wp_ai_client';
  31  
  32      /**
  33       * Retrieves the cache group used for cache operations, applying a filter for customization.
  34       *
  35       * @since 7.1.0
  36       *
  37       * @return string Cache group name.
  38       */
  39  	private function get_cache_group(): string {
  40          /**
  41           * Filters the cache group used by the WP AI Client cache adapter.
  42           *
  43           * Allows integrators to change the object cache group under which AI client
  44           * items are stored. This is useful for avoiding key collisions, creating
  45           * environment-specific caches, or adapting to backend constraints.
  46           *
  47           * @since 7.1.0
  48           *
  49           * @param string $group The cache group.
  50           */
  51          return (string) apply_filters( 'wp_ai_client_cache_group', self::CACHE_GROUP );
  52      }
  53  
  54      /**
  55       * Fetches a value from the cache.
  56       *
  57       * @since 7.0.0
  58       *
  59       * @param string $key           The unique key of this item in the cache.
  60       * @param mixed  $default_value Default value to return if the key does not exist.
  61       * @return mixed The value of the item from the cache, or $default_value in case of cache miss.
  62       */
  63  	public function get( $key, $default_value = null ) {
  64          $found = false;
  65          $value = wp_cache_get( $key, $this->get_cache_group(), false, $found );
  66  
  67          if ( ! $found ) {
  68              return $default_value;
  69          }
  70  
  71          return $value;
  72      }
  73  
  74      /**
  75       * Persists data in the cache, uniquely referenced by a key with an optional expiration TTL time.
  76       *
  77       * @since 7.0.0
  78       *
  79       * @param string                $key   The key of the item to store.
  80       * @param mixed                 $value The value of the item to store, must be serializable.
  81       * @param null|int|DateInterval $ttl   Optional. The TTL value of this item.
  82       * @return bool True on success and false on failure.
  83       */
  84  	public function set( $key, $value, $ttl = null ): bool {
  85          $expire = $this->ttl_to_seconds( $ttl );
  86  
  87          return wp_cache_set( $key, $value, $this->get_cache_group(), $expire );
  88      }
  89  
  90      /**
  91       * Delete an item from the cache by its unique key.
  92       *
  93       * @since 7.0.0
  94       *
  95       * @param string $key The unique cache key of the item to delete.
  96       * @return bool True if the item was successfully removed. False if there was an error.
  97       */
  98  	public function delete( $key ): bool {
  99          return wp_cache_delete( $key, $this->get_cache_group() );
 100      }
 101  
 102      /**
 103       * Wipes clean the entire cache's keys.
 104       *
 105       * This method only clears the cache group used by this adapter. If the underlying
 106       * cache implementation does not support group flushing, this method returns false.
 107       *
 108       * @since 7.0.0
 109       *
 110       * @return bool True on success and false on failure.
 111       */
 112  	public function clear(): bool {
 113          if ( ! function_exists( 'wp_cache_supports' ) || ! wp_cache_supports( 'flush_group' ) ) {
 114              return false;
 115          }
 116  
 117          return wp_cache_flush_group( $this->get_cache_group() );
 118      }
 119  
 120      /**
 121       * Obtains multiple cache items by their unique keys.
 122       *
 123       * @since 7.0.0
 124       *
 125       * @param iterable<string> $keys          A list of keys that can be obtained in a single operation.
 126       * @param mixed            $default_value Default value to return for keys that do not exist.
 127       * @return array<string, mixed> A list of key => value pairs.
 128       */
 129  	public function getMultiple( $keys, $default_value = null ): array {
 130          /**
 131           * Keys array.
 132           *
 133           * @var array<string> $keys_array
 134           */
 135          $keys_array = $this->iterable_to_array( $keys );
 136          $values     = wp_cache_get_multiple( $keys_array, $this->get_cache_group() );
 137          $result     = array();
 138  
 139          foreach ( $keys_array as $key ) {
 140              if ( false === $values[ $key ] ) {
 141                  // Could be a stored false or a cache miss — disambiguate via get().
 142                  $result[ $key ] = $this->get( $key, $default_value );
 143              } else {
 144                  $result[ $key ] = $values[ $key ];
 145              }
 146          }
 147  
 148          return $result;
 149      }
 150  
 151      /**
 152       * Persists a set of key => value pairs in the cache, with an optional TTL.
 153       *
 154       * @since 7.0.0
 155       *
 156       * @param iterable<string, mixed> $values A list of key => value pairs for a multiple-set operation.
 157       * @param null|int|DateInterval   $ttl    Optional. The TTL value of this item.
 158       * @return bool True on success and false on failure.
 159       */
 160  	public function setMultiple( $values, $ttl = null ): bool {
 161          $values_array = $this->iterable_to_array( $values );
 162          $expire       = $this->ttl_to_seconds( $ttl );
 163          $results      = wp_cache_set_multiple( $values_array, $this->get_cache_group(), $expire );
 164  
 165          // Return true only if all operations succeeded.
 166          return ! in_array( false, $results, true );
 167      }
 168  
 169      /**
 170       * Deletes multiple cache items in a single operation.
 171       *
 172       * @since 7.0.0
 173       *
 174       * @param iterable<string> $keys A list of string-based keys to be deleted.
 175       * @return bool True if the items were successfully removed. False if there was an error.
 176       */
 177  	public function deleteMultiple( $keys ): bool {
 178          $keys_array = $this->iterable_to_array( $keys );
 179          $results    = wp_cache_delete_multiple( $keys_array, $this->get_cache_group() );
 180  
 181          // Return true only if all operations succeeded.
 182          return ! in_array( false, $results, true );
 183      }
 184  
 185      /**
 186       * Determines whether an item is present in the cache.
 187       *
 188       * @since 7.0.0
 189       *
 190       * @param string $key The cache item key.
 191       * @return bool True if the item exists in the cache, false otherwise.
 192       */
 193  	public function has( $key ): bool {
 194          $found = false;
 195          wp_cache_get( $key, $this->get_cache_group(), false, $found );
 196  
 197          return (bool) $found;
 198      }
 199  
 200      /**
 201       * Converts a PSR-16 TTL value to seconds for WordPress cache functions.
 202       *
 203       * @since 7.0.0
 204       *
 205       * @param null|int|DateInterval $ttl The TTL value.
 206       * @return int The TTL in seconds, or 0 for no expiration.
 207       */
 208  	private function ttl_to_seconds( $ttl ): int {
 209          if ( null === $ttl ) {
 210              return 0;
 211          }
 212  
 213          if ( $ttl instanceof DateInterval ) {
 214              $now = new DateTime();
 215              $end = ( clone $now )->add( $ttl );
 216  
 217              return $end->getTimestamp() - $now->getTimestamp();
 218          }
 219  
 220          return max( 0, (int) $ttl );
 221      }
 222  
 223      /**
 224       * Converts an iterable to an array.
 225       *
 226       * @since 7.0.0
 227       *
 228       * @param iterable<mixed> $items The iterable to convert.
 229       * @return array<mixed> The array.
 230       */
 231  	private function iterable_to_array( $items ): array {
 232          if ( is_array( $items ) ) {
 233              return $items;
 234          }
 235  
 236          return iterator_to_array( $items );
 237      }
 238  }