<?php
/**
 * Base class for transmutation handlers.
 *
 * @package Ealab\Deployer
 */

namespace EaLab\WP_Deployer\vendor\Ealab\Deployer\Tracking\ItemValueHandler\ValueProcessor\TransmutationHandler;

use EaLab\WP_Deployer\vendor\Dakwamine\Component\ComponentBasedObject;
use EaLab\WP_Deployer\vendor\Ealab\Deployer\Exception\IgnoredTransmutationException;
use EaLab\WP_Deployer\vendor\Ealab\Deployer\Exception\InvalidDeploymentDataForImportException;
use EaLab\WP_Deployer\vendor\Ealab\Deployer\Exception\WpDeployException;
use EaLab\WP_Deployer\vendor\Ealab\Deployer\Tracking\ItemValueHandler\PlaceholderableTrait;

/**
 * Base class for transmutation handlers.
 */
abstract class TransmutationHandlerBase extends ComponentBasedObject {

	use PlaceholderableTrait;

	/**
	 * Form build for this transmutation handler, if any.
	 *
	 * @return array|null The form build, null if not needed.
	 */
	public static function getFormBuild(): ?array {
		return null;
	}

	/**
	 * Returns the ID of the transmutation handler.
	 *
	 * @return string The ID of the transmutation handler.
	 */
	abstract static public function getId(): string;

	/**
	 * Returns the public name of the transmutation handler.
	 *
	 * @return string The public name of the transmutation handler.
	 */
	abstract static public function getPublicName(): string;

	/**
	 * Transmutes the given value to a format suitable for export.
	 *
	 * @param mixed      $value The value to transmute.
	 * @param array|null $options The options to use for the transmutation. It contains at least the following keys:
	 *     - "_value_processor" (string): The ID of the value processor that is calling the transmutation.
	 *     - "_item_value_handler" (ItemValueHandlerBase): The item value handler that is calling the transmutation.
	 *
	 * @return mixed The transmuted value.
	 *
	 * @throws IgnoredTransmutationException If this handler does not handle the transmutation.
	 * @throws WpDeployException Serious error during transmutation that should interrupt the process.
	 */
	public function toExport( $value, ?array $options = array() ) {
		throw new IgnoredTransmutationException();
	}

	/**
	 * Transmutes the given value to a format suitable for import finalization.
	 *
	 * @param mixed      $value The value to transmute.
	 * @param array|null $options The options to use for the transmutation. It contains at least the following keys:
	 *     - "_value_processor" (string): The ID of the value processor that is calling the transmutation.
	 *     - "_item_value_handler" (ItemValueHandlerBase): The item value handler that is calling the transmutation.
	 *
	 * @return mixed The transmuted value.
	 *
	 * @throws IgnoredTransmutationException If this handler does not handle the transmutation.
	 * @throws InvalidDeploymentDataForImportException If the value is invalid.
	 */
	public function toImportFinalize( $value, ?array $options = array() ) {
		throw new IgnoredTransmutationException();
	}

	/**
	 * Transmutes the given value to a format suitable for import presave.
	 *
	 * @param mixed      $value The value to transmute.
	 * @param array|null $options The options to use for the transmutation. It contains at least the following keys:
	 *     - "_value_processor" (string): The ID of the value processor that is calling the transmutation.
	 *     - "_item_value_handler" (ItemValueHandlerBase): The item value handler that is calling the transmutation.
	 *
	 * @return mixed The transmuted value.
	 *
	 * @throws IgnoredTransmutationException If this handler does not handle the transmutation.
	 * @throws InvalidDeploymentDataForImportException If the value is invalid.
	 */
	public function toImportPresave( $value, ?array $options = array() ) {
		throw new IgnoredTransmutationException();
	}
}
