FormSubmitterInterface.php 2.71 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
<?php

/**
 * @file
 * Contains \Drupal\Core\Form\FormSubmitterInterface.
 */

namespace Drupal\Core\Form;

/**
 * Provides an interface for processing form submissions.
 */
interface FormSubmitterInterface {

  /**
   * Handles the submitted form, executing callbacks and processing responses.
   *
   * @param array $form
   *   An associative array containing the structure of the form.
20 21
   * @param \Drupal\Core\Form\FormStateInterface $form_state
   *   The current state of the form.
22 23 24 25 26
   *
   * @return null|\Symfony\Component\HttpFoundation\Response
   *   If a response was set by a submit handler, or if the form needs to
   *   redirect, a Response object will be returned.
   */
27
  public function doSubmitForm(&$form, FormStateInterface &$form_state);
28 29 30 31 32 33 34 35 36 37

  /**
   * Executes custom submission handlers for a given form.
   *
   * Button-specific handlers are checked first. If none exist, the function
   * falls back to form-level handlers.
   *
   * @param $form
   *   An associative array containing the structure of the form.
   * @param $form_state
38 39 40
   *   The current state of the form. If the user submitted the form by clicking
   *   a button with custom handler functions defined, those handlers will be
   *   stored here.
41
   */
42
  public function executeSubmitHandlers(&$form, FormStateInterface &$form_state);
43 44 45 46 47 48

  /**
   * Redirects the user to a URL after a form has been processed.
   *
   * After a form is submitted and processed, normally the user should be
   * redirected to a new destination page. This function figures out what that
49
   * destination should be, based on the $form_state and the 'destination'
50 51
   * query string in the request URL, and redirects the user there.
   *
52 53 54
   * The result of \Drupal\Core\Form|FormStateInterface::getRedirect()
   * determines where to redirect the user. See the possible return values
   * listed there. If the result is FALSE, then the user will not be redirected.
55
   *
56
   * Here is an example of how to set up a form to redirect to the path 'user':
57
   * @code
58
   * $form_state->setRedirect('user.page');
59 60 61
   * @endcode
   * And here is an example of how to redirect to 'node/123?foo=bar#baz':
   * @code
62 63
   * $form_state->setRedirect('node.view',
   *   array('node' => 123),
64 65 66 67 68 69
   *   array(
   *     'query' => array(
   *       'foo' => 'bar',
   *     ),
   *     'fragment' => 'baz',
   *   ),
70
   * ));
71 72
   * @endcode
   *
73
   * @param \Drupal\Core\Form\FormStateInterface $form_state
74
   *   The current state of the form.
75 76 77 78 79 80
   *
   * @return \Symfony\Component\HttpFoundation\RedirectResponse|null
   *
   * @see \Drupal\Core\Form\FormBuilderInterface::processForm()
   * @see \Drupal\Core\Form\FormBuilderInterface::buildForm()
   */
81
  public function redirectForm(FormStateInterface $form_state);
82 83

}