<?php


namespace Drupal\custom_forms\Entity;


use Drupal\Core\Entity\ContentEntityInterface;
use Drupal\Core\Entity\EntityChangedInterface;
use Drupal\state_machine\Plugin\Field\FieldType\StateItemInterface;

interface CustomFormSubmissionInterface extends ContentEntityInterface, EntityChangedInterface {

  /**
   * Gets an custom form submission data.
   *
   * @return mixed
   *   Returns the whole data as array.
   */
  public function getData();

  /**
   * Gets an custom form submission mapped data.
   *
   * @param bool $hide_sensitive
   *   Whether to hide the sensitive data in the result or not.
   * @param array $column_headers
   *   An array reference that will get populated with the label for each
   *   column.
   *
   * @return mixed
   *   Returns the whole mapped data as array.
   */
  public function getMappedData($hide_sensitive = TRUE, &$column_headers = []);

  /**
   * Sets the originating form id.
   *
   * @param int $form_id
   *   The id for the form that the submission originates from.
   *
   * @return \Drupal\custom_forms\Entity\CustomFormSubmissionInterface
   */
  public function setFormId($form_id) : CustomFormSubmissionInterface;

  /**
   * Sets the entire data array for a custom form submission.
   *
   * Be careful using this, as it will override all the data on the submission.
   *
   * @param array $data
   *   The data array.
   *
   * @return \Drupal\custom_forms\Entity\CustomFormSubmissionInterface
   */
  public function setDataArray(array $data) : CustomFormSubmissionInterface;

  /**
   * Sets the entire mapped data array for a custom form submission.
   *
   * Be careful using this, as it will override all the mapped data on the
   * submission.
   *
   * @param array $data
   *   The mapped data array.
   *
   * @return \Drupal\custom_forms\Entity\CustomFormSubmissionInterface
   */
  public function setMappedDataArray(array $data) : CustomFormSubmissionInterface;

  /**
   * Set the errors on the submission.
   *
   * You can add errors that are only logged by adding them under the "_log" key.
   * Usage example:
   * @code
   * $errors = [
   *   'machine_name' => [
   *     'required' => t('The field is required.'),
   *     'invalid' => t('The field does not match the required format'),
   *   ],
   *   '_log' => [
   *     'error' => t('This error is logged as type "error".'),
   *     'debug' => t('This error is logged as type "debug".'),
   *   ]
   * ];
   * @endcode
   *
   * @param array $errors
   *   The array of errors, keyed by field machine name.
   *
   * @return \Drupal\custom_forms\Entity\CustomFormSubmissionInterface
   */
  public function setErrors(array $errors) : CustomFormSubmissionInterface;

  /**
   * Gets the unique id of the submission.
   *
   * @return string
   *   The unique id of the submission.
   */
  public function getUniqueId() : ?string;

  /**
   * Gets the form of the submission.
   *
   * @return \Drupal\custom_forms\Entity\CustomForm|NULL
   *   The custom form that created the submission or
   *   NULL if the form was not found.
   */
  public function getForm() : ?CustomForm;

  /**
   * Gets the current state of the submission.
   *
   * @return \Drupal\state_machine\Plugin\Field\FieldType\StateItemInterface
   *   The state the submission is currently in.
   */
  public function getState() : StateItemInterface;

  /**
   * Get all errors on the submission.
   *
   * @return array
   *   Returns an array of all errors, or an empty array if no errors exist.
   */
  public function getErrors() : array;

  /**
   * Gets the timestamp the submission was created.
   *
   * @return int
   *   The timestamp when the submission was created.
   */
  public function getCreatedTime() : int;

  /**
   * Generates an array containing all receipt data.
   *
   * The data in the array is keyed by the machine name, with the value being
   * another array containing the label and value of the field.
   *
   * This way the label and value can be retrieved separately for any rendering
   * requirements.
   *
   * @return array
   *   Returns an array with the receipt data.
   *
   * @throws \Drupal\Component\Plugin\Exception\PluginException
   *   Throws an exception when a custom form item's plugin is missing or
   *   malformed.
   */
  public function generateReceiptData() : array;

  /**
   * Load a submission based on its unique id.
   *
   * @param string $id
   *   The unique ID to load by.
   *
   * @return \Drupal\Core\Entity\EntityInterface|null
   *   Returns the submission, or NULL if none were found.
   */
  public static function loadByUniqueId($id) : ?CustomFormSubmissionInterface;

}