<?php declare( strict_types = 1 );

/**
 * Interface for defining platform-specific code for common Edge Cache code.
 *
 * NOTE: This interface is designed to be shared between the mu-plugin in Simple and Atomic. Each
 * plugin should implement this interface to allow all other shared code to operate in both environments.
 */
interface Edge_Cache_Platform {
	/**
	 * Send an API request to purge a specific hostname, logging the result.
	 *
	 * @param $domain - The domain to purge.
	 * @param $tags   - Associative array of tag:value tags to associate with this event in logs.
	 *
	 * @return bool - True on success, false on failure.
	 */
	public function purge_domain( $domain, $tags );

	/**
	 * Send an API request to purge a set of URIs, logging the result.
	 *
	 * @param $uris - An array of URIs to purge.
	 * @param $tags - Associative array of tag:value tags to associate with this event in logs.
	 *
	 * @return bool - True on success, false on failure.
	 */
	public function purge_uris( $uris, $tags );

	/**
	 * Get the current site / requestor's domain name.
	 *
	 * @return string - The domain name of the site being run/used.
	 */
	public function get_domain_name();

	/**
	 * Given a domain name, returns true if it can be purged.
	 *
	 * @param $domain - Domain name.
	 *
	 * @return bool - True if this domain is able to purge.
	 */
	public function can_purge_domain( $domain );

	/**
	 * Return a short string describing the current platform type.
	 *
	 * @return string - Current platform.
	 */
	public function get_platform_type();
}