1. interface
  2. Drupal
  3. \
  4. filter
  5. \
  6. Plugin
  7. \
  8. FilterInterface

FilterInterface

interface FilterInterface implements ConfigurableInterface, DependentPluginInterface, ConfigurablePluginInterface, PluginInspectionInterface (View source)

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.

Constants

TYPE_MARKUP_LANGUAGE

Non-HTML markup language filters that generate HTML.
TYPE_HTML_RESTRICTOR

HTML tag and attribute restricting filters to prevent XSS attacks.
TYPE_TRANSFORM_REVERSIBLE

Reversible transformation filters.
TYPE_TRANSFORM_IRREVERSIBLE

Irreversible transformation filters.

Methods

array
getConfiguration()

Gets this plugin's configuration.

from  ConfigurablePluginInterface
setConfiguration(array $configuration)

Sets the configuration for this plugin instance.

from  ConfigurablePluginInterface
array
defaultConfiguration()

Gets default configuration for this plugin.

from  ConfigurablePluginInterface
array
calculateDependencies()

Calculates dependencies for the configured plugin.

from  DependentPluginInterface
string
getPluginId()

Gets the plugin_id of the plugin instance.

from  PluginInspectionInterface
array
getPluginDefinition()

Gets the definition of the plugin implementation.

from  PluginInspectionInterface
int
getType()

Returns the processing type of this filter plugin.

string
getLabel()

Returns the administrative label for this filter plugin.

string
getDescription()

Returns the administrative description for this filter plugin.

array
settingsForm(array $form, FormStateInterface $form_state)

Generates a filter's settings form.

string
prepare(string $text, string $langcode)

Prepares the text for processing.

FilterProcessResult
process(string $text, string $langcode)

Performs the filter processing.

array|false
getHTMLRestrictions()

Returns HTML allowed by this filter's configuration.

string|null
tips(bool $long = FALSE)

Generates a filter's tip.

Details

in ConfigurablePluginInterface at line 27
array getConfiguration()

Gets this plugin's configuration.

Return Value

array

An array of this plugin's configuration.

in ConfigurablePluginInterface at line 35
setConfiguration(array $configuration)

Sets the configuration for this plugin instance.

Parameters

array $configuration

An associative array containing the plugin's configuration.

in ConfigurablePluginInterface at line 43
array defaultConfiguration()

Gets default configuration for this plugin.

Return Value

array

An associative array with the default configuration.

in DependentPluginInterface at line 35
array calculateDependencies()

Calculates dependencies for the configured plugin.

Dependencies are saved in the plugin's configuration entity and are used to determine configuration synchronization order. For example, if the plugin integrates with specific user roles, this method should return an array of dependencies listing the specified roles.

Return Value

array

An array of dependencies grouped by type (config, content, module, theme). For example: @code array( 'config' => array('user.role.anonymous', 'user.role.authenticated'), 'content' => array('node:article:f0a189e6-55fb-47fb-8005-5bef81c44d6d'), 'module' => array('node', 'user'), 'theme' => array('seven'), ); @endcode

See also

ConfigDependencyManager
EntityInterface::getConfigDependencyName

in PluginInspectionInterface at line 21
string getPluginId()

Gets the plugin_id of the plugin instance.

Return Value

string

The plugin_id of the plugin instance.

in PluginInspectionInterface at line 30
array getPluginDefinition()

Gets the definition of the plugin implementation.

Return Value

array

The plugin definition, as returned by the discovery object used by the plugin manager.

at line 112
int getType()

Returns the processing type of this filter plugin.

Return Value

int

One of:

  • FilterInterface::TYPE_MARKUP_LANGUAGE
  • FilterInterface::TYPE_HTML_RESTRICTOR
  • FilterInterface::TYPE_TRANSFORM_REVERSIBLE
  • FilterInterface::TYPE_TRANSFORM_IRREVERSIBLE

at line 119
string getLabel()

Returns the administrative label for this filter plugin.

Return Value

string

at line 126
string getDescription()

Returns the administrative description for this filter plugin.

Return Value

string

at line 140
array settingsForm(array $form, FormStateInterface $form_state)

Generates a filter's settings form.

Parameters

array $form

A minimally prepopulated form array.
FormStateInterface $form_state

The state of the (entire) configuration form.

Return Value

array

The $form array with additional form elements for the settings of this filter. The submitted form values should match $this->settings.

at line 157
string prepare(string $text, string $langcode)

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.

Parameters

string $text

The text string to be filtered.
string $langcode

The language code of the text to be filtered.

Return Value

string

The prepared, escaped text.

at line 173
FilterProcessResult process(string $text, string $langcode)

Performs the filter processing.

Parameters

string $text

The text string to be filtered.
string $langcode

The language code of the text to be filtered.

Return Value

FilterProcessResult

The filtered text, wrapped in a FilterProcessResult object, and possibly with associated assets, cacheability metadata and placeholders.

See also

FilterProcessResult

at line 268
array|false getHTMLRestrictions()

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 Value

array|false

A nested array with either of the following keys:

  • 'allowed': (optional) 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
  • 'forbidden_tags': (optional) the forbidden tags

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 array( 'allowed' => array( // Allows any attribute with any value on the

tag. 'div' => TRUE, // Allows no attributes on the

tag. 'p' => FALSE, // Allows the following attributes on the tag: // - 'href', with any value; // - 'rel', with the value 'nofollow' value. 'a' => array( 'href' => TRUE, 'rel' => array('nofollow' => TRUE), ), // Only allows the 'src' and 'alt' attributes on the tag, // with any value. 'img' => array( 'src' => TRUE, 'alt' => TRUE, ), // Allow RDFa on tags, using only the dc, foaf, xsd and sioc // vocabularies/namespaces. 'span' => array( 'property' => array('dc:' => TRUE, 'foaf:' => TRUE), 'datatype' => array('xsd:' => TRUE), 'rel' => array('sioc:' => TRUE), ), // Forbid the 'style' and 'on' ('onClick' etc.) attributes on any // tag. '' => array( 'style' => FALSE, 'on*' => FALSE, ), ) ) @endcode

A simpler example, for a very coarse filter: @code array( 'forbidden_tags' => array('iframe', 'script') ) @endcode

The simplest example possible: a filter that doesn't allow any HTML: @code array( 'allowed' => array() ) @endcode

And for a filter that applies no restrictions, i.e. allows any HTML: @code FALSE @endcode

See also

\Drupal\filter\Entity\FilterFormatInterface::getHtmlRestrictions()

at line 286
string|null tips(bool $long = FALSE)

Generates a filter's tip.

A filter's tips should be informative and to the point. Short tips are preferably one-liners.

Split into getSummaryItem() and buildGuidelines().

Parameters

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 Value

string|null

Translated text to display as a tip, or NULL if this filter has no tip.