Commit 6a7dc8b3 authored by catch's avatar catch

Issue #2544684 by alexpott, Pravin Ajaaz, Wim Leers: Expand @internal...

Issue #2544684 by alexpott, Pravin Ajaaz, Wim Leers: Expand @internal documentation on SafeString and SafeStringInterface and introduce ViewsRenderPipelineSafeString
parent 09a0c9f3
......@@ -10,15 +10,25 @@
/**
* Marks an object's __toString() method as returning safe markup.
*
* All objects that implement this interface should be marked @internal.
*
* This interface should only be used on objects that emit known safe strings
* from their __toString() method. If there is any risk of the method returning
* user-entered data that has not been filtered first, it must not be used.
*
* If the object is going to be used directly in Twig templates it should
* implement \Countable so it can be used in if statements.
*
* @internal
* This interface is marked as internal because it should only be used by
* objects used during rendering. Currently, there is no use case for this
* interface in contrib or custom code.
* objects used during rendering. This interface should be used by modules if
* they interrupt the render pipeline and explicitly deal with SafeString
* objects created by the render system. Additionally, if a module reuses the
* regular render pipeline internally and passes processed data into it. For
* example, Views implements a custom render pipeline in order to render JSON
* and to fast render fields.
*
* @see \Drupal\Component\Utility\SafeStringTrait
* @see \Drupal\Component\Utility\SafeMarkup::set()
* @see \Drupal\Component\Utility\SafeMarkup::isSafe()
* @see \Drupal\Core\Template\TwigExtension::escapeFilter()
......
<?php
/**
* @file
* Contains \Drupal\Component\Utility\SafeStringTrait.
*/
namespace Drupal\Component\Utility;
/**
* Implements SafeStringInterface and Countable for rendered objects.
*
* @see \Drupal\Component\Utility\SafeStringInterface
*/
trait SafeStringTrait {
/**
* The safe string.
*
* @var string
*/
protected $string;
/**
* Creates a SafeString object if necessary.
*
* If $string is equal to a blank string then it is not necessary to create a
* SafeString object. If $string is an object that implements
* SafeStringInterface 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\Utility\SafeStringInterface
* A safe string.
*/
public static function create($string) {
if ($string instanceof SafeStringInterface) {
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 SafeString 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);
}
}
......@@ -8,7 +8,7 @@
namespace Drupal\Core\Render;
use Drupal\Component\Utility\SafeStringInterface;
use Drupal\Component\Utility\Unicode;
use Drupal\Component\Utility\SafeStringTrait;
/**
* Defines an object that passes safe strings through the render system.
......@@ -18,67 +18,13 @@
* filtered first, it must not be used.
*
* @internal
* This object is marked as internal because it should only be used during
* rendering. Currently, there is no use case for this object by contrib or
* custom code.
* This object is marked as internal because it should only be used whilst
* rendering.
*
* @see \Drupal\Core\Template\TwigExtension::escapeFilter
* @see \Twig_Markup
* @see \Drupal\Component\Utility\SafeMarkup
*/
class SafeString implements SafeStringInterface, \Countable {
/**
* The safe string.
*
* @var string
*/
protected $string;
/**
* Creates a SafeString object if necessary.
*
* If $string is equal to a blank string then it is not necessary to create a
* SafeString object. If $string is an object that implements
* SafeStringInterface 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\Utility\SafeStringInterface
* A safe string.
*/
public static function create($string) {
if ($string instanceof SafeStringInterface) {
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 SafeString 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);
}
final class SafeString implements SafeStringInterface, \Countable {
use SafeStringTrait;
}
......@@ -16,10 +16,10 @@
use Drupal\Core\Cache\Cache;
use Drupal\Core\Form\FormStateInterface;
use Drupal\Core\Render\Renderer;
use Drupal\Core\Render\SafeString;
use Drupal\Core\Url as CoreUrl;
use Drupal\views\Plugin\views\HandlerBase;
use Drupal\views\Plugin\views\display\DisplayPluginBase;
use Drupal\views\Render\ViewsRenderPipelineSafeString;
use Drupal\views\ResultRow;
use Drupal\views\ViewExecutable;
......@@ -1291,7 +1291,7 @@ public function renderText($alter) {
* Render this field as user-defined altered text.
*/
protected function renderAltered($alter, $tokens) {
return SafeString::create($this->viewsTokenReplace($alter['text'], $tokens));
return ViewsRenderPipelineSafeString::create($this->viewsTokenReplace($alter['text'], $tokens));
}
/**
......
......@@ -11,10 +11,10 @@
use Drupal\Component\Utility\Xss;
use Drupal\Core\Form\FormStateInterface;
use Drupal\Core\Render\Element;
use Drupal\Core\Render\SafeString;
use Drupal\views\Plugin\views\display\DisplayPluginBase;
use Drupal\views\Plugin\views\PluginBase;
use Drupal\views\Plugin\views\wizard\WizardInterface;
use Drupal\views\Render\ViewsRenderPipelineSafeString;
use Drupal\views\ViewExecutable;
/**
......@@ -708,7 +708,7 @@ protected function renderFields(array $result) {
foreach ($this->rendered_fields[$index] as &$rendered_field) {
// Placeholders and rendered fields have been processed by the
// render system and are therefore safe.
$rendered_field = SafeString::create(str_replace($placeholders, $values, $rendered_field));
$rendered_field = ViewsRenderPipelineSafeString::create(str_replace($placeholders, $values, $rendered_field));
}
}
}
......@@ -745,7 +745,7 @@ public function elementPreRenderRow(array $data) {
* @param string $field
* The ID of the field.
*
* @return \Drupal\Core\Render\SafeString|null
* @return \Drupal\Component\Utility\SafeStringInterface|null
* The output of the field, or NULL if it was empty.
*/
public function getField($index, $field) {
......
<?php
/**
* @file
* Contains \Drupal\views\Render\ViewsRenderPipelineSafeString.
*/
namespace Drupal\views\Render;
use Drupal\Component\Utility\SafeStringInterface;
use Drupal\Component\Utility\SafeStringTrait;
/**
* Defines an object that passes safe strings through the Views render system.
*
* This object should only be constructed with a known safe string. If there is
* any risk that the string contains user-entered data that has not been
* filtered first, it must not be used.
*
* @internal
* This object is marked as internal because it should only be used in the
* Views render pipeline.
*
* @see \Drupal\Core\Render\SafeString
*/
final class ViewsRenderPipelineSafeString implements SafeStringInterface, \Countable {
use SafeStringTrait;
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment