FilterInterface.php

Same filename in this branch
  1. 10 core/lib/Drupal/Core/Routing/FilterInterface.php
Same filename in other branches
  1. 9 core/modules/filter/src/Plugin/FilterInterface.php
  2. 9 core/lib/Drupal/Core/Routing/FilterInterface.php
  3. 8.9.x core/modules/filter/src/Plugin/FilterInterface.php
  4. 8.9.x core/lib/Drupal/Core/Routing/FilterInterface.php
  5. 11.x core/modules/filter/src/Plugin/FilterInterface.php
  6. 11.x core/lib/Drupal/Core/Routing/FilterInterface.php

Namespace

Drupal\filter\Plugin

File

core/modules/filter/src/Plugin/FilterInterface.php

View source
<?php

namespace Drupal\filter\Plugin;

use Drupal\Component\Plugin\PluginInspectionInterface;
use Drupal\Component\Plugin\ConfigurableInterface;
use Drupal\Component\Plugin\DependentPluginInterface;
use Drupal\Core\Form\FormStateInterface;

/**
 * Defines the interface for text processing filter plugins.
 *
 * User submitted content is passed through a group of filters before it is
 * output in HTML, in order to remove insecure or unwanted parts, correct or
 * enhance the formatting, transform special keywords, etc. A group of filters
 * is referred to as a "text format". Administrators can create as many text
 * formats as needed. Individual filters can be enabled and configured
 * differently for each text format.
 *
 * @see \Drupal\filter\Entity\FilterFormat
 *
 * Filtering is a two-step process. First, the content is 'prepared' by calling
 * the FilterInterface::prepare() method for every filter. The purpose is to
 * escape HTML-like structures. For example, imagine a filter which allows the
 * user to paste entire chunks of programming code without requiring manual
 * escaping of special HTML characters like < or &. If the programming code were
 * left untouched, then other filters could think it was HTML and change it. For
 * many filters, the prepare step is not necessary.
 *
 * The second step is the actual processing step. The result from passing the
 * text through all the filters' prepare steps gets passed to all the filters
 * again, this time to the FilterInterface::process() method. The process method
 * should then actually change the content: transform URLs into hyperlinks,
 * convert smileys into images, etc.
 *
 * @see \Drupal\filter\Plugin\FilterInterface::process()
 * @see check_markup()
 *
 * Typically, only text processing is applied, but in more advanced use cases,
 * filters may also:
 * - declare asset libraries to be loaded;
 * - declare cache tags that the resulting filtered text depends upon, so when
 *   either of those cache tags is invalidated, the render-cached HTML that the
 *   filtered text is part of should also be invalidated;
 * - create placeholders to apply uncacheable filtering, for example because it
 *   changes every few seconds.
 *
 * @see \Drupal\filter\Plugin\FilterInterface::process()
 *
 * Filters are discovered through annotations, which may contain the following
 * definition properties:
 * - title: (required) An administrative summary of what the filter does.
 * - type: (required) A classification of the filter's purpose. This is one of
 *   the following:
 *   - FilterInterface::TYPE_HTML_RESTRICTOR: HTML tag and attribute restricting
 *     filters.
 *   - FilterInterface::TYPE_MARKUP_LANGUAGE: Non-HTML markup language filters
 *     that generate HTML.
 *   - FilterInterface::TYPE_TRANSFORM_IRREVERSIBLE: Irreversible transformation
 *     filters.
 *   - FilterInterface::TYPE_TRANSFORM_REVERSIBLE: Reversible transformation
 *     filters.
 * - description: Additional administrative information about the filter's
 *   behavior, if needed for clarification.
 * - status: The default status for new instances of the filter. Defaults to
 *   FALSE.
 * - weight: A default weight for new instances of the filter. Defaults to 0.
 * - settings: An associative array containing default settings for new
 *   instances of the filter.
 *
 * Most implementations want to extend the generic basic implementation for
 * filter plugins.
 *
 * @see \Drupal\filter\Annotation\Filter
 * @see \Drupal\filter\FilterPluginManager
 * @see \Drupal\filter\Plugin\FilterBase
 * @see plugin_api
 */
interface FilterInterface extends ConfigurableInterface, DependentPluginInterface, PluginInspectionInterface {
    
    /**
     * Non-HTML markup language filters that generate HTML.
     */
    const TYPE_MARKUP_LANGUAGE = 0;
    
    /**
     * HTML tag and attribute restricting filters to prevent XSS attacks.
     */
    const TYPE_HTML_RESTRICTOR = 1;
    
    /**
     * Reversible transformation filters.
     */
    const TYPE_TRANSFORM_REVERSIBLE = 2;
    
    /**
     * Irreversible transformation filters.
     */
    const TYPE_TRANSFORM_IRREVERSIBLE = 3;
    
    /**
     * Returns the processing type of this filter plugin.
     *
     * @return int
     *   One of:
     *   - FilterInterface::TYPE_MARKUP_LANGUAGE
     *   - FilterInterface::TYPE_HTML_RESTRICTOR
     *   - FilterInterface::TYPE_TRANSFORM_REVERSIBLE
     *   - FilterInterface::TYPE_TRANSFORM_IRREVERSIBLE
     */
    public function getType();
    
