opdavies/drupalcampbristol
Archived
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update to drupal 8.0.0-rc1. For more information, see https://www.drupal.org/node/2582663

Browse source
This commit is contained in:
Greg Anderson 2015-10-08 11:40:12 -07:00
parent eb34d130a8
commit f32e58e4b1
8476 changed files with 211648 additions and 170042 deletions
Download patch file Download diff file Expand all files Collapse all files

253
core/lib/Drupal/Component/Render/FormattableMarkup.php Normal file
View file

@ -0,0 +1,253 @@
<?php
/**
* @file
* Contains Drupal\Component\Render\FormattableMarkup.
*/
namespace Drupal\Component\Render;
use Drupal\Component\Utility\Html;
use Drupal\Component\Utility\SafeMarkup;
use Drupal\Component\Utility\Unicode;
use Drupal\Component\Utility\UrlHelper;
/**
* Formats a string for HTML display by replacing variable placeholders.
*
* When cast to a string, this object replaces variable placeholders in the
* string with the arguments passed in during construction and escapes the
* values so they can be safely displayed as HTML. See the documentation of
* \Drupal\Component\Render\FormattableMarkup::placeholderFormat() for details
* on the supported placeholders and how to use them securely. Incorrect use of
* this class can result in security vulnerabilities.
*
* In most cases, you should use TranslatableMarkup or PluralTranslatableMarkup
* rather than this object, since they will translate the text (on
* non-English-only sites) in addition to formatting it. Variables concatenated
* without the insertion of language-specific words or punctuation are some
* examples where translation is not applicable and using this class directly
* directly is appropriate.
*
* This class is designed for formatting messages that are mostly text, not as
* an HTML template language. As such:
* - The passed in string should contain no (or minimal) HTML.
* - Variable placeholders should not be used within the "<" and ">" of an
* HTML tag, such as in HTML attribute values. This would be a security
* risk. Examples:
* @code
* // Insecure (placeholder within "<" and ">"):
* $this->placeholderFormat('<@variable>text</@variable>', ['@variable' => $variable]);
* // Insecure (placeholder within "<" and ">"):
* $this->placeholderFormat('<a @variable>link text</a>', ['@variable' => $variable]);
* // Insecure (placeholder within "<" and ">"):
* $this->placeholderFormat('<a title="@variable">link text</a>', ['@variable' => $variable]);
* @endcode
* Only the "href" attribute is supported via the special ":variable"
* placeholder, to allow simple links to be inserted:
* @code
* // Secure (usage of ":variable" placeholder for href attribute):
* $this->placeholderFormat('<a href=":variable">link text</a>', [':variable' , $variable]);
* // Secure (usage of ":variable" placeholder for href attribute):
* $this->placeholderFormat('<a href=":variable" title="static text">link text</a>', [':variable' => $variable]);
* // Insecure (the "@variable" placeholder does not filter dangerous
* // protocols):
* $this->placeholderFormat('<a href="@variable">link text</a>', ['@variable' => $variable]);
* // Insecure ("@variable" placeholder within "<" and ">"):
* $this->placeholderFormat('<a href=":url" title="@variable">link text</a>', [':url' => $url, '@variable' => $variable]);
* @endcode
* To build non-minimal HTML, use an HTML template language such as Twig,
* rather than this class.
*
* @ingroup sanitization
*
* @see \Drupal\Core\StringTranslation\TranslatableMarkup
* @see \Drupal\Core\StringTranslation\PluralTranslatableMarkup
* @see \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
*/
class FormattableMarkup implements MarkupInterface {
/**
* The arguments to replace placeholders with.
*
* @var array
*/
protected $arguments = [];
/**
* Constructs a new class instance.
*
* @param string $string
* A string containing placeholders. The string itself will not be escaped,
* any unsafe content must be in $args and inserted via placeholders.
* @param array $arguments
* An array with placeholder replacements, keyed by placeholder. See
* \Drupal\Component\Render\FormattableMarkup::placeholderFormat() for
* additional information about placeholders.
*
* @see \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
*/
public function __construct($string, array $arguments) {
$this->string = (string) $string;
$this->arguments = $arguments;
}
/**
* {@inheritdoc}
*/
public function __toString() {
return static::placeholderFormat($this->string, $this->arguments);
}
/**
* Returns the string length.
*
* @return int
* The length of the string.
*/
public function count() {
return Unicode::strlen($this->string);
}
/**
* Returns a representation of the object for use in JSON serialization.
*
* @return string
* The safe string content.
*/
public function jsonSerialize() {
return $this->__toString();
}
/**
* Replaces placeholders in a string with values.
*
* @param string $string
* A string containing placeholders. The string itself is expected to be
* safe and correct HTML. Any unsafe content must be in $args and
* inserted via placeholders.
* @param array $args
* An associative array of replacements. Each array key should be the same
* as a placeholder in $string. The corresponding value should be a string
* or an object that implements
* \Drupal\Component\Render\MarkupInterface. The value replaces the
* placeholder in $string. Sanitization and formatting will be done before
* replacement. The type of sanitization and formatting depends on the first
* character of the key:
* - @variable: When the placeholder replacement value is:
* - A string, the replaced value in the returned string will be sanitized
* using \Drupal\Component\Utility\Html::escape().
* - A MarkupInterface object, the replaced value in the returned string
* will not be sanitized.
* - A MarkupInterface object cast to a string, the replaced value in the
* returned string be forcibly sanitized using
* \Drupal\Component\Utility\Html::escape().
* @code
* $this->placeholderFormat('This will force HTML-escaping of the replacement value: @text', ['@text' => (string) $safe_string_interface_object));
* @endcode
* Use this placeholder as the default choice for anything displayed on
* the site, but not within HTML attributes, JavaScript, or CSS. Doing so
* is a security risk.
* - %variable: Use when the replacement value is to be wrapped in <em>
* tags.
* A call like:
* @code
* $string = "%output_text";
* $arguments = ['output_text' => 'text output here.'];
* $this->placeholderFormat($string, $arguments);
* @endcode
* makes the following HTML code:
* @code
* <em class="placeholder">text output here.</em>
* @endcode
* As with @variable, do not use this within HTML attributes, JavaScript,
* or CSS. Doing so is a security risk.
* - :variable: Return value is escaped with
* \Drupal\Component\Utility\Html::escape() and filtered for dangerous
* protocols using UrlHelper::stripDangerousProtocols(). Use this when
* using the "href" attribute, ensuring the attribute value is always
* wrapped in quotes:
* @code
* // Secure (with quotes):
* $this->placeholderFormat('<a href=":url">@variable</a>', [':url' => $url, @variable => $variable]);
* // Insecure (without quotes):
* $this->placeholderFormat('<a href=:url>@variable</a>', [':url' => $url, @variable => $variable]);
* @endcode
* When ":variable" comes from arbitrary user input, the result is secure,
* but not guaranteed to be a valid URL (which means the resulting output
* could fail HTML validation). To guarantee a valid URL, use
* Url::fromUri($user_input)->toString() (which either throws an exception
* or returns a well-formed URL) before passing the result into a
* ":variable" placeholder.
*
* @return string
* A formatted HTML string with the placeholders replaced.
*
* @ingroup sanitization
*
* @see \Drupal\Core\StringTranslation\TranslatableMarkup
* @see \Drupal\Core\StringTranslation\PluralTranslatableMarkup
* @see \Drupal\Component\Utility\Html::escape()
* @see \Drupal\Component\Utility\UrlHelper::stripDangerousProtocols()
* @see \Drupal\Core\Url::fromUri()
*/
protected static function placeholderFormat($string, array $args) {
// Transform arguments before inserting them.
foreach ($args as $key => $value) {
switch ($key[0]) {
case '@':
// Escape if the value is not an object from a class that implements
// \Drupal\Component\Render\MarkupInterface, for example strings will
// be escaped.
// \Drupal\Component\Utility\SafeMarkup\SafeMarkup::isSafe() may
// return TRUE for content that is safe within HTML fragments, but not
// within other contexts, so this placeholder type must not be used
// within HTML attributes, JavaScript, or CSS.
$args[$key] = static::placeholderEscape($value);
break;
case ':':
// Strip URL protocols that can be XSS vectors.
$value = UrlHelper::stripDangerousProtocols($value);
// Escape unconditionally, without checking
// \Drupal\Component\Utility\SafeMarkup\SafeMarkup::isSafe(). This
// forces characters that are unsafe for use in an "href" HTML
// attribute to be encoded. If a caller wants to pass a value that is
// extracted from HTML and therefore is already HTML encoded, it must
// invoke
// \Drupal\Component\Render\OutputStrategyInterface::renderFromHtml()
// on it prior to passing it in as a placeholder value of this type.
// @todo Add some advice and stronger warnings.
// https://www.drupal.org/node/2569041.
$args[$key] = Html::escape($value);
break;
case '%':
default:
// Similarly to @, escape non-safe values. Also, add wrapping markup
// in order to render as a placeholder. Not for use within attributes,
// per the warning above about
// \Drupal\Component\Utility\SafeMarkup\SafeMarkup::isSafe() and also
// due to the wrapping markup.
$args[$key] = '<em class="placeholder">' . static::placeholderEscape($value) . '</em>';
break;
}
}
return strtr($string, $args);
}
/**
* Escapes a placeholder replacement value if needed.
*
* @param string|\Drupal\Component\Render\MarkupInterface $value
* A placeholder replacement value.
*
* @return string
* The properly escaped replacement value.
*/
protected static function placeholderEscape($value) {
return SafeMarkup::isSafe($value) ? (string) $value : Html::escape($value);
}
}

