FilterProcessResult.php

<?php

namespace Drupal\filter;

use Drupal\Component\Utility\Crypt;
use Drupal\Component\Utility\Html;
use Drupal\Component\Utility\UrlHelper;
use Drupal\Core\Render\BubbleableMetadata;

/**
 * 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:
 * @code
 * public function process($text, $langcode) {
 *   // Modify $text.
 *
 *   return new FilterProcessResult($text);
 * }
 * @endcode
 *
 * The advanced use cases:
 * @code
 * 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;
 * }
 * @endcode
 */
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;
    }

}