Filter API overview

The Filter API in Drupal processes and transforms user-entered text to ensure it is safe, properly formatted, and displayed as intended. It is essential for managing text formats used in text editors and other input fields across the site. By applying filters, Drupal can sanitize HTML, transform markup, and handle custom text processing. In Drupal 8 and later, filters are created as plugins, replacing the older hook-based system for greater flexibility.

Key updates to the Filter API include:

• Filters are now defined using plugins instead of hooks.
• Filter types must be specified to support in-place editing.

For more technical details, visit the filter.module documentation and the FilterInterface reference.

API features

Text format config entities

\Drupal\filter\Entity\FilterFormat config entity: configure text formats, one text format can have one text editor.

Every text format consists of an ordered list of filters (filter plugins), with settings for those filters that do have settings. When filtering text, these filters are invoked in order.

Filter plugins

\Drupal\filter\Plugin\FilterInterface: filter plugins, to provide additional filters that are available to site builders to be used.

• Plugin implementations must be annotated with the @Filter annotation so they can be discovered.
• Discovered plugins' annotation metadata can be altered using hook_filter_info_alter()
• \Drupal\filter\Plugin\FilterBase provides a default implementation so filter plugins don't need to implement every method
• Every filter plugin must specify a filter type in its annotation. Filter types were added specifically to support in-place editing. There are four filter types:
  1. FilterInterface::TYPE_MARKUP_LANGUAGE — Non-HTML markup language filters that generate HTML. The filter converts something that's not HTML to HTML in a way that is not compatible with WYSIWYG editing.
  2. FilterInterface::TYPE_HTML_RESTRICTOR — HTML tag and attribute restricting filters to prevent XSS attacks. The filter restricts the HTML allowed, for example, to protect against XSS.
  3. FilterInterface::TYPE_TRANSFORM_REVERSIBLE — Reversible transformation filters. The filter performs a transform for which a WYSIWYG plugin exists to perform the same transformation (and its reverse) client-side. For example, <img data-caption="Druplicon"> may be (reversibly!) transformed to <figure><img><figcaption>Druplicon</figcaption></figure>.
  4. FilterInterface::TYPE_TRANSFORM_IRREVERSIBLE — Irreversible transformation filters. The filter performs a transform for which a WYSIWYG plugin does not exist to perform the transformation client-side (especially, the reverse of it); instead, the WYSIWYG editor displays the unfiltered text. For example, Token Filter.

check_markup()

Using the check_markup() function, you can filter a user-supplied string using a text format. The return value has the type MarkupInterface and is fully filtered against the configured format.

See also

• Filter module: text formats that filter user input
• Text Editor module: associating assistive editors with text formats
• Drupal 8: best authoring experience for structured content?
• Creating a Custom Filter in Drupal 8