61
core/lib/Drupal/Component/Render/HtmlEscapedText.php Normal file
View file

@ -0,0 +1,61 @@
<?php
/**
* @file
* Contains \Drupal\Component\Render\HtmlEscapedText.
*/
namespace Drupal\Component\Render;
use Drupal\Component\Utility\Html;
use Drupal\Component\Utility\Unicode;
/**
* Escapes HTML syntax characters to HTML entities for display in markup.
*
* This class can be used to provide theme engine-like late escaping
* functionality.
*
* @ingroup sanitization
*/
class HtmlEscapedText implements MarkupInterface {
/**
* The string to escape.
*
* @var string
*/
protected $string;
/**
* Constructs an HtmlEscapedText object.
*
* @param $string
* The string to escape. This value will be cast to a string.
*/
public function __construct($string) {
$this->string = (string) $string;
}
/**
* {@inheritdoc}
*/
public function __toString() {
return Html::escape($this->string);
}
/**
* {@inheritdoc}
*/
public function count() {
return Unicode::strlen($this->string);
}
/**
* {@inheritdoc}
*/
public function jsonSerialize() {
return $this->__toString();
}
}

48
core/lib/Drupal/Component/Render/MarkupInterface.php Normal file
View file

@ -0,0 +1,48 @@
<?php
/**
* @file
* Contains \Drupal\Component\Render\MarkupInterface.
*/
namespace Drupal\Component\Render;
/**
* Marks an object's __toString() method as returning markup.
*
* Objects that implement this interface will not be automatically XSS filtered
* by the render system or automatically escaped by the theme engine.
*
* If there is any risk of the object's __toString() method returning
* user-entered data that has not been filtered first, it must not be used. If
* the object that implements this does not perform automatic escaping or
* filtering itself, then it must be marked as "@internal". For example, Views
* has the internal ViewsRenderPipelineMarkup object to provide a custom render
* pipeline in order to render JSON and to fast render fields. By contrast,
* FormattableMarkup and TranslatableMarkup always sanitize their output when
* used correctly.
*
* If the object is going to be used directly in Twig templates it should
* implement \Countable so it can be used in if statements.
*
* @see \Drupal\Component\Render\MarkupTrait
* @see \Drupal\Component\Utility\SafeMarkup::isSafe()
* @see \Drupal\Core\Template\TwigExtension::escapeFilter()
* @see \Drupal\Component\Render\FormattableMarkup
* @see \Drupal\Core\StringTranslation\TranslatableMarkup
* @see \Drupal\views\Render\ViewsRenderPipelineMarkup
* @see twig_render_template()
* @see sanitization
* @see theme_render
*/
interface MarkupInterface extends \JsonSerializable {
/**
* Returns markup.
*
* @return string
* The markup.
*/
public function __toString();
}

