<?php
/**
 * Module Interface
 *
 * Defines the contract that all WP PowerSuite modules must implement.
 * This interface ensures consistent module behavior and enables the
 * ModuleManager to properly load and manage modules.
 *
 * @package WP_PowerSuite\Core\Contracts
 * @since 1.0.0
 */

namespace WP_PowerSuite\Core\Contracts;

/**
 * Module Interface
 *
 * All modules must implement this interface to be recognized and loaded
 * by the ModuleManager. The interface defines the minimum required methods
 * for module identification, initialization, and context detection.
 *
 * New modules should extend {@see \WP_PowerSuite\Core\AbstractModule} and
 * put hook registration in {@see \WP_PowerSuite\Core\AbstractModule::registerHooks()}
 * so bootstrap is idempotent and OptionStore access is consistent.
 *
 * @since 1.0.0
 */
interface ModuleInterface {

	/**
	 * Get Module ID
	 *
	 * Returns a unique identifier for the module. This should be a
	 * lowercase, hyphenated string (e.g., 'my-module-name').
	 *
	 * @since 1.0.0
	 * @return string Module ID.
	 */
	public function getId(): string;

	/**
	 * Get Module Name
	 *
	 * Returns the human-readable name of the module for display purposes.
	 *
	 * @since 1.0.0
	 * @return string Module name.
	 */
	public function getName(): string;

	/**
	 * Get Module Version
	 *
	 * Returns the current version of the module (e.g., '1.0.0').
	 *
	 * @since 1.0.0
	 * @return string Module version.
	 */
	public function getVersion(): string;

	/**
	 * Get Module Description
	 *
	 * Returns a brief description of what the module does.
	 *
	 * @since 1.0.0
	 * @return string Module description.
	 */
	public function getDescription(): string;

	/**
	 * Get Module Context
	 *
	 * Returns the context(s) where this module should be loaded.
	 * Possible values: 'admin', 'frontend', 'login', 'both', 'ajax', 'rest', 'cron'.
	 * Can return a single string or array of strings.
	 *
	 * @since 1.0.0
	 * @return string|array<string> Module context(s).
	 */
	public function getContext(): string|array;

	/**
	 * Get Module Dependencies
	 *
	 * Returns an array of module IDs that this module depends on.
	 * These modules must be loaded before this module can be initialized.
	 *
	 * @since 1.0.0
	 * @return array<string> Array of module IDs.
	 */
	public function getDependencies(): array;

	/**
	 * Initialize Module
	 *
	 * Called when the module is loaded and ready to be initialized.
	 * This is where the module should register hooks, set up functionality,
	 * and perform any initialization tasks.
	 *
	 * @since 1.0.0
	 * @return void
	 */
	public function init(): void;

	/**
	 * Check if Module is Enabled
	 *
	 * Returns whether the module is currently enabled. This should check
	 * the module's enabled state from the database/options.
	 *
	 * @since 1.0.0
	 * @return bool True if enabled, false otherwise.
	 */
	public function isEnabled(): bool;
}







