<?php
/**
 * Hookable Interface
 *
 * Defines the contract for classes that register WordPress hooks.
 * This interface provides a standardized way to organize and register
 * action and filter hooks throughout the plugin.
 *
 * @package     WPUltimateSecurity\UltimateSecurity\Contracts
 * @since       1.0.0
 * @author      Ultimate Security Team
 * @license     GPL-2.0-or-later
 */

declare(strict_types=1);

namespace WPUltimateSecurity\UltimateSecurity\Contracts;

/**
 * Interface HookableInterface
 *
 * Contract for classes that need to register WordPress action and filter hooks.
 * This interface promotes a clean, declarative approach to hook registration
 * by separating hook definitions from their registration logic.
 *
 * Benefits of this pattern:
 * - Clear visibility of all hooks a class registers
 * - Easy to test hook configurations
 * - Consistent hook registration across the plugin
 * - Simplifies debugging hook-related issues
 * - Enables conditional hook registration
 *
 * Example implementation:
 * ```php
 * class LoginSecurityHooks implements HookableInterface {
 *     public function getHooks(): array {
 *         return [
 *             [
 *                 'type' => 'action',
 *                 'hook' => 'wp_login',
 *                 'callback' => [$this, 'onUserLogin'],
 *                 'priority' => 10,
 *                 'accepted_args' => 2,
 *             ],
 *             [
 *                 'type' => 'filter',
 *                 'hook' => 'authenticate',
 *                 'callback' => [$this, 'validateLogin'],
 *                 'priority' => 30,
 *                 'accepted_args' => 3,
 *             ],
 *         ];
 *     }
 *
 *     public function register(): void {
 *         foreach ($this->getHooks() as $hook) {
 *             $function = $hook['type'] === 'filter' ? 'add_filter' : 'add_action';
 *             $function(
 *                 $hook['hook'],
 *                 $hook['callback'],
 *                 $hook['priority'] ?? 10,
 *                 $hook['accepted_args'] ?? 1
 *             );
 *         }
 *     }
 *
 *     public function onUserLogin(string $userLogin, \WP_User $user): void {
 *         // Handle login event
 *     }
 * }
 * ```
 *
 * @since 1.0.0
 */
interface HookableInterface
{
    /**
     * Get the list of hooks to register.
     *
     * Returns an array of hook definitions. Each definition is an associative
     * array containing the hook configuration:
     *
     * Required keys:
     * - 'type': string - Either 'action' or 'filter'
     * - 'hook': string - The WordPress hook name (e.g., 'init', 'wp_login')
     * - 'callback': callable - The callback function or method
     *
     * Optional keys:
     * - 'priority': int - Hook priority (default: 10, lower runs earlier)
     * - 'accepted_args': int - Number of arguments the callback accepts (default: 1)
     * - 'condition': callable - A callable that returns bool; hook only registers if true
     *
     * Example return value:
     * ```php
     * [
     *     [
     *         'type' => 'action',
     *         'hook' => 'init',
     *         'callback' => [$this, 'initialize'],
     *         'priority' => 5,
     *     ],
     *     [
     *         'type' => 'filter',
     *         'hook' => 'the_content',
     *         'callback' => [$this, 'filterContent'],
     *         'priority' => 10,
     *         'accepted_args' => 1,
     *     ],
     *     [
     *         'type' => 'action',
     *         'hook' => 'admin_init',
     *         'callback' => [$this, 'adminSetup'],
     *         'condition' => fn() => is_admin(),
     *     ],
     * ]
     * ```
     *
     * @since 1.0.0
     *
     * @return array<int, array{
     *     type: string,
     *     hook: string,
     *     callback: callable,
     *     priority?: int,
     *     accepted_args?: int,
     *     condition?: callable
     * }> Array of hook definition arrays.
     */
    public function getHooks(): array;

    /**
     * Register all hooks with WordPress.
     *
     * Iterates through the hooks returned by getHooks() and registers each
     * one with WordPress using add_action() or add_filter() as appropriate.
     *
     * Implementation notes:
     * - Should handle both actions and filters based on the 'type' key
     * - Should apply default values for priority (10) and accepted_args (1)
     * - Should respect any 'condition' callbacks before registering
     * - May log hook registrations for debugging purposes
     * - Should be idempotent (safe to call multiple times)
     *
     * Typical implementation:
     * ```php
     * public function register(): void {
     *     foreach ($this->getHooks() as $hook) {
     *         // Check condition if present
     *         if (isset($hook['condition']) && !call_user_func($hook['condition'])) {
     *             continue;
     *         }
     *
     *         $function = $hook['type'] === 'filter' ? 'add_filter' : 'add_action';
     *         $function(
     *             $hook['hook'],
     *             $hook['callback'],
     *             $hook['priority'] ?? 10,
     *             $hook['accepted_args'] ?? 1
     *         );
     *     }
     * }
     * ```
     *
     * @since 1.0.0
     *
     * @return void
     */
    public function register(): void;
}
