Filter
In Drupal, a text filter is one ordered step of a text format, such as Convert URLs into links, that rewrites stored text as it is rendered.
A filter is a small piece of code that changes user-entered text when Drupal displays it. One filter removes HTML tags you have not approved, another turns URLs into clickable links, another adds captions to images. Filters are plugins that you switch on, order and configure inside a text format.
How filters work in Drupal 11
Core discovers filters as plugins in the Plugin\Filter namespace of a module. A class declares itself with the #[Filter] attribute, which requires an id, a title and a type. Most filters extend FilterBase and implement FilterInterface. Text passes through two steps. First, prepare() runs for every filter; the interface says it should be used for escaping only. Then process() runs and returns a FilterProcessResult, which can also carry assets, cacheability metadata and placeholders.
The type is one of four constants on FilterInterface: TYPE_MARKUP_LANGUAGE, TYPE_HTML_RESTRICTOR, TYPE_TRANSFORM_REVERSIBLE and TYPE_TRANSFORM_IRREVERSIBLE. A text format stores, for each filter, whether it is enabled, its weight and its settings. Filters run from top to bottom in that order.
Filters that ship with core
| Filter | What it does |
|---|---|
| Limit allowed HTML tags and correct faulty HTML | Keeps only the tags and attributes in its allowed list. |
| Correct faulty and chopped off HTML | Repairs broken or unclosed HTML. |
| Convert line breaks into HTML | Turns line breaks into <br> and <p> tags. |
| Convert URLs into links | Makes web addresses clickable. |
| Display any HTML as plain text | Shows tags as visible text instead of running them. |
| Restrict images to this site | Replaces images hosted elsewhere with a placeholder. |
| Align images, Caption images | Read the data-align and data-caption attributes of an image. |
| Lazy load images | Asks browsers to lazy load images that have dimensions. |
| Track images uploaded via a Text Editor | Keeps the latest version and the dimensions of uploaded images. |
| Embed media (Media module) | Replaces a <drupal-media> tag with the media item. |
| Entity links (Drupal 11.3 and later) | Points links that carry data-entity-type and data-entity-uuid to the current URL alias. |
Example
The Plain text format turns on three filters: display any HTML as plain text, convert URLs into links and convert line breaks. Type <b>Hello</b> https://example.com into a field that uses it and the visitor sees the tag as text, followed by a working link. The Restricted HTML format of the Standard profile instead limits HTML to a list that starts with <a href hreflang> <em> <strong>.
Common mistakes
- Ignoring the order. The Drupal help gives the case of converting URLs into links before disallowed tags are removed: all links may then be removed.
- Expecting a filter to fix saved content. It only changes the output, so the original text is still in the database.
- Mixing it up with a Views filter. In a view, a filter limits the data the view outputs, for example to published content. It has nothing to do with text formats.
- Letting untrusted roles use a format without the tag limit. The tag-limiting filter helps defend against XSS, but only in formats that enable it. The Full HTML format of the Standard profile does not.
For marketing and content teams
Filters explain surprises on the page: a pasted web address that became a link, an image that gained a caption, or a tag that vanished. Ask your developer which filters the format has before you assume a bug.
Sources
- Drupal core 11.4.8: Filter module help text (FilterHooks.php)
- Drupal core 11.4.8: FilterInterface
- Drupal core 11.4.8: Filter plugin attribute
- Drupal core 11.4.8: Core filter plugins (Plugin/Filter directory)
- Drupal core 11.4.8: FilterHtml plugin
- Drupal core 11.4.8: Plain text format
- Drupal core 11.4.8: Restricted HTML format (Standard profile)
- Drupal core 11.4.8: Full HTML format (Standard profile)
- Drupal core 11.4.8: Track images uploaded via a Text Editor filter (EditorFileReference.php)
- Drupal core 11.4.8: Embed media filter (MediaEmbed.php)
- Drupal User Guide: Concept: Text formats and editors
- Drupal User Guide: Concept: The parts of a view