<?php
/**
 * Event seam.
 *
 * @package Rahkar\WP
 */

declare( strict_types = 1 );

namespace Rahkar\WP\Support;

defined( 'ABSPATH' ) || exit;

/**
 * Where modules report what happened, for whoever is listening (EVENTS-v1.md §10).
 *
 * Today the only listener is the Rahkar Foroosh connector, and only while the site
 * is connected. A module neither knows nor cares: it calls {@see self::emit()},
 * which costs one `has_action()` when nobody listens. Building an expensive body
 * should be guarded with {@see self::listening()} first.
 *
 * Types a module emits must be registered with the `rahkar_wp_event_types`
 * filter; the connector drops unregistered ones, so nothing outside the contract
 * leaves the site by accident.
 */
final class Events {

	public const ACTION = 'rahkar_wp_event';

	public const TYPES_FILTER = 'rahkar_wp_event_types';

	/**
	 * Is anyone listening?
	 */
	public static function listening(): bool {
		return false !== has_action( self::ACTION );
	}

	/**
	 * Report an event.
	 *
	 * @param string               $type       Contract event type, e.g. `cart.reminder_sent`.
	 * @param array<string, mixed> $data       Body, in contract shape.
	 * @param int|null             $occurredAt Unix time it happened; now when null.
	 */
	public static function emit( string $type, array $data, ?int $occurredAt = null ): void {
		if ( self::listening() ) {
			// Spelled out rather than self::ACTION, so the plugin prefix is visible to
			// Plugin Check; the constant stays for the listeners.
			do_action( 'rahkar_wp_event', $type, $data, $occurredAt );
		}
	}
}