123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345 |
- <?php
- namespace Drupal\Core\Template;
- use Drupal\Component\Render\PlainTextOutput;
- use Drupal\Component\Render\MarkupInterface;
- /**
- * Collects, sanitizes, and renders HTML attributes.
- *
- * To use, optionally pass in an associative array of defined attributes, or
- * add attributes using array syntax. For example:
- * @code
- * $attributes = new Attribute(array('id' => 'socks'));
- * $attributes['class'] = array('black-cat', 'white-cat');
- * $attributes['class'][] = 'black-white-cat';
- * echo '<cat' . $attributes . '>';
- * // Produces <cat id="socks" class="black-cat white-cat black-white-cat">
- * @endcode
- *
- * $attributes always prints out all the attributes. For example:
- * @code
- * $attributes = new Attribute(array('id' => 'socks'));
- * $attributes['class'] = array('black-cat', 'white-cat');
- * $attributes['class'][] = 'black-white-cat';
- * echo '<cat class="cat ' . $attributes['class'] . '"' . $attributes . '>';
- * // Produces <cat class="cat black-cat white-cat black-white-cat" id="socks" class="cat black-cat white-cat black-white-cat">
- * @endcode
- *
- * When printing out individual attributes to customize them within a Twig
- * template, use the "without" filter to prevent attributes that have already
- * been printed from being printed again. For example:
- * @code
- * <cat class="{{ attributes.class }} my-custom-class"{{ attributes|without('class') }}>
- * {# Produces <cat class="cat black-cat white-cat black-white-cat my-custom-class" id="socks"> #}
- * @endcode
- *
- * The attribute keys and values are automatically escaped for output with
- * Html::escape(). No protocol filtering is applied, so when using user-entered
- * input as a value for an attribute that expects an URI (href, src, ...),
- * UrlHelper::stripDangerousProtocols() should be used to ensure dangerous
- * protocols (such as 'javascript:') are removed. For example:
- * @code
- * $path = 'javascript:alert("xss");';
- * $path = UrlHelper::stripDangerousProtocols($path);
- * $attributes = new Attribute(array('href' => $path));
- * echo '<a' . $attributes . '>';
- * // Produces <a href="alert("xss");">
- * @endcode
- *
- * The attribute values are considered plain text and are treated as such. If a
- * safe HTML string is detected, it is converted to plain text with
- * PlainTextOutput::renderFromHtml() before being escaped. For example:
- * @code
- * $value = t('Highlight the @tag tag', ['@tag' => '<em>']);
- * $attributes = new Attribute(['value' => $value]);
- * echo '<input' . $attributes . '>';
- * // Produces <input value="Highlight the <em> tag">
- * @endcode
- *
- * @see \Drupal\Component\Utility\Html::escape()
- * @see \Drupal\Component\Render\PlainTextOutput::renderFromHtml()
- * @see \Drupal\Component\Utility\UrlHelper::stripDangerousProtocols()
- */
- class Attribute implements \ArrayAccess, \IteratorAggregate, MarkupInterface {
- /**
- * Stores the attribute data.
- *
- * @var \Drupal\Core\Template\AttributeValueBase[]
- */
- protected $storage = [];
- /**
- * Constructs a \Drupal\Core\Template\Attribute object.
- *
- * @param array $attributes
- * An associative array of key-value pairs to be converted to attributes.
- */
- public function __construct($attributes = []) {
- foreach ($attributes as $name => $value) {
- $this->offsetSet($name, $value);
- }
- }
- /**
- * {@inheritdoc}
- */
- public function offsetGet($name) {
- if (isset($this->storage[$name])) {
- return $this->storage[$name];
- }
- }
- /**
- * {@inheritdoc}
- */
- public function offsetSet($name, $value) {
- $this->storage[$name] = $this->createAttributeValue($name, $value);
- }
- /**
- * Creates the different types of attribute values.
- *
- * @param string $name
- * The attribute name.
- * @param mixed $value
- * The attribute value.
- *
- * @return \Drupal\Core\Template\AttributeValueBase
- * An AttributeValueBase representation of the attribute's value.
- */
- protected function createAttributeValue($name, $value) {
- // If the value is already an AttributeValueBase object,
- // return a new instance of the same class, but with the new name.
- if ($value instanceof AttributeValueBase) {
- $class = get_class($value);
- return new $class($name, $value->value());
- }
- // An array value or 'class' attribute name are forced to always be an
- // AttributeArray value for consistency.
- if ($name == 'class' && !is_array($value)) {
- // Cast the value to string in case it implements MarkupInterface.
- $value = [(string) $value];
- }
- if (is_array($value)) {
- // Cast the value to an array if the value was passed in as a string.
- // @todo Decide to fix all the broken instances of class as a string
- // in core or cast them.
- $value = new AttributeArray($name, $value);
- }
- elseif (is_bool($value)) {
- $value = new AttributeBoolean($name, $value);
- }
- // As a development aid, we allow the value to be a safe string object.
- elseif ($value instanceof MarkupInterface) {
- // Attributes are not supposed to display HTML markup, so we just convert
- // the value to plain text.
- $value = PlainTextOutput::renderFromHtml($value);
- $value = new AttributeString($name, $value);
- }
- elseif (!is_object($value)) {
- $value = new AttributeString($name, $value);
- }
- return $value;
- }
- /**
- * {@inheritdoc}
- */
- public function offsetUnset($name) {
- unset($this->storage[$name]);
- }
- /**
- * {@inheritdoc}
- */
- public function offsetExists($name) {
- return isset($this->storage[$name]);
- }
- /**
- * Adds classes or merges them on to array of existing CSS classes.
- *
- * @param string|array ...
- * CSS classes to add to the class attribute array.
- *
- * @return $this
- */
- public function addClass() {
- $args = func_get_args();
- if ($args) {
- $classes = [];
- foreach ($args as $arg) {
- // Merge the values passed in from the classes array.
- // The argument is cast to an array to support comma separated single
- // values or one or more array arguments.
- $classes = array_merge($classes, (array) $arg);
- }
- // Merge if there are values, just add them otherwise.
- if (isset($this->storage['class']) && $this->storage['class'] instanceof AttributeArray) {
- // Merge the values passed in from the class value array.
- $classes = array_merge($this->storage['class']->value(), $classes);
- $this->storage['class']->exchangeArray($classes);
- }
- else {
- $this->offsetSet('class', $classes);
- }
- }
- return $this;
- }
- /**
- * Sets values for an attribute key.
- *
- * @param string $attribute
- * Name of the attribute.
- * @param string|array $value
- * Value(s) to set for the given attribute key.
- *
- * @return $this
- */
- public function setAttribute($attribute, $value) {
- $this->offsetSet($attribute, $value);
- return $this;
- }
- /**
- * Removes an attribute from an Attribute object.
- *
- * @param string|array ...
- * Attributes to remove from the attribute array.
- *
- * @return $this
- */
- public function removeAttribute() {
- $args = func_get_args();
- foreach ($args as $arg) {
- // Support arrays or multiple arguments.
- if (is_array($arg)) {
- foreach ($arg as $value) {
- unset($this->storage[$value]);
- }
- }
- else {
- unset($this->storage[$arg]);
- }
- }
- return $this;
- }
- /**
- * Removes argument values from array of existing CSS classes.
- *
- * @param string|array ...
- * CSS classes to remove from the class attribute array.
- *
- * @return $this
- */
- public function removeClass() {
- // With no class attribute, there is no need to remove.
- if (isset($this->storage['class']) && $this->storage['class'] instanceof AttributeArray) {
- $args = func_get_args();
- $classes = [];
- foreach ($args as $arg) {
- // Merge the values passed in from the classes array.
- // The argument is cast to an array to support comma separated single
- // values or one or more array arguments.
- $classes = array_merge($classes, (array) $arg);
- }
- // Remove the values passed in from the value array. Use array_values() to
- // ensure that the array index remains sequential.
- $classes = array_values(array_diff($this->storage['class']->value(), $classes));
- $this->storage['class']->exchangeArray($classes);
- }
- return $this;
- }
- /**
- * Checks if the class array has the given CSS class.
- *
- * @param string $class
- * The CSS class to check for.
- *
- * @return bool
- * Returns TRUE if the class exists, or FALSE otherwise.
- */
- public function hasClass($class) {
- if (isset($this->storage['class']) && $this->storage['class'] instanceof AttributeArray) {
- return in_array($class, $this->storage['class']->value());
- }
- else {
- return FALSE;
- }
- }
- /**
- * Implements the magic __toString() method.
- */
- public function __toString() {
- $return = '';
- /** @var \Drupal\Core\Template\AttributeValueBase $value */
- foreach ($this->storage as $name => $value) {
- $rendered = $value->render();
- if ($rendered) {
- $return .= ' ' . $rendered;
- }
- }
- return $return;
- }
- /**
- * Returns all storage elements as an array.
- *
- * @return array
- * An associative array of attributes.
- */
- public function toArray() {
- $return = [];
- foreach ($this->storage as $name => $value) {
- $return[$name] = $value->value();
- }
- return $return;
- }
- /**
- * Implements the magic __clone() method.
- */
- public function __clone() {
- foreach ($this->storage as $name => $value) {
- $this->storage[$name] = clone $value;
- }
- }
- /**
- * {@inheritdoc}
- */
- public function getIterator() {
- return new \ArrayIterator($this->storage);
- }
- /**
- * Returns the whole array.
- */
- public function storage() {
- return $this->storage;
- }
- /**
- * Returns a representation of the object for use in JSON serialization.
- *
- * @return string
- * The safe string content.
- */
- public function jsonSerialize() {
- return (string) $this;
- }
- }
|