<?php
/**
 * Values worked out through a filter, kept while the filter stays as it is.
 *
 * @package Careback
 */

namespace Careback;

defined( 'ABSPATH' ) || exit;

/**
 * Keeps a value built through a filter until the callbacks on that filter
 * change.
 *
 * The status and route registries are read many times per request — every
 * status of every row of the Requests screen asks them several questions —
 * and building one means running the filter, completing and sorting the
 * list. What a registration answers depends only on who registered, so the
 * list is built again only when a callback is added to or taken off the
 * filter: `remove_filter()` and `add_filter()` are seen at once, as before.
 * A callback must answer the same every time it is asked.
 *
 * The callbacks are compared as they are held (closures and objects by
 * identity), and the cache keeps them, so a closure taken off cannot be
 * freed and its place reused by a new one that would look the same.
 */
final class Hook_Cache {

	/**
	 * Per filter: the callbacks the value was built with, and the value.
	 *
	 * @var array<string,array{callbacks:array,value:mixed}>
	 */
	private static $entries = array();

	/**
	 * The value built by `$build`, from the cache while the callbacks on `$tag`
	 * are those it was built with.
	 *
	 * @param string   $tag   Filter the value is worked out through.
	 * @param callable $build Builds the value; runs the filter itself.
	 * @return mixed
	 */
	public static function get( $tag, $build ) {
		$tag       = (string) $tag;
		$callbacks = self::callbacks( $tag );

		if ( isset( self::$entries[ $tag ] ) && self::$entries[ $tag ]['callbacks'] === $callbacks ) {
			return self::$entries[ $tag ]['value'];
		}

		$value = call_user_func( $build );

		self::$entries[ $tag ] = array(
			'callbacks' => $callbacks,
			'value'     => $value,
		);

		return $value;
	}

	/**
	 * The callbacks on a filter, by priority, as WordPress holds them; empty
	 * when there are none.
	 *
	 * @param string $tag Filter.
	 * @return array
	 */
	public static function callbacks( $tag ) {
		global $wp_filter;

		return isset( $wp_filter[ $tag ] ) && $wp_filter[ $tag ] instanceof \WP_Hook ? $wp_filter[ $tag ]->callbacks : array();
	}

	/**
	 * Forgets every value, so the next read builds it again.
	 *
	 * @return void
	 */
	public static function flush() {
		self::$entries = array();
	}
}