<?php
/**
 * Abilities loader class file.
 */

declare( strict_types=1 );

namespace Automattic\WooCommerce\Internal\Abilities;

use Automattic\WooCommerce\Abilities\AbilityDefinition;
use Automattic\WooCommerce\Abilities\ExtensibleAbilities;
use Automattic\WooCommerce\Abilities\ActionableAbility;
use Automattic\WooCommerce\Internal\Abilities\Domain\OrderAddNote;
use Automattic\WooCommerce\Internal\Abilities\Domain\OrderNotesQuery;
use Automattic\WooCommerce\Internal\Abilities\Domain\OrderUpdateStatus;
use Automattic\WooCommerce\Internal\Abilities\Domain\OrdersQuery;
use Automattic\WooCommerce\Internal\Abilities\Domain\ProductCreate;
use Automattic\WooCommerce\Internal\Abilities\Domain\ProductDelete;
use Automattic\WooCommerce\Internal\Abilities\Domain\ProductUpdate;
use Automattic\WooCommerce\Internal\Abilities\Domain\ProductsQuery;

defined( 'ABSPATH' ) || exit;

/**
 * Hooks WooCommerce ability definitions into the WordPress Abilities API.
 */
class AbilitiesLoader {

	/**
	 * Whether the loader hooks have been registered.
	 *
	 * @var bool
	 */
	private static bool $initialized = false;

	/**
	 * Canonical WooCommerce domain ability definition classes.
	 *
	 * @var array<int, class-string>
	 */
	private const CORE_ABILITY_DEFINITION_CLASSES = array(
		OrdersQuery::class,
		OrderAddNote::class,
		OrderNotesQuery::class,
		OrderUpdateStatus::class,
		ProductsQuery::class,
		ProductCreate::class,
		ProductDelete::class,
		ProductUpdate::class,
	);

	/**
	 * Log source for ability registration notices.
	 *
	 * @var string
	 */
	private const LOG_SOURCE = 'woocommerce-abilities';

	/**
	 * Core ability instances registered by this loader in the current request.
	 *
	 * @var array<string, object>
	 */
	private static array $registered_core_abilities = array();

	/**
	 * Query var that holds the extension filter clauses of a list ability.
	 *
	 * @internal
	 */
	public const EXTENSION_QUERY_VAR = 'woocommerce_extensible_abilities_query_args';

	/**
	 * Initialize ability registration hooks.
	 *
	 * @internal
	 *
	 * @since 10.9.0
	 */
	final public static function init(): void {
		if ( self::$initialized ) {
			return;
		}

		/*
		 * Register abilities when Abilities API is ready.
		 * Support both old (pre-6.9) and new (6.9+) action names.
		 */
		AbilitiesCategories::init();
		add_action( 'woocommerce_extensible_abilities_resources_init', array( __CLASS__, 'register_core_resources' ), 0 );
		add_action( 'abilities_api_init', array( __CLASS__, 'init_extensions' ), 0 );
		add_action( 'wp_abilities_api_init', array( __CLASS__, 'init_extensions' ), 0 );
		add_action( 'abilities_api_init', array( __CLASS__, 'register_abilities' ) );
		add_action( 'wp_abilities_api_init', array( __CLASS__, 'register_abilities' ) );
		add_filter( 'woocommerce_product_data_store_cpt_get_products_query', array( __CLASS__, 'add_extension_query_args' ), 10, 2 );
		add_filter( 'woocommerce_order_data_store_cpt_get_orders_query', array( __CLASS__, 'add_extension_query_args' ), 10, 2 );

		self::$initialized = true;
	}

	/**
	 * Register the resources that Core's abilities format, so extensions can register fields on them.
	 *
	 * @internal
	 *
	 * @since 11.3.0
	 */
	public static function register_core_resources(): void {
		foreach ( array( 'product', 'order', 'order_item' ) as $resource_name ) {
			ExtensibleAbilities::register_resource( $resource_name );
		}
	}

	/**
	 * Add the extension filter clauses of a list ability to its WP_Query arguments.
	 *
	 * The posts storage ignores a meta_query argument, so a list ability puts the
	 * clauses in the EXTENSION_QUERY_VAR query var. Other queries do not have it,
	 * so a query that a hook runs inside the ability's query stays the same.
	 *
	 * @internal
	 *
	 * @since 11.3.0
	 *
	 * @param array $wp_query_args WP_Query arguments.
	 * @param array $query_vars    Query vars of wc_get_products() or wc_get_orders().
	 * @return array
	 */
	public static function add_extension_query_args( $wp_query_args, $query_vars ) {
		if ( empty( $query_vars[ self::EXTENSION_QUERY_VAR ] ) || ! is_array( $wp_query_args ) ) {
			return $wp_query_args;
		}

		unset( $wp_query_args[ self::EXTENSION_QUERY_VAR ] );
		return array_merge_recursive( $wp_query_args, $query_vars[ self::EXTENSION_QUERY_VAR ] );
	}

