Version 1

[yaffs-website] / web / core / modules / filter / src / FilterProcessResult.php

diff --git a/web/core/modules/filter/src/FilterProcessResult.php b/web/core/modules/filter/src/FilterProcessResult.php
new file mode 100644 (file)
index 0000000..3fa592b
--- /dev/null
+++ b/web/core/modules/filter/src/FilterProcessResult.php
@@ -0,0 +1,156 @@
+<?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;
+  }
+
+}