class FilterProcessResult in Drupal 9

Same name and namespace in other branches

8 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

class \Drupal\Core\Cache\CacheableMetadata implements RefinableCacheableDependencyInterface uses RefinableCacheableDependencyTrait
- class \Drupal\Core\Render\BubbleableMetadata implements AttachmentsInterface uses AttachmentsTrait
  - class \Drupal\filter\FilterProcessResult

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

Name	Modifiers	Type	Description
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 '#attached' 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

You are here

class FilterProcessResult in Drupal 9

Hierarchy

File

Namespace

Members

API Navigation