Chris@0: <?php
Chris@0: 
Chris@0: namespace Drupal\search\Plugin;
Chris@0: 
Chris@0: use Drupal\Component\Plugin\PluginInspectionInterface;
Chris@0: use Drupal\Core\Form\FormStateInterface;
Chris@0: 
Chris@0: /**
Chris@0:  * Defines a common interface for all SearchPlugin objects.
Chris@0:  */
Chris@0: interface SearchInterface extends PluginInspectionInterface {
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets the keywords, parameters, and attributes to be used by execute().
Chris@0:    *
Chris@0:    * @param string $keywords
Chris@0:    *   The keywords to use in a search.
Chris@0:    * @param array $parameters
Chris@0:    *   Array of parameters as an associative array. This is expected to
Chris@0:    *   be the query string from the current request.
Chris@0:    * @param array $attributes
Chris@0:    *   Array of attributes, usually from the current request object.
Chris@0:    *
Chris@0:    * @return \Drupal\search\Plugin\SearchInterface
Chris@0:    *   A search plugin object for chaining.
Chris@0:    */
Chris@0:   public function setSearch($keywords, array $parameters, array $attributes);
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the currently set keywords of the plugin instance.
Chris@0:    *
Chris@0:    * @return string
Chris@0:    *   The keywords.
Chris@0:    */
Chris@0:   public function getKeywords();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the current parameters set using setSearch().
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   The parameters.
Chris@0:    */
Chris@0:   public function getParameters();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the currently set attributes (from the request).
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   The attributes.
Chris@0:    */
Chris@0:   public function getAttributes();
Chris@0: 
Chris@0:   /**
Chris@0:    * Verifies if the values set via setSearch() are valid and sufficient.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if the search settings are valid and sufficient to execute a search,
Chris@0:    *   and FALSE if not.
Chris@0:    */
Chris@0:   public function isSearchExecutable();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the search index type this plugin uses.
Chris@0:    *
Chris@0:    * @return string|null
Chris@0:    *   The type used by this search plugin in the search index, or NULL if this
Chris@0:    *   plugin does not use the search index.
Chris@0:    *
Chris@0:    * @see search_index()
Chris@0:    * @see search_index_clear()
Chris@0:    */
Chris@0:   public function getType();
Chris@0: 
Chris@0:   /**
Chris@0:    * Executes the search.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   A structured list of search results.
Chris@0:    */
Chris@0:   public function execute();
Chris@0: 
Chris@0:   /**
Chris@0:    * Executes the search and builds render arrays for the result items.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array of render arrays of search result items (generally each item
Chris@0:    *   has '#theme' set to 'search_result'), or an empty array if there are no
Chris@0:    *   results.
Chris@0:    */
Chris@0:   public function buildResults();
Chris@0: 
Chris@0:   /**
Chris@0:    * Provides a suggested title for a page of search results.
Chris@0:    *
Chris@0:    * @return string
Chris@0:    *   The translated suggested page title.
Chris@0:    */
Chris@0:   public function suggestedTitle();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the searching help.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   Render array for the searching help.
Chris@0:    */
Chris@0:   public function getHelp();
Chris@0: 
Chris@0:   /**
Chris@0:    * Alters the search form when being built for a given plugin.
Chris@0:    *
Chris@0:    * The core search module only invokes this method on active module plugins
Chris@0:    * when building a form for them in
Chris@0:    * \Drupal\search\Form\SearchPageForm::buildForm(). A plugin implementing this
Chris@0:    * will also need to implement the buildSearchUrlQuery() method.
Chris@0:    *
Chris@0:    * @param array $form
Chris@0:    *   Nested array of form elements that comprise the form.
Chris@0:    * @param \Drupal\Core\Form\FormStateInterface $form_state
Chris@0:    *   The current state of the form. The arguments that
Chris@0:    *   \Drupal::formBuilder()->getForm() was originally called with are
Chris@0:    *   available in the array $form_state->getBuildInfo()['args'].
Chris@0:    *
Chris@0:    * @see SearchInterface::buildSearchUrlQuery()
Chris@0:    */
Chris@0:   public function searchFormAlter(array &$form, FormStateInterface $form_state);
Chris@0: 
Chris@0:   /**
Chris@0:    * Builds the URL GET query parameters array for search.
Chris@0:    *
Chris@0:    * When the search form is submitted, a redirect is generated with the
Chris@0:    * search input as GET query parameters. Plugins using the searchFormAlter()
Chris@0:    * method to add form elements to the search form will need to override this
Chris@0:    * method to gather the form input and add it to the GET query parameters.
Chris@0:    *
Chris@0:    * @param \Drupal\Core\Form\FormStateInterface $form_state
Chris@0:    *   The form state, with submitted form information.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array of GET query parameters containing all relevant form values
Chris@0:    *   to process the search. The 'keys' element must be present in order to
Chris@0:    *   trigger generation of search results, even if it is empty or unused by
Chris@0:    *   the search plugin.
Chris@0:    *
Chris@0:    * @see SearchInterface::searchFormAlter()
Chris@0:    */
Chris@0:   public function buildSearchUrlQuery(FormStateInterface $form_state);
Chris@0: 
Chris@0: }