annotate core/lib/Drupal/Component/Utility/SafeMarkup.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 129ea1e6d783
children
rev   line source
Chris@0 1 <?php
Chris@0 2
Chris@0 3 namespace Drupal\Component\Utility;
Chris@0 4
Chris@0 5 use Drupal\Component\Render\HtmlEscapedText;
Chris@0 6 use Drupal\Component\Render\FormattableMarkup;
Chris@0 7 use Drupal\Component\Render\MarkupInterface;
Chris@0 8
Chris@0 9 /**
Chris@0 10 * Contains deprecated functionality related to sanitization of markup.
Chris@0 11 *
Chris@0 12 * @deprecated Will be removed before Drupal 9.0.0. Use the appropriate
Chris@0 13 * @link sanitization sanitization functions @endlink or the @link theme_render theme and render systems @endlink
Chris@0 14 * so that the output can can be themed, escaped, and altered properly.
Chris@0 15 *
Chris@0 16 * @see https://www.drupal.org/node/2549395
Chris@0 17 *
Chris@0 18 * @see TwigExtension::escapeFilter()
Chris@0 19 * @see twig_render_template()
Chris@0 20 * @see sanitization
Chris@0 21 * @see theme_render
Chris@0 22 */
Chris@0 23 class SafeMarkup {
Chris@0 24
Chris@0 25 /**
Chris@0 26 * Checks if a string is safe to output.
Chris@0 27 *
Chris@0 28 * @param string|\Drupal\Component\Render\MarkupInterface $string
Chris@0 29 * The content to be checked.
Chris@0 30 * @param string $strategy
Chris@0 31 * (optional) This value is ignored.
Chris@0 32 *
Chris@0 33 * @return bool
Chris@0 34 * TRUE if the string has been marked secure, FALSE otherwise.
Chris@0 35 *
Chris@0 36 * @deprecated in Drupal 8.0.x-dev, will be removed before Drupal 9.0.0.
Chris@0 37 * Instead, you should just check if a variable is an instance of
Chris@0 38 * \Drupal\Component\Render\MarkupInterface.
Chris@0 39 *
Chris@0 40 * @see https://www.drupal.org/node/2549395
Chris@0 41 */
Chris@0 42 public static function isSafe($string, $strategy = 'html') {
Chris@17 43 @trigger_error('SafeMarkup::isSafe() is scheduled for removal in Drupal 9.0.0. Instead, you should just check if a variable is an instance of \Drupal\Component\Render\MarkupInterface. See https://www.drupal.org/node/2549395.', E_USER_DEPRECATED);
Chris@0 44 return $string instanceof MarkupInterface;
Chris@0 45 }
Chris@0 46
Chris@0 47 /**
Chris@0 48 * Encodes special characters in a plain-text string for display as HTML.
Chris@0 49 *
Chris@0 50 * Also validates strings as UTF-8. All processed strings are also
Chris@0 51 * automatically flagged as safe markup strings for rendering.
Chris@0 52 *
Chris@0 53 * @param string $text
Chris@0 54 * The text to be checked or processed.
Chris@0 55 *
Chris@0 56 * @return \Drupal\Component\Render\HtmlEscapedText
Chris@0 57 * An HtmlEscapedText object that escapes when rendered to string.
Chris@0 58 *
Chris@0 59 * @deprecated Will be removed before Drupal 9.0.0. Rely on Twig's
Chris@0 60 * auto-escaping feature, or use the @link theme_render #plain_text @endlink
Chris@0 61 * key when constructing a render array that contains plain text in order to
Chris@0 62 * use the renderer's auto-escaping feature. If neither of these are
Chris@0 63 * possible, \Drupal\Component\Utility\Html::escape() can be used in places
Chris@0 64 * where explicit escaping is needed.
Chris@0 65 *
Chris@0 66 * @see https://www.drupal.org/node/2549395
Chris@0 67 * @see drupal_validate_utf8()
Chris@0 68 */
Chris@0 69 public static function checkPlain($text) {
Chris@17 70 @trigger_error('SafeMarkup::checkPlain() is scheduled for removal in Drupal 9.0.0. Rely on Twig\'s auto-escaping feature, or use the @link theme_render #plain_text @endlink key when constructing a render array that contains plain text in order to use the renderer\'s auto-escaping feature. If neither of these are possible, \Drupal\Component\Utility\Html::escape() can be used in places where explicit escaping is needed. See https://www.drupal.org/node/2549395.', E_USER_DEPRECATED);
Chris@0 71 return new HtmlEscapedText($text);
Chris@0 72 }
Chris@0 73
Chris@0 74 /**
Chris@0 75 * Formats a string for HTML display by replacing variable placeholders.
Chris@0 76 *
Chris@0 77 * @param string $string
Chris@0 78 * A string containing placeholders. The string itself will not be escaped,
Chris@0 79 * any unsafe content must be in $args and inserted via placeholders.
Chris@0 80 * @param array $args
Chris@0 81 * An array with placeholder replacements, keyed by placeholder. See
Chris@0 82 * \Drupal\Component\Render\FormattableMarkup::placeholderFormat() for
Chris@0 83 * additional information about placeholders.
Chris@0 84 *
Chris@0 85 * @return string|\Drupal\Component\Render\MarkupInterface
Chris@0 86 * The formatted string, which is an instance of MarkupInterface unless
Chris@0 87 * sanitization of an unsafe argument was suppressed (see above).
Chris@0 88 *
Chris@0 89 * @see \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
Chris@0 90 * @see \Drupal\Component\Render\FormattableMarkup
Chris@0 91 *
Chris@0 92 * @deprecated in Drupal 8.0.0, will be removed before Drupal 9.0.0.
Chris@0 93 * Use \Drupal\Component\Render\FormattableMarkup.
Chris@0 94 *
Chris@0 95 * @see https://www.drupal.org/node/2549395
Chris@0 96 */
Chris@0 97 public static function format($string, array $args) {
Chris@17 98 @trigger_error('SafeMarkup::format() is scheduled for removal in Drupal 9.0.0. Use \Drupal\Component\Render\FormattableMarkup. See https://www.drupal.org/node/2549395.', E_USER_DEPRECATED);
Chris@0 99 return new FormattableMarkup($string, $args);
Chris@0 100 }
Chris@0 101
Chris@0 102 }