<?php
/**
 * The third-party plugin integrations (#5), and what they share.
 *
 * @package ActivityLog404
 */

namespace ActivityLog404\Events;

defined( 'ABSPATH' ) || exit;

/**
 * Logging for the popular plugins issue #5 names -- forms (Gravity Forms,
 * WPForms, Contact Form 7), SEO (Yoast SEO, Rank Math), Advanced Custom
 * Fields, LMS (LearnDash, LifterLMS), membership (MemberPress, Paid
 * Memberships Pro) and page builders (Elementor) -- through each plugin's own
 * hooks. WooCommerce, the first, stays its own class (WooCommerceEvents).
 *
 * Every integration is **guarded**: its `register()` adds nothing unless its
 * plugin is loaded (a class or constant that plugin defines at include time,
 * before this plugin boots on `plugins_loaded`), and its event types are
 * listed in the log's filter only then. A site without any of them runs
 * exactly as before.
 *
 * The families share event types, so the log's filter reads "Form Submitted"
 * whichever form plugin took it; `details.plugin` says which. Every hook and
 * argument was checked against the plugin's own source or, for the closed
 * ones (Gravity Forms, LearnDash, MemberPress), its official developer docs;
 * docs/event-coverage.md has the table and the live-verification deferral.
 *
 * Free: this is event capture (AGENTS.md). Never stored, by construction:
 * form field values or a submitter's address, a custom field's value, a
 * member's payment details or amount.
 */
final class Integrations {

	/**
	 * Every integration class, in display order.
	 *
	 * @var array<int, class-string<Integrations\Integration>>
	 */
	public const CLASSES = array(
		Integrations\GravityForms::class,
		Integrations\WpForms::class,
		Integrations\ContactForm7::class,
		Integrations\Yoast::class,
		Integrations\RankMath::class,
		Integrations\Acf::class,
		Integrations\LearnDash::class,
		Integrations\LifterLms::class,
		Integrations\MemberPress::class,
		Integrations\PaidMembershipsPro::class,
		Integrations\Elementor::class,
	);

	/**
	 * Whether an integration is on: its plugin detected, unless the site
	 * says otherwise through `ops404_activity_log_integration_enabled`. A
	 * site can switch one off (a busy form whose submissions it does not
	 * want in the log); switching one on without its plugin does nothing,
	 * since its hooks never fire.
	 *
	 * @param string $plugin   The integration's plugin slug (e.g. `gravityforms`).
	 * @param bool   $detected Whether the plugin is loaded.
	 */
	public static function enabled( string $plugin, bool $detected ): bool {
		/**
		 * Whether Activity Log records a third-party plugin's events.
		 *
		 * @param bool   $detected Whether the plugin is loaded.
		 * @param string $plugin   The plugin's slug.
		 */
		return (bool) apply_filters( 'ops404_activity_log_integration_enabled', $detected, $plugin );
	}

	/**
	 * Register every integration whose plugin is active. Called from
	 * EventLogger::register_hooks().
	 */
	public static function register(): void {
		foreach ( self::CLASSES as $class ) {
			$class::register();
		}
	}

	/**
	 * Event types of the integrations whose plugin is active, for the log's
	 * filter. Rows already written keep their type either way.
	 *
	 * @return array<string, string>
	 */
	public static function event_types(): array {
		$types = array();
		foreach ( self::CLASSES as $class ) {
			if ( $class::is_active() ) {
				$types += $class::event_types();
			}
		}

		return $types;
	}

	/**
	 * Every integration's event types, active or not.
	 *
	 * @return array<string, string>
	 */
	public static function all_event_types(): array {
		$types = array();
		foreach ( self::CLASSES as $class ) {
			$types += $class::event_types();
		}

		return $types;
	}

	/**
	 * How a post type an active integration owns is logged, or null for any
	 * other post type: the event-type prefix, the noun its summary uses, and
	 * the plugin. A WPForms form is a `wpforms` post; logged as a post it read
	 * `Wpforms "Contact" updated` and filed under posts.
	 *
	 * @param string $post_type A post type.
	 * @return array{prefix: string, noun: string, plugin: string}|null
	 */
	public static function post_type( string $post_type ): ?array {
		foreach ( self::CLASSES as $class ) {
			if ( ! $class::is_active() ) {
				continue;
			}
			$owned = $class::post_types();
			if ( isset( $owned[ $post_type ] ) ) {
				return $owned[ $post_type ];
			}
		}

		return null;
	}

	/**
	 * Post types an active integration's plugin uses internally, which are
	 * never post events at all (an ACF field is a post; saving a field group
	 * with twenty fields wrote twenty rows).
	 *
	 * @param string $post_type A post type.
	 */
	public static function is_internal_post_type( string $post_type ): bool {
		foreach ( self::CLASSES as $class ) {
			if ( $class::is_active() && in_array( $post_type, $class::internal_post_types(), true ) ) {
				return true;
			}
		}

		return false;
	}
}