<?php
/**
 * Decides whether measurement is permitted for this visitor.
 *
 * @package AdPix\Analytics
 */

declare( strict_types = 1 );

namespace AdPix\Analytics\Service;

use AdPix\Analytics\Contracts\SettingsRepositoryInterface;
use AdPix\Analytics\Contracts\VisitorContextInterface;

defined( 'ABSPATH' ) || exit;

/**
 * The single answer to "are we allowed to send this".
 *
 * Consent has to be checked on the server as well as in the browser, because a server-side purchase
 * event bypasses the tag entirely — a visitor who declined statistics in the banner would otherwise
 * still have their order sent from PHP, which is exactly the outcome the banner promised would not
 * happen. Putting the decision in one object means every sender is bound by it and none of them can
 * implement it slightly differently.
 */
final class ConsentGate {

	/**
	 * The category that ordinary measurement falls under.
	 */
	public const CATEGORY_STATISTICS = 'statistics';

	/**
	 * The category advertising and remarketing data falls under.
	 */
	public const CATEGORY_MARKETING = 'marketing';

	/**
	 * @var SettingsRepositoryInterface
	 */
	private $settings;

	/**
	 * @var VisitorContextInterface
	 */
	private $visitor;

	/**
	 * @param SettingsRepositoryInterface $settings Configuration source.
	 * @param VisitorContextInterface     $visitor  The current request's visitor.
	 */
	public function __construct( SettingsRepositoryInterface $settings, VisitorContextInterface $visitor ) {
		$this->settings = $settings;
		$this->visitor  = $visitor;
	}

	/**
	 * Whether an event in this category may be sent.
	 *
	 * @param string                       $category Consent category.
	 * @param VisitorContextInterface|null $visitor  Whose decision to read; defaults to the current
	 *                                               request. An order reports the decision the customer
	 *                                               made at checkout, not whoever is logged into
	 *                                               wp-admin when the status changes.
	 * @return bool
	 */
	public function allows( string $category = self::CATEGORY_STATISTICS, ?VisitorContextInterface $visitor = null ): bool {
		$visitor = null !== $visitor ? $visitor : $this->visitor;

		// Opt-out is absolute. It is the visitor's own decision rather than a category preference, so it
		// is honoured whether or not the site has consent enforcement switched on.
		if ( $visitor->has_opted_out() ) {
			$allowed = false;
		} elseif ( $this->settings->load()->flag( 'respect_consent' ) ) {
			$allowed = $visitor->allows( $category );
		} else {
			$allowed = true;
		}

		/**
		 * Filters whether a server-side event may be sent for this visitor.
		 *
		 * Useful for sites whose consent state lives somewhere this plugin cannot see, such as a
		 * consent management platform that keeps its decision server-side.
		 *
		 * @since 1.0.0
		 *
		 * @param bool                    $allowed  Whether sending is permitted.
		 * @param string                  $category Consent category being checked.
		 * @param VisitorContextInterface $visitor  The visitor whose decision was read.
		 */
		return (bool) apply_filters( 'adpix_analytics_consent_allows', $allowed, $category, $visitor );
	}
}