Add Tribe__Cache::has method

readme.txt

@@ -1,5 +1,10 @@
 == Changelog ==
 
+= [TBD] TBD =
+
+* Feature - Add the `has( string $key, string $expiration_trigger = '' ): bool`; add the `&$found` parameter to the `Tribe__Cache::get` method.
+* Feature - Add the `has_shape( mixed $array, array $shape ): bool ` method to the `Tribe__Utils__Array` class.
+
 = [5.2.3] 2024-02-19 =
 
 * Tweak - Refactor JS logic to prevent ticketing of recurring events. [ET-1936]

src/Tribe/Cache.php

@@ -1,11 +1,18 @@
 <?php
+/**
+ * Manage setting and expiring cached data
+ *
+ * Select actions can be used to force cached
+ */
 
 /**
  * Manage setting and expiring cached data
  *
  * Select actions can be used to force cached
  * data to expire. Implemented so far:
  *  - save_post
+ *  - update main option
+ *  - regenerate rewrite rules
  *
  * When used in its ArrayAccess API the cache will provide non persistent storage.
  */
@@ -99,17 +106,21 @@ public function set_transient( $id, $value, $expiration = 0, $expiration_trigger
 	 *
 	 * Note: When a default value or callback is specified, this value gets set in the cache.
 	 *
+	 * @since 4.11.0
+	 * @since TBD Added the `$found` parameter.
+	 *
 	 * @param string       $id                 The key for the cached value.
 	 * @param string|array $expiration_trigger Optional. Hook to trigger cache invalidation.
 	 * @param mixed        $default            Optional. A default value or callback that returns a default value.
 	 * @param int          $expiration         Optional. When the default value expires, if it gets set.
 	 * @param mixed        $args               Optional. Args passed to callback.
+	 * @param bool         $found              Optional. Whether the value was found in the cache. Set by reference.
 	 *
 	 * @return mixed
 	 */
-	public function get( $id, $expiration_trigger = '', $default = false, $expiration = 0, $args = [] ) {
-		$group   = isset( $this->non_persistent_keys[ $id ] ) ? 'tribe-events-non-persistent' : 'tribe-events';
-		$value   = wp_cache_get( $this->get_id( $id, $expiration_trigger ), $group );
+	public function get( $id, $expiration_trigger = '', $default = false, $expiration = 0, $args = [], ?bool &$found = false ) {
+		$group = isset( $this->non_persistent_keys[ $id ] ) ? 'tribe-events-non-persistent' : 'tribe-events';
+		$value = wp_cache_get( $this->get_id( $id, $expiration_trigger ), $group, false, $found );
 
 		// Value found.
 		if ( false !== $value ) {
@@ -149,7 +160,7 @@ public function get_transient( $id, $expiration_trigger = '' ) {
 	 * @return bool
 	 */
 	public function delete( $id, $expiration_trigger = '' ) {
-		$group   = isset( $this->non_persistent_keys[ $id ] ) ? 'tribe-events-non-persistent' : 'tribe-events';
+		$group = isset( $this->non_persistent_keys[ $id ] ) ? 'tribe-events-non-persistent' : 'tribe-events';
 
 		// Delete from non-persistent keys list.
 		if ( 'tribe-events-non-persistent' === $group ) {
@@ -369,7 +380,6 @@ public function make_key( $components, $prefix = '', $sort = true ) {
 	 *
 	 * @return boolean Whether the offset exists in the cache.
 	 *@link  http://php.net/manual/en/arrayaccess.offsetexists.php
-	 *
 	 */
 	#[\ReturnTypeWillChange]
 	public function offsetExists( $offset ): bool {
@@ -499,7 +509,7 @@ public function warmup_post_caches( $post_ids, $update_post_meta_cache = false )
 
 		do {
 			$limit_clause = $limit < 0 ? sprintf( 'LIMIT %d,%d', $limit * $page, $limit ) : '';
-			$page++;
+			++$page;
 			$these_ids    = array_splice( $buffer, 0, $limit );
 			$interval     = implode( ',', array_map( 'absint', $these_ids ) );
 			$posts_query  = "SELECT * FROM {$wpdb->posts} WHERE ID IN ({$interval}) {$limit_clause}";
@@ -604,7 +614,6 @@ public function get_chunkable_transient( $id, $expiration_trigger = '' ) {
 	 *
 	 * The method will redirect to the `set_transient` function if the site is using object caching.
 	 *
-	 *
 	 * @since 4.13.3
 	 *
 	 * @param string               $id                 The transient ID.
@@ -643,4 +652,21 @@ public function set_chunkable_transient( $id, $value, $expiration = 0, $expirati
 
 		return true;
 	}
+
+	/**
+	 * Checks whether a value is set in the cache or not.
+	 *
+	 * @since TBD
+	 *
+	 * @param string $id                 The key for the cached value.
+	 * @param string $expiration_trigger Optional. Hook to trigger cache invalidation.
+	 *
+	 * @return bool Whether the value is set in the cache or not.
+	 */
+	public function has( $id, $expiration_trigger = '' ): bool {
+		$group = isset( $this->non_persistent_keys[ $id ] ) ? 'tribe-events-non-persistent' : 'tribe-events';
+		wp_cache_get( $this->get_id( $id, $expiration_trigger ), $group, false, $found );
+
+		return $found;
+	}
 }

src/Tribe/Utils/Array.php

@@ -732,5 +732,55 @@ public static function usearch( $needle, array $haystack, callable $callback ) {
 
 			return false;
 		}
+
+		/**
+		 * Checks if an array has a specific shape.
+		 *
+		 * @since TBD
+		 *
+		 * @param array                      $array The array to check.
+		 * @param array<string|int,callable> $shape The shape to check for. Each key, either a string or an integer,
+		 *                                          maps to a callable that will be used to validate the value at that key.
+		 *                                          The callable must have the signature `fn( mixed $value ) :bool`.
+		 * @param bool                       $strict Whether the array should only contain the keys specified in the shape.
+		 *
+		 * @return bool Whether the array has the specified shape.
+		 */
+		public static function has_shape( $array, array $shape, bool $strict = false ): bool {
+			if ( ! is_array( $array ) ) {
+				return false;
+			}
+
+			if (
+				$strict
+				&& (
+					array_intersect_key( $array, $shape ) !== $array
+					||
+					array_diff_key( $array, $shape ) !== []
+				)
+			) {
+				return false;
+			}
+
+			if ( count( array_intersect_key( $shape, $array ) ) < count( $shape ) ) {
+				return false;
+			}
+
+			foreach ( $shape as $key => $check ) {
+				if ( ! is_callable( $check ) ) {
+					throw new \BadMethodCallException( 'The shape array must contain only callables as values.' );
+				}
+
+				try {
+					if ( ! $check( $array[ $key ] ) ) {
+						return false;
+					}
+				} catch ( \Throwable $th ) {
+					return false;
+				}
+			}
+
+			return true;
+		}
 	}
 }

tests/unit/Tribe/Utils/ArrayTest.php

@@ -4,7 +4,7 @@
 
 class Tribe__Utils__Array_Test extends \Codeception\Test\Unit {
 	public function shape_filter_data_provider() {
-		$test_shape = [
+		$test_shape          = [
 			'a'       =>
 				[
 					'deeply' =>
@@ -306,10 +306,10 @@ public function test_shape_filter( array $input, array $shape, array $expected )
 	}
 
 	public function usearch_data_provider() {
-		$value_gt_needle = static function ( $needle, $value ): bool {
+		$value_gt_needle              = static function ( $needle, $value ): bool {
 			return $value > $needle;
 		};
-		$matches_needle = static function ( $needle, $value ): bool {
+		$matches_needle               = static function ( $needle, $value ): bool {
 			return $value === $needle;
 		};
 		$callback_using_value_and_key = static function ( $needle, $value, $key ): bool {
@@ -352,4 +352,90 @@ public function usearch_data_provider() {
 	public function test_usearch( $needle, array $haystack, $expected, callable $callback ) {
 		$this->assertEquals( $expected, Arr::usearch( $needle, $haystack, $callback ) );
 	}
+
+	public function has_shape_data_provider(): array {
+		return [
+			'not an array'                                                     => [ 'foo', [], true, false ],
+			'empty array, empty shape'                                         => [ [], [], true, true ],
+			'empty array, non-empty shape, strict'                             => [
+				[],
+				[ 'foo' => 'is_string' ],
+				true,
+				false
+			],
+			'empty array, non-empty shape, non-strict'                         => [
+				[],
+				[ 'foo' => 'is_string' ],
+				false,
+				false
+			],
+			'non-empty array, function shape, missing key, strict'             => [
+				[ 'foo' => 23 ],
+				[ 'bar' => 'is_string' ],
+				true,
+				false
+			],
+			'non-empty array, function shape, missing key, non-strict'         => [
+				[ 'foo' => 23 ],
+				[ 'bar' => 'is_string' ],
+				false,
+				false
+			],
+			'non-empty array, function shape, extra key, strict'               => [
+				[ 'foo' => 23, 'bar' => 'baz' ],
+				[ 'foo' => 'is_int' ],
+				true,
+				false
+			],
+			'non-empty array, function shape, extra key, non-strict'           => [
+				[ 'foo' => 23, 'bar' => 'baz' ],
+				[ 'foo' => 'is_int' ],
+				false,
+				true
+			],
+			'non-empty array, closure shape, all key fail failure, strict'     => [
+				[ 'foo' => 23, 'bar' => 89 ],
+				[ 'foo' => fn( $foo ) => $foo === 'hello', 'bar' => fn( $bar ) => $bar === 'world' ],
+				true,
+				false
+			],
+			'non-empty array, closure shape, all key fail failure, non-strict' => [
+				[ 'foo' => 23, 'bar' => 89 ],
+				[ 'foo' => fn( $foo ) => $foo === 'hello', 'bar' => fn( $bar ) => $bar === 'world' ],
+				false,
+				false
+			],
+			'non-empty array, closure shape, all key pass, strict'             => [
+				[ 'foo' => 'hello', 'bar' => 'world' ],
+				[ 'foo' => fn( $foo ) => $foo === 'hello', 'bar' => fn( $bar ) => $bar === 'world' ],
+				true,
+				true
+			],
+			'non-empty array, closure shape, all key pass, non-strict '        => [
+				[ 'foo' => 'hello', 'bar' => 'world' ],
+				[ 'foo' => fn( $foo ) => $foo === 'hello', 'bar' => fn( $bar ) => $bar === 'world' ],
+				false,
+				true
+			],
+			'non-empty array, closure shape, some key pass, strict'            => [
+				[ 'foo' => 'hello', 'bar' => 89 ],
+				[ 'foo' => fn( $foo ) => $foo === 'hello', 'bar' => fn( $bar ) => $bar === 'world' ],
+				true,
+				false
+			],
+			'non-empty array, closure shape, some key pass, non-strict'        => [
+				[ 'foo' => 'hello', 'bar' => 89 ],
+				[ 'foo' => fn( $foo ) => $foo === 'hello', 'bar' => fn( $bar ) => $bar === 'world' ],
+				false,
+				false
+			],
+		];
+	}
+
+	/**
+	 * @dataProvider has_shape_data_provider
+	 */
+	public function test_has_shape( $input, $shape, $strict, $expected ): void {
+		$this->assertEquals( $expected, Arr::has_shape( $input, $shape, $strict ) );
+	}
 }