[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       * Fetches a value from the cache.
  34       *
  35       * @since 7.0.0
  36       *
  37       * @param string $key           The unique key of this item in the cache.
  38       * @param mixed  $default_value Default value to return if the key does not exist.
  39       * @return mixed The value of the item from the cache, or $default_value in case of cache miss.
  40       */
  41  	public function get( $key, $default_value = null ) {
  42          $found = false;
  43          $value = wp_cache_get( $key, self::CACHE_GROUP, false, $found );
  44  
  45          if ( ! $found ) {
  46              return $default_value;
  47          }
  48  
  49          return $value;
  50      }
  51  
  52      /**
  53       * Persists data in the cache, uniquely referenced by a key with an optional expiration TTL time.
  54       *
  55       * @since 7.0.0
  56       *
  57       * @param string                $key   The key of the item to store.
  58       * @param mixed                 $value The value of the item to store, must be serializable.
  59       * @param null|int|DateInterval $ttl   Optional. The TTL value of this item.
  60       * @return bool True on success and false on failure.
  61       */
  62  	public function set( $key, $value, $ttl = null ): bool {
  63          $expire = $this->ttl_to_seconds( $ttl );
  64  
  65          return wp_cache_set( $key, $value, self::CACHE_GROUP, $expire );
  66      }
  67  
  68      /**
  69       * Delete an item from the cache by its unique key.
  70       *
  71       * @since 7.0.0
  72       *
  73       * @param string $key The unique cache key of the item to delete.
  74       * @return bool True if the item was successfully removed. False if there was an error.
  75       */
  76  	public function delete( $key ): bool {
  77          return wp_cache_delete( $key, self::CACHE_GROUP );
  78      }
  79  
  80      /**
  81       * Wipes clean the entire cache's keys.
  82       *
  83       * This method only clears the cache group used by this adapter. If the underlying
  84       * cache implementation does not support group flushing, this method returns false.
  85       *
  86       * @since 7.0.0
  87       *
  88       * @return bool True on success and false on failure.
  89       */
  90  	public function clear(): bool {
  91          if ( ! function_exists( 'wp_cache_supports' ) || ! wp_cache_supports( 'flush_group' ) ) {
  92              return false;
  93          }
  94  
  95          return wp_cache_flush_group( self::CACHE_GROUP );
  96      }
  97  
  98      /**
  99       * Obtains multiple cache items by their unique keys.
 100       *
 101       * @since 7.0.0
 102       *
 103       * @param iterable<string> $keys          A list of keys that can be obtained in a single operation.
 104       * @param mixed            $default_value Default value to return for keys that do not exist.
 105       * @return array<string, mixed> A list of key => value pairs.
 106       */
 107  	public function getMultiple( $keys, $default_value = null ): array {
 108          /**
 109           * Keys array.
 110           *
 111           * @var array<string> $keys_array
 112           */
 113          $keys_array = $this->iterable_to_array( $keys );
 114          $values     = wp_cache_get_multiple( $keys_array, self::CACHE_GROUP );
 115          $result     = array();
 116  
 117          foreach ( $keys_array as $key ) {
 118              if ( false === $values[ $key ] ) {
 119                  // Could be a stored false or a cache miss — disambiguate via get().
 120                  $result[ $key ] = $this->get( $key, $default_value );
 121              } else {
 122                  $result[ $key ] = $values[ $key ];
 123              }
 124          }
 125  
 126          return $result;
 127      }
 128  
 129      /**
 130       * Persists a set of key => value pairs in the cache, with an optional TTL.
 131       *
 132       * @since 7.0.0
 133       *
 134       * @param iterable<string, mixed> $values A list of key => value pairs for a multiple-set operation.
 135       * @param null|int|DateInterval   $ttl    Optional. The TTL value of this item.
 136       * @return bool True on success and false on failure.
 137       */
 138  	public function setMultiple( $values, $ttl = null ): bool {
 139          $values_array = $this->iterable_to_array( $values );
 140          $expire       = $this->ttl_to_seconds( $ttl );
 141          $results      = wp_cache_set_multiple( $values_array, self::CACHE_GROUP, $expire );
 142  
 143          // Return true only if all operations succeeded.
 144          return ! in_array( false, $results, true );
 145      }
 146  
 147      /**
 148       * Deletes multiple cache items in a single operation.
 149       *
 150       * @since 7.0.0
 151       *
 152       * @param iterable<string> $keys A list of string-based keys to be deleted.
 153       * @return bool True if the items were successfully removed. False if there was an error.
 154       */
 155  	public function deleteMultiple( $keys ): bool {
 156          $keys_array = $this->iterable_to_array( $keys );
 157          $results    = wp_cache_delete_multiple( $keys_array, self::CACHE_GROUP );
 158  
 159          // Return true only if all operations succeeded.
 160          return ! in_array( false, $results, true );
 161      }
 162  
 163      /**
 164       * Determines whether an item is present in the cache.
 165       *
 166       * @since 7.0.0
 167       *
 168       * @param string $key The cache item key.
 169       * @return bool True if the item exists in the cache, false otherwise.
 170       */
 171  	public function has( $key ): bool {
 172          $found = false;
 173          wp_cache_get( $key, self::CACHE_GROUP, false, $found );
 174  
 175          return (bool) $found;
 176      }
 177  
 178      /**
 179       * Converts a PSR-16 TTL value to seconds for WordPress cache functions.
 180       *
 181       * @since 7.0.0
 182       *
 183       * @param null|int|DateInterval $ttl The TTL value.
 184       * @return int The TTL in seconds, or 0 for no expiration.
 185       */
 186  	private function ttl_to_seconds( $ttl ): int {
 187          if ( null === $ttl ) {
 188              return 0;
 189          }
 190  
 191          if ( $ttl instanceof DateInterval ) {
 192              $now = new DateTime();
 193              $end = ( clone $now )->add( $ttl );
 194  
 195              return $end->getTimestamp() - $now->getTimestamp();
 196          }
 197  
 198          return max( 0, (int) $ttl );
 199      }
 200  
 201      /**
 202       * Converts an iterable to an array.
 203       *
 204       * @since 7.0.0
 205       *
 206       * @param iterable<mixed> $items The iterable to convert.
 207       * @return array<mixed> The array.
 208       */
 209  	private function iterable_to_array( $items ): array {
 210          if ( is_array( $items ) ) {
 211              return $items;
 212          }
 213  
 214          return iterator_to_array( $items );
 215      }
 216  }