<?php
/**
 * The module contract.
 *
 * Every feature of PageCore is a module. A module owns its admin screen, its
 * assets, its REST routes, its settings and its uninstall behaviour, and the
 * core bootstrap knows nothing about any of them by name.
 *
 * @package PageCore
 */

namespace PageCore;

defined( 'ABSPATH' ) || exit;

/**
 * Base class every PageCore module extends.
 */
abstract class Module {

	/**
	 * Stable identifier, lower case with hyphens.
	 *
	 * Must match the module's directory name, under modules/ or under a group
	 * folder such as modules/editor-options/, because discovery derives the
	 * class name from the directory.
	 *
	 * @return string
	 */
	abstract public function get_id();

	/**
	 * Translated name shown in the admin menu and on the Modules screen.
	 *
	 * @return string
	 */
	abstract public function get_label();

	/**
	 * One or two translated sentences describing what the module does.
	 *
	 * @return string
	 */
	abstract public function get_description();

	/**
	 * Attach the module's hooks.
	 *
	 * Called once per request, only when the module is enabled and available.
	 * Register REST routes, admin hooks and blocks from here.
	 *
	 * @return void
	 */
	abstract public function boot();

	/**
	 * Sort order within the PageCore submenu. Lower comes first.
	 *
	 * @return int
	 */
	public function get_menu_position() {
		return 50;
	}

	/**
	 * Shorter label for the submenu, when the full label is unwieldy.
	 *
	 * @return string
	 */
	public function get_menu_title() {
		return $this->get_label();
	}

	/**
	 * Whether the module contributes a submenu screen.
	 *
	 * A module that only exposes REST routes returns false.
	 *
	 * @return bool
	 */
	public function has_screen() {
		return true;
	}

	/**
	 * Render the module's admin screen.
	 *
	 * @return void
	 */
	public function render_screen() {}

	/**
	 * Whether this module has a card on the Settings screen at the moment.
	 *
	 * @return bool
	 */
	public function is_listed() {
		return true;
	}

	/**
	 * Whether this module can run in the current environment.
	 *
	 * An unavailable module is listed on the Modules screen with its reason, and
	 * cannot be switched on.
	 *
	 * @return bool
	 */
	public function is_available() {
		return true;
	}

	/**
	 * Translated explanation shown when is_available() is false.
	 *
	 * @return string
	 */
	public function get_unavailable_reason() {
		return '';
	}

	/**
	 * Whether the module is on for a site that has never chosen.
	 *
	 * @return bool
	 */
	public function is_enabled_by_default() {
		return true;
	}

	/**
	 * Read one of the module's settings.
	 *
	 * @param string $key     Setting key, or null for the whole array.
	 * @param mixed  $default Value returned when the key is absent.
	 * @return mixed
	 */
	public function get_setting( $key = null, $default = null ) {
		return pagecore()->settings()->get_module( $this->get_id(), $key, $default );
	}

	/**
	 * Write one of the module's settings.
	 *
	 * @param string $key   Setting key.
	 * @param mixed  $value Value to store.
	 * @return bool
	 */
	public function set_setting( $key, $value ) {
		return pagecore()->settings()->set_module( $this->get_id(), $key, $value );
	}

	/**
	 * Switches the module offers on its card on the Modules screen.
	 *
	 * Each is a site-wide on/off setting, stored with the module's other
	 * settings under its key.
	 *
	 * @return array[] Each: key, label, help (optional), default.
	 */
	public function get_options() {
		return array();
	}

	/**
	 * The module's options, with their current values.
	 *
	 * @return array[] Each: key, label, help, value.
	 */
	public function get_option_values() {
		$options = array();

		foreach ( $this->get_options() as $option ) {
			$options[] = array(
				'key'   => $option['key'],
				'label' => $option['label'],
				'help'  => $option['help'] ?? '',
				'value' => (bool) $this->get_setting( $option['key'], ! empty( $option['default'] ) ),
			);
		}

		return $options;
	}

	/**
	 * Whether a key names one of get_options().
	 *
	 * @param string $key Setting key.
	 * @return bool
	 */
	public function has_option( $key ) {
		return in_array( $key, wp_list_pluck( $this->get_options(), 'key' ), true );
	}

	/**
	 * Where discovery found the module, relative to the plugin, with a
	 * trailing slash. Empty for a module that was not discovered in modules/.
	 *
	 * @var string
	 */
	private $location = '';

	/**
	 * Record where discovery found the module.
	 *
	 * Most modules sit at modules/<id>/, but a group folder such as
	 * modules/editor-options/ holds several, so the directory cannot always be
	 * worked out from the id alone.
	 *
	 * @param string $dir Absolute path to the module's directory.
	 * @return void
	 */
	public function set_location( $dir ) {
		$dir = trailingslashit( wp_normalize_path( (string) $dir ) );
		$own = trailingslashit( wp_normalize_path( PAGECORE_DIR ) );

		if ( 0 === strpos( $dir, $own ) ) {
			$this->location = substr( $dir, strlen( $own ) );
		}
	}

	/**
	 * The module's directory relative to the plugin, with a trailing slash.
	 *
	 * @return string
	 */
	private function get_location() {
		return $this->location ? $this->location : 'modules/' . $this->get_id() . '/';
	}

	/**
	 * Absolute path to the module's own directory.
	 *
	 * @return string
	 */
	public function get_dir() {
		return PAGECORE_DIR . $this->get_location();
	}

	/**
	 * URL of the module's own directory.
	 *
	 * A module ships its own images and other static files beside its code, so
	 * nothing it owns has to be held in a shared plugin wide assets directory.
	 *
	 * @param string $path Optional path beneath the module directory.
	 * @return string
	 */
	public function get_url( $path = '' ) {
		return PAGECORE_URL . $this->get_location() . ltrim( (string) $path, '/' );
	}

	/**
	 * Admin screen slug used in the page= query argument.
	 *
	 * @return string
	 */
	public function get_screen_slug() {
		return Admin_Menu::SLUG . '-' . $this->get_id();
	}

	/**
	 * URL of the module's admin screen.
	 *
	 * @return string
	 */
	public function get_screen_url() {
		return admin_url( 'admin.php?page=' . $this->get_screen_slug() );
	}

	/**
	 * Remove everything this module created.
	 *
	 * Only ever called from uninstall.php, and only when the site owner has
	 * turned on "remove all data". Switching a module off must never reach here.
	 *
	 * @return void
	 */
	public function uninstall() {}

	/**
	 * Shape sent to the Modules screen.
	 *
	 * @return array
	 */
	public function to_array() {
		return array(
			'id'                => $this->get_id(),
			'label'             => $this->get_label(),
			'description'       => $this->get_description(),
			'enabled'           => pagecore()->modules()->is_enabled( $this->get_id() ),
			'available'         => $this->is_available(),
			'unavailableReason' => $this->get_unavailable_reason(),
			'hasScreen'         => $this->has_screen(),
			'screenUrl'         => $this->has_screen() ? $this->get_screen_url() : '',
			'position'          => $this->get_menu_position(),
			'options'           => $this->get_option_values(),
		);
	}
}