82
core/lib/Drupal/Component/Render/MarkupTrait.php Normal file
View file

@ -0,0 +1,82 @@
<?php
/**
* @file
* Contains \Drupal\Component\Render\MarkupTrait.
*/
namespace Drupal\Component\Render;
use Drupal\Component\Utility\Unicode;
/**
* Implements MarkupInterface and Countable for rendered objects.
*
* @see \Drupal\Component\Render\MarkupInterface
*/
trait MarkupTrait {
/**
* The safe string.
*
* @var string
*/
protected $string;
/**
* Creates a Markup object if necessary.
*
* If $string is equal to a blank string then it is not necessary to create a
* Markup object. If $string is an object that implements MarkupInterface it
* is returned unchanged.
*
* @param mixed $string
* The string to mark as safe. This value will be cast to a string.
*
* @return string|\Drupal\Component\Render\MarkupInterface
* A safe string.
*/
public static function create($string) {
if ($string instanceof MarkupInterface) {
return $string;
}
$string = (string) $string;
if ($string === '') {
return '';
}
$safe_string = new static();
$safe_string->string = $string;
return $safe_string;
}
/**
* Returns the string version of the Markup object.
*
* @return string
* The safe string content.
*/
public function __toString() {
return $this->string;
}
/**
* Returns the string length.
*
* @return int
* The length of the string.
*/
public function count() {
return Unicode::strlen($this->string);
}
/**
* Returns a representation of the object for use in JSON serialization.
*
* @return string
* The safe string content.
*/
public function jsonSerialize() {
return $this->__toString();
}
}

