<?php

namespace Drupal\custom_forms\Plugin\CustomForms\FieldMapping;

use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
use Drupal\Component\Plugin\PluginInspectionInterface;
use Drupal\custom_forms\CustomFormItem;

/**
 * Interface CustomFormsFieldMappingInterface
 *
 * @package Drupal\custom_forms\Plugin\CustomForms\FieldMapping
 */
interface CustomFormsFieldMappingInterface extends PluginInspectionInterface, ContainerFactoryPluginInterface {

  /**
   * Whether the mapping plugin allows multiple values to be mapped to it.
   *
   * @return bool
   *   Returns TRUE if multiple values are allowed to be mapped using this
   *   plugin, otherwise returns FALSE.
   */
  public function allowsMultiple() : bool;

  /**
   * Returns an array of all available mapping ids for the specified field.
   *
   * Usually this just returns a single value array, but it supports a mapping
   * plugin defining multiple values if a field is mapped to multiple keys.
   *
   * @param \Drupal\custom_forms\CustomFormItem $item
   *   The field to get the mapping ids for.
   * @param array $mapping_ids
   *   The array of mapping ids. This array might only be partial depending
   *   on how far along in the mapping process the function was called.
   *   Useful for checking if there has already been defined the same mapping
   *   id.
   * @param bool $hide_sensitive
   *   Whether to hide sensitive data, defaults to TRUE.
   *
   * @return array
   *   Returns the array of mapping ids for the specified form item.
   */
  public function getMappingIds(CustomFormItem $item, array $mapping_ids, $hide_sensitive = TRUE) : array;

  /**
   * Maps the value of the item.
   *
   * @param array $values
   *   The array containing the submitted values.
   * @param array $mapped_values
   *   The array of mapped values. This array might only be partial depending
   *   on how far along in the mapping process the function was called.
   *   Useful for checking if there has already been mapped a value to the same
   *   key.
   * @param \Drupal\custom_forms\CustomFormItem $item
   *   The field that is being mapped.
   * @param bool $hide_sensitive
   *   Whether to hide sensitive data, defaults to TRUE.
   *
   * @return array
   *   Returns an array containing the mapped value.
   */
  public function mapValue(array $values, array $mapped_values, CustomFormItem $item, $hide_sensitive = TRUE) : array;

  /**
   * Whether the mapping is sensitive.
   *
   * This is an indication that it should not be directly rendered.
   *
   * @return boolean
   *   TRUE if the field is sensitive, otherwise FALSE.
   */
  public function isSensitive() : bool;
}