class FilterProcessResult

Same name in other branches
  1. 9 core/modules/filter/src/FilterProcessResult.php \Drupal\filter\FilterProcessResult
  2. 10 core/modules/filter/src/FilterProcessResult.php \Drupal\filter\FilterProcessResult
  3. 11.x core/modules/filter/src/FilterProcessResult.php \Drupal\filter\FilterProcessResult

Used to return values from a text filter plugin's processing method.

The typical use case for a text filter plugin's processing method is to just apply some filtering to the given text, but for more advanced use cases, it may be necessary to also:

  • Declare asset libraries to be loaded.
  • Declare cache tags that the filtered text depends upon, so when either of those cache tags is invalidated, the filtered text should also be invalidated.
  • Declare cache context to vary by, e.g. 'language' to do language-specific filtering.
  • Declare a maximum age for the filtered text.
  • Apply uncacheable filtering, for example because it differs per user.

In case a filter needs one or more of these advanced use cases, it can use the additional methods available.

The typical use case:


public function process($text, $langcode) {
  // Modify $text.

  return new FilterProcessResult($text);
}

The advanced use cases:


public function process($text, $langcode) {
  // Modify $text.

  $result = new FilterProcessResult($text);

  // Associate assets to be attached.
  $result->setAttachments(array(
    'library' => array(
       'filter/caption',
    ),
  ));

  // Associate cache contexts to vary by.
  $result->setCacheContexts(['language']);

  // Associate cache tags to be invalidated by.
  $result->setCacheTags($node->getCacheTags());

  // Associate a maximum age.
  $result->setCacheMaxAge(300); // 5 minutes.

  return $result;
}

Hierarchy

Expanded class hierarchy of FilterProcessResult

23 files declare their use of FilterProcessResult
EditorFileReference.php in core/modules/editor/src/Plugin/Filter/EditorFileReference.php
FilterAlign.php in core/modules/filter/src/Plugin/Filter/FilterAlign.php
FilterAutoP.php in core/modules/filter/src/Plugin/Filter/FilterAutoP.php
FilterCaption.php in core/modules/filter/src/Plugin/Filter/FilterCaption.php
FilterHtml.php in core/modules/filter/src/Plugin/Filter/FilterHtml.php

... See full list

File

core/modules/filter/src/FilterProcessResult.php, line 64

Namespace

Drupal\filter
View source
class FilterProcessResult extends BubbleableMetadata {
    
    /**
     * The processed text.
     *
     * @see \Drupal\filter\Plugin\FilterInterface::process()
     *
     * @var string
     */
    protected $processedText;
    
    /**
     * Constructs a FilterProcessResult object.
     *
     * @param string $processed_text
     *   The text as processed by a text filter.
     */
    public function __construct($processed_text = '') {
        $this->processedText = $processed_text;
    }
    
    /**
     * Gets the processed text.
     *
     * @return string
     */
    public function getProcessedText() {
        return $this->processedText;
    }
    
    /**
     * Gets the processed text.
     *
     * @return string
     */
    public function __toString() {
        return $this->getProcessedText();
    }
    
    /**
     * Sets the processed text.
     *
     * @param string $processed_text
     *   The text as processed by a text filter.
     *
     * @return $this
     */
    public function setProcessedText($processed_text) {
        $this->processedText = $processed_text;
        return $this;
    }
    
    /**
     * Creates a placeholder.
     *
     * This generates its own placeholder markup for one major reason: to not have
     * FilterProcessResult depend on the Renderer service, because this is a value
     * object. As a side-effect and added benefit, this makes it easier to
     * distinguish placeholders for filtered text versus generic render system
     * placeholders.
     *
     * @param string $callback
     *   The #lazy_builder callback that will replace the placeholder with its
     *   eventual markup.
     * @param array $args
     *   The arguments for the #lazy_builder callback.
     *
     * @return string
     *   The placeholder markup.
     */
    public function createPlaceholder($callback, array $args) {
        // Generate placeholder markup.
        // @see \Drupal\Core\Render\PlaceholderGenerator::createPlaceholder()
        $arguments = UrlHelper::buildQuery($args);
        $token = Crypt::hashBase64(serialize([
            $callback,
            $args,
        ]));
        $placeholder_markup = '<drupal-filter-placeholder callback="' . Html::escape($callback) . '" arguments="' . Html::escape($arguments) . '" token="' . Html::escape($token) . '"></drupal-filter-placeholder>';
        // Add the placeholder attachment.
        $this->addAttachments([
            'placeholders' => [
                $placeholder_markup => [
                    '#lazy_builder' => [
                        $callback,
                        $args,
                    ],
                ],
            ],
        ]);
        // Return the placeholder markup, so that the filter wanting to use a
        // placeholder can actually insert the placeholder markup where it needs the
        // placeholder to be replaced.
        return $placeholder_markup;
    }

}

Members

Title Sort descending Modifiers Object type Summary Overriden Title
AttachmentsTrait::$attachments protected property The attachments for this response.
AttachmentsTrait::addAttachments public function
AttachmentsTrait::getAttachments public function
AttachmentsTrait::setAttachments public function
BubbleableMetadata::addCacheableDependency public function Overrides RefinableCacheableDependencyTrait::addCacheableDependency
BubbleableMetadata::applyTo public function Applies the values of this bubbleable metadata object to a render array. Overrides CacheableMetadata::applyTo
BubbleableMetadata::createFromObject public static function Creates a bubbleable metadata object from a depended object. Overrides CacheableMetadata::createFromObject
BubbleableMetadata::createFromRenderArray public static function Creates a bubbleable metadata object with values taken from a render array. Overrides CacheableMetadata::createFromRenderArray
BubbleableMetadata::merge public function Creates a new bubbleable metadata object by merging this one with another. Overrides CacheableMetadata::merge
BubbleableMetadata::mergeAttachments public static function Merges two attachments arrays (which live under the &#039;#attached&#039; key).
CacheableDependencyTrait::$cacheContexts protected property Cache contexts.
CacheableDependencyTrait::$cacheMaxAge protected property Cache max-age.
CacheableDependencyTrait::$cacheTags protected property Cache tags.
CacheableDependencyTrait::setCacheability protected function Sets cacheability; useful for value object constructors.
CacheableMetadata::getCacheContexts public function The cache contexts associated with this object. Overrides CacheableDependencyTrait::getCacheContexts
CacheableMetadata::getCacheMaxAge public function The maximum age for which this object may be cached. Overrides CacheableDependencyTrait::getCacheMaxAge
CacheableMetadata::getCacheTags public function The cache tags associated with this object. Overrides CacheableDependencyTrait::getCacheTags
CacheableMetadata::setCacheContexts public function Sets cache contexts.
CacheableMetadata::setCacheMaxAge public function Sets the maximum age (in seconds).
CacheableMetadata::setCacheTags public function Sets cache tags.
FilterProcessResult::$processedText protected property The processed text.
FilterProcessResult::createPlaceholder public function Creates a placeholder.
FilterProcessResult::getProcessedText public function Gets the processed text.
FilterProcessResult::setProcessedText public function Sets the processed text.
FilterProcessResult::__construct public function Constructs a FilterProcessResult object.
FilterProcessResult::__toString public function Gets the processed text.
RefinableCacheableDependencyTrait::addCacheContexts public function
RefinableCacheableDependencyTrait::addCacheTags public function
RefinableCacheableDependencyTrait::mergeCacheMaxAge public function

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