36
core/lib/Drupal/Component/Render/OutputStrategyInterface.php Normal file
View file

@ -0,0 +1,36 @@
<?php
/**
* @file
* Contains \Drupal\Component\Render\OutputStrategyInterface.
*/
namespace Drupal\Component\Render;
/**
* Provides an output strategy that formats HTML strings for a given context.
*
* Output strategies assist in transforming HTML strings into strings that are
* appropriate for a given context (e.g. plain-text), through performing the
* relevant formatting. No santization is applied.
*/
interface OutputStrategyInterface {
/**
* Transforms a given HTML string into to a context-appropriate output string.
*
* This transformation consists of performing the formatting appropriate to
* a given output context (e.g., plain-text email subjects, HTML attribute
* values).
*
* @param string|object $string
* An HTML string or an object with a ::__toString() magic method returning
* HTML markup. The source HTML markup is considered ready for output into
* HTML fragments and thus already properly escaped and sanitized.
*
* @return string
* A new string that is formatted according to the output strategy.
*/
public static function renderFromHtml($string);
}

29
core/lib/Drupal/Component/Render/PlainTextOutput.php Normal file
View file

@ -0,0 +1,29 @@
<?php
/**
* @file
* Contains \Drupal\Component\Render\PlainTextOutput.
*/
namespace Drupal\Component\Render;
use Drupal\Component\Utility\Html;
/**
* Provides an output strategy for transforming HTML into simple plain text.
*
* Use this when rendering a given HTML string into a plain text string that
* does not need special formatting, such as a label or an email subject.
*
* Returns a string with HTML tags stripped and HTML entities decoded suitable
* for email or other non-HTML contexts.
*/
class PlainTextOutput implements OutputStrategyInterface {
/**
* {@inheritdoc}
*/
public static function renderFromHtml($string) {
return Html::decodeEntities(strip_tags((string) $string));
}
}