<?php

namespace Drupal\custom_forms\Plugin\CustomForms\SubmissionHandler;

use Drupal\Core\Form\FormStateInterface;
use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
use Drupal\Component\Plugin\PluginInspectionInterface;
use Drupal\custom_forms\CustomFormInterface;
use Drupal\custom_forms\Entity\CustomFormSubmissionHandlerInterface;
use Drupal\custom_forms\Entity\CustomFormSubmissionInterface;

/**
 * Interface CustomFormsSubmissionHandlerInterface
 *
 * Interface for the custom submission handler plugins, defining and documenting
 * the different functions available from the plugin.
 *
 * @package Drupal\custom_forms\Plugin\CustomForms\SubmissionHandler
 */
interface CustomFormsSubmissionHandlerInterface extends PluginInspectionInterface, ContainerFactoryPluginInterface {

  /**
   * Build the settings form for the handler plugin.
   *
   * @param \Drupal\custom_forms\CustomFormInterface $custom_form
   *   The custom form that the handler belongs to.
   * @param array $form
   *   The form array used for building the settings form.
   * @param \Drupal\Core\Form\FormStateInterface $form_state
   *   The form state.
   *
   * @return array
   *   Returns the form array for the settings form.
   */
  public function buildSettingsForm(CustomFormInterface $custom_form, array $form, FormStateInterface $form_state) : array;

  /**
   * Handle saving the handler plugin settings form.
   *
   * @param \Drupal\custom_forms\CustomFormInterface $custom_form
   *   The custom form that the handler belongs to.
   * @param array $form
   *   The form array used for building the settings form.
   * @param \Drupal\Core\Form\FormStateInterface $form_state
   *   The form state.
   */
  public function submitSettingsForm(CustomFormInterface $custom_form, array &$form, FormStateInterface $form_state) : void;

  /**
   * Execute the handler plugin.
   *
   * @param \Drupal\custom_forms\Entity\CustomFormSubmissionInterface $submission
   *   The submission generated when the custom form was submitted.
   *   This can contain partial data depending on at what event the plugin is
   *   executed.
   * @param \Drupal\custom_forms\Entity\CustomFormSubmissionHandlerInterface $handler_entity
   *   The handler entity that is executing.
   */
  public function executeHandler(CustomFormSubmissionInterface $submission, CustomFormSubmissionHandlerInterface $handler_entity) : void;
}