	/**
	 * Let extensions register their resources, then their ability fields, before the abilities build their schemas.
	 *
	 * @internal
	 *
	 * @since 11.3.0
	 */
	public static function init_extensions(): void {
		if ( did_action( 'woocommerce_extensible_abilities_init' ) || ! ExtensibleAbilities::is_enabled() ) {
			return;
		}

		/**
		 * Fires when extensions can register their resources with ExtensibleAbilities.
		 *
		 * Fires one time, before `woocommerce_extensible_abilities_init`, only when the
		 * experimental `extensible_abilities` feature is on.
		 *
		 * @since 11.3.0
		 */
		do_action( 'woocommerce_extensible_abilities_resources_init' );

		/**
		 * Fires when extensions can register their fields with ExtensibleAbilities.
		 *
		 * Fires one time, only when the experimental `extensible_abilities` feature is on.
		 *
		 * @since 11.3.0
		 */
		do_action( 'woocommerce_extensible_abilities_init' );
	}

	/**
	 * Register all configured ability definitions.
	 *
	 * @since 10.9.0
	 */
	public static function register_abilities(): void {
		if ( ! function_exists( 'wp_register_ability' ) ) {
			return;
		}

		foreach ( self::get_ability_definition_classes() as $class_name ) {
			if ( ! is_string( $class_name ) || ! class_exists( $class_name ) ) {
				continue;
			}

			// Core's product write abilities extend ActionableAbility, so WordPress builds them from their own class.
			$is_actionable = is_a( $class_name, ActionableAbility::class, true ) && self::is_core_ability_definition_class( $class_name );

			if ( ! $is_actionable && ! is_a( $class_name, AbilityDefinition::class, true ) ) {
				continue;
			}

			$ability_name = $is_actionable ? $class_name::ABILITY_NAME : $class_name::get_name();

			if ( '' === $ability_name ) {
				continue;
			}

			$is_core_ability = self::is_core_ability_definition_class( $class_name );

			if ( self::is_reserved_woocommerce_ability_name( $ability_name ) && ! $is_core_ability ) {
				continue;
			}

			if ( function_exists( 'wp_has_ability' ) && wp_has_ability( $ability_name ) ) {
				$existing_ability = function_exists( 'wp_get_ability' ) ? wp_get_ability( $ability_name ) : null;

				if (
					$is_core_ability
					&& isset( self::$registered_core_abilities[ $ability_name ] )
					&& $existing_ability === self::$registered_core_abilities[ $ability_name ]
				) {
					continue;
				}

				if ( ! $is_core_ability || ! function_exists( 'wp_unregister_ability' ) ) {
					continue;
				}

				// Drop stale instance tracking before replacing a shadowed registration.
				unset( self::$registered_core_abilities[ $ability_name ] );
				wp_unregister_ability( $ability_name );
				self::log_replaced_reserved_ability( $ability_name, $class_name );
			}

			$args = $class_name::get_registration_args();
			if ( $is_actionable ) {
				$args['ability_class'] = $class_name;
			}

			$registered_ability = wp_register_ability( $ability_name, $args );

			if ( $is_core_ability && null !== $registered_ability ) {
				self::$registered_core_abilities[ $ability_name ] = $registered_ability;
			}
		}
	}

	/**
	 * Log when WooCommerce replaces a pre-existing registration in its reserved namespace.
	 *
	 * @param string       $ability_name Ability name.
	 * @param class-string $class_name Ability definition class name.
	 */
	private static function log_replaced_reserved_ability( string $ability_name, string $class_name ): void {
		if ( ! function_exists( 'wc_get_logger' ) ) {
			return;
		}

		wc_get_logger()->warning(
			'WooCommerce unregistered a previously registered ability before registering its canonical definition.',
			array(
				'source'           => self::LOG_SOURCE,
				'ability_name'     => $ability_name,
				'definition_class' => $class_name,
				'reserved_prefix'  => 'woocommerce/',
			)
		);
	}

	/**
	 * Check whether an ability definition class is provided by WooCommerce core.
	 *
	 * @param class-string $class_name Ability definition class name.
	 * @return bool
	 */
	private static function is_core_ability_definition_class( string $class_name ): bool {
		return in_array( $class_name, self::CORE_ABILITY_DEFINITION_CLASSES, true );
	}

	/**
	 * Check whether an ability name uses WooCommerce's reserved namespace.
	 *
	 * @param string $ability_name Ability name.
	 * @return bool
	 */
	private static function is_reserved_woocommerce_ability_name( string $ability_name ): bool {
		return 0 === strpos( $ability_name, 'woocommerce/' );
	}

	/**
	 * Get all ability definition classes that should be loaded.
	 *
	 * @return array<int, class-string>
	 */
	private static function get_ability_definition_classes(): array {
		/**
		 * Filter WooCommerce ability definition classes.
		 *
		 * Extensions can append autoloadable classes that implement
		 * {@see AbilityDefinition}. The loader will call get_name() and
		 * get_registration_args() on each definition class and register the ability on the
		 * Abilities API init hook. Returning a subset will not unregister core abilities;
		 * core classes are always retained.
		 *
		 * @since 10.9.0
		 *
		 * @param array<int, class-string> $classes Ability definition class names.
		 */
		$classes = apply_filters( 'woocommerce_ability_definition_classes', self::CORE_ABILITY_DEFINITION_CLASSES );

		if ( ! is_array( $classes ) ) {
			$classes = array();
		}

		return array_values(
			array_unique(
				array_filter(
					array_merge( self::CORE_ABILITY_DEFINITION_CLASSES, $classes ),
					'is_string'
				)
			)
		);
	}
}