    /**
     * Returns the administrative label for this filter plugin.
     *
     * @return string
     */
    public function getLabel();
    
    /**
     * Returns the administrative description for this filter plugin.
     *
     * @return string
     */
    public function getDescription();
    
    /**
     * Generates a filter's settings form.
     *
     * @param array $form
     *   A minimally prepopulated form array.
     * @param \Drupal\Core\Form\FormStateInterface $form_state
     *   The state of the (entire) configuration form.
     *
     * @return array
     *   The $form array with additional form elements for the settings of this
     *   filter. The submitted form values should match $this->settings.
     */
    public function settingsForm(array $form, FormStateInterface $form_state);
    
    /**
     * Prepares the text for processing.
     *
     * Filters should not use the prepare method for anything other than escaping,
     * because that would short-circuit the control the user has over the order in
     * which filters are applied.
     *
     * @param string $text
     *   The text string to be filtered.
     * @param string $langcode
     *   The language code of the text to be filtered.
     *
     * @return string
     *   The prepared, escaped text.
     */
    public function prepare($text, $langcode);
    
    /**
     * Performs the filter processing.
     *
     * @param string $text
     *   The text string to be filtered.
     * @param string $langcode
     *   The language code of the text to be filtered.
     *
     * @return \Drupal\filter\FilterProcessResult
     *   The filtered text, wrapped in a FilterProcessResult object, and possibly
     *   with associated assets, cacheability metadata and placeholders.
     *
     * @see \Drupal\filter\FilterProcessResult
     */
    public function process($text, $langcode);
    
    /**
     * Returns HTML allowed by this filter's configuration.
     *
     * May be implemented by filters of the FilterInterface::TYPE_HTML_RESTRICTOR
     * type, this won't be used for filters of other types; they should just
     * return FALSE.
     *
     * This callback function is only necessary for filters that strip away HTML
     * tags (and possibly attributes) and allows other modules to gain insight in
     * a generic manner into which HTML tags and attributes are allowed by a
     * format.
     *
     * @return array|false
     *   A nested array with the following structure:
     *     - 'allowed': the allowed tags as keys, and for each of those tags
     *       (keys) either of the following values:
     *       - TRUE to indicate any attribute is allowed
     *       - FALSE to indicate no attributes are allowed
     *       - an array to convey attribute restrictions: the keys must be
     *         attribute names (which may use a wildcard, e.g. "data-*"), the
     *         possible values are similar to the above:
     *           - TRUE to indicate any attribute value is allowed
     *           - FALSE to indicate the attribute is forbidden
     *           - an array to convey attribute value restrictions: the key must
     *             be attribute values (which may use a wildcard, e.g. "xsd:*"),
     *             the possible values are TRUE or FALSE: to mark the attribute
     *             value as allowed or forbidden, respectively
     *
     *   There is one special case: the "wildcard tag", "*": any attribute
     *   restrictions on that pseudotag apply to all tags.
     *
     *   If no restrictions apply, then FALSE must be returned.
     *
     *   Here is a concrete example, for a very granular filter:
     *     @code
     *     [
     *       'allowed' => [
     *         // Allows any attribute with any value on the <div> tag.
     *         'div' => TRUE,
     *         // Allows no attributes on the <p> tag.
     *         'p' => FALSE,
     *         // Allows the following attributes on the <a> tag:
     *         //  - 'href', with any value;
     *         //  - 'rel', with the value 'nofollow' value.
     *         'a' => [
     *           'href' => TRUE,
     *           'rel' => ['nofollow' => TRUE],
     *         ],
     *         // Only allows the 'src' and 'alt' attributes on the <alt> tag,
     *         // with any value.
     *         'img' => [
     *           'src' => TRUE,
     *           'alt' => TRUE,
     *         ],
     *         // Forbid the 'style' and 'on*' ('onClick' etc.) attributes on any
     *         // tag.
     *         '*' => [
     *           'style' => FALSE,
     *           'on*' => FALSE,
     *         ],
     *       ]
     *     ]
     *     @endcode
     *
     *   The simplest example possible: a filter that doesn't allow any HTML:
     *     @code
     *     [
     *       'allowed' => []
     *     ]
     *     @endcode
     *
     *   And for a filter that applies no restrictions, i.e. allows any HTML:
     *     @code
     *     FALSE
     *     @endcode
     *
     * @see \Drupal\filter\Entity\FilterFormatInterface::getHtmlRestrictions()
     */
    public function getHTMLRestrictions();
    
    /**
     * Generates a filter's tip.
     *
     * A filter's tips should be informative and to the point. Short tips are
     * preferably one-liners.
     *
     * @param bool $long
     *   Whether this callback should return a short tip to display in a form
     *   (FALSE), or whether a more elaborate filter tips should be returned for
     *   template_preprocess_filter_tips() (TRUE).
     *
     * @return string|null
     *   Translated text to display as a tip, or NULL if this filter has no tip.
     *
     * @todo Split into getSummaryItem() and buildGuidelines().
     */
    public function tips($long = FALSE);

}

Interfaces

Title Deprecated Summary
FilterInterface Defines the interface for text processing filter plugins.

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.