<?php

namespace WPForms\Admin;

/**
 * Adds a "WPForms" category tab to the WordPress Plugins screen.
 *
 * Uses the `plugins_list` filter to register an extra group containing
 * every WPForms-owned plugin (the main plugin and all `wpforms-*` addons),
 * and the `plugins_list_status_text` filter (introduced in WordPress 7.0)
 * to provide a friendly label for the new tab.
 *
 * On WordPress versions older than 7.0, the feature is disabled so
 * customers keep relying on the existing search / filter mechanism.
 *
 * @since 1.10.0.5
 */
class PluginsCategory {

	/**
	 * Status slug used as a key in `$plugins` and as `?plugin_status=` value.
	 *
	 * @since 1.10.0.5
	 */
	private const STATUS_KEY = 'wpforms';

	/**
	 * Slug prefix shared by the main plugin and all WPForms addons.
	 *
	 * @since 1.10.0.5
	 */
	private const SLUG_PREFIX = 'wpforms';

	/**
	 * Init.
	 *
	 * @since 1.10.0.5
	 */
	public function init(): void {

		if ( ! $this->is_supported() ) {
			return;
		}

		$this->hooks();
	}

	/**
	 * Whether the current request supports the new plugins category tab.
	 *
	 * Registers on the `plugins.php` screen and on the AJAX
	 * `search-plugins` handler invoked by the live-search input,
	 * so the filter stays scoped to WPForms when the user clears
	 * the search box (the 'X' icon) and the table is re-rendered
	 * via admin-ajax.
	 *
	 * @since 1.10.0.5
	 *
	 * @return bool
	 */
	private function is_supported(): bool {

		global $pagenow;

		$is_plugins_screen = ! empty( $pagenow ) && $pagenow === 'plugins.php';

		// The 'X' clear icon on the live-search input fires the
		// `search-plugins` AJAX action, which re-runs `plugins_list`
		// from admin-ajax.php. The nonce is verified inside the core
		// handler before our filter runs.
		// phpcs:disable WordPress.Security.NonceVerification.Missing
		$is_plugins_search_ajax = wp_doing_ajax()
			&& isset( $_POST['action'], $_POST['pagenow'] )
			&& sanitize_key( $_POST['action'] ) === 'search-plugins'
			&& sanitize_key( $_POST['pagenow'] ) === 'plugins';
		// phpcs:enable WordPress.Security.NonceVerification.Missing

		if ( ! $is_plugins_screen && ! $is_plugins_search_ajax ) {
			return false;
		}

		return is_wp_version_compatible( '7.0' );
	}

	/**
	 * Register hooks.
	 *
	 * @since 1.10.0.5
	 */
	private function hooks(): void {

		add_filter( 'plugins_list', [ $this, 'add_category' ] );
		add_filter( 'plugins_list_status_text', [ $this, 'category_label' ], 10, 3 );
	}

	/**
	 * Append a WPForms group to the plugins list used by the list table.
	 *
	 * @since 1.10.0.5
	 *
	 * @param array|mixed $plugins Plugins grouped by status (`all`, `active`, ...).
	 *
	 * @return array
	 */
	public function add_category( $plugins ): array {

		$plugins = (array) $plugins;

		if ( empty( $plugins['all'] ) || ! is_array( $plugins['all'] ) ) {
			return $plugins;
		}

		$wpforms_plugins = [];

		foreach ( $plugins['all'] as $file => $plugin_data ) {
			if ( ! is_array( $plugin_data ) ) {
				continue;
			}

			if ( $this->is_wpforms_plugin( (string) $file, $plugin_data ) ) {
				$wpforms_plugins[ $file ] = $plugin_data;
			}
		}

		if ( ! empty( $wpforms_plugins ) ) {
			$plugins[ self::STATUS_KEY ] = $wpforms_plugins;
		}

		return $plugins;
	}

	/**
	 * Provide the human-readable label for the WPForms category tab.
	 *
	 * The list table escapes the returned string and appends the count
	 * span, so the value must be plain text without HTML.
	 *
	 * @since 1.10.0.5
	 *
	 * @param string|mixed $text  Status text. Default empty string.
	 * @param int|mixed    $count Number of plugins in the category.
	 * @param string|mixed $type  The status slug being filtered.
	 *
	 * @return string
	 * @noinspection PhpUnusedParameterInspection
	 */
	public function category_label( $text, $count, $type ): string { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed

		if ( $type !== self::STATUS_KEY ) {
			return is_string( $text ) ? $text : '';
		}

		// "WPForms" is a brand name, but keep the call translatable so locales
		// can adjust casing if needed. The %s count is appended by core.
		return __( 'WPForms', 'wpforms-lite' );
	}

	/**
	 * Determine whether a plugin should be listed under the WPForms category.
	 *
	 * The default rule matches by folder slug: the main plugin (`wpforms`)
	 * and any `wpforms-*` addon. Third parties can override via the
	 * exposed filter without touching this class.
	 *
	 * @since 1.10.0.5
	 *
	 * @param string $file        Plugin file path (e.g. `wpforms-stripe/wpforms-stripe.php`).
	 * @param array  $plugin_data Plugin metadata as returned by `get_plugins()`.
	 *
	 * @return bool
	 */
	private function is_wpforms_plugin( string $file, array $plugin_data ): bool {

		$slug    = explode( '/', $file )[0];
		$is_ours = $slug === self::SLUG_PREFIX || strpos( $slug, self::SLUG_PREFIX . '-' ) === 0;

		/**
		 * Filters whether a plugin should be listed under the WPForms category tab.
		 *
		 * @since 1.10.0.5
		 *
		 * @param bool   $is_ours     Whether the plugin is recognised as a WPForms plugin.
		 * @param string $file        Plugin file path (e.g. `wpforms-stripe/wpforms-stripe.php`).
		 * @param array  $plugin_data Plugin metadata as returned by `get_plugins()`.
		 *
		 * @return bool Whether the plugin should appear under the WPForms tab.
		 */
		return (bool) apply_filters( 'wpforms_admin_plugins_category_is_wpforms_plugin', $is_ours, $file, $plugin_data ); // phpcs:ignore WPForms.PHP.ValidateHooks.InvalidHookName
	}
}