class Attribute

Same name in other branches
  1. 9 core/lib/Drupal/Core/Template/Attribute.php \Drupal\Core\Template\Attribute
  2. 10 core/lib/Drupal/Core/Template/Attribute.php \Drupal\Core\Template\Attribute
  3. 11.x core/lib/Drupal/Core/Template/Attribute.php \Drupal\Core\Template\Attribute

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:

$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">

$attributes always prints out all the attributes. For example:

$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">

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:


 <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"> #}

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:

$path = 'javascript:alert("xss");';
$path = UrlHelper::stripDangerousProtocols($path);
$attributes = new Attribute(array(
    'href' => $path,
));
echo '<a' . $attributes . '>';
// Produces <a href="alert(&quot;xss&quot;);">

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:

$value = t('Highlight the @tag tag', [
    '@tag' => '<em>',
]);
$attributes = new Attribute([
    'value' => $value,
]);
echo '<input' . $attributes . '>';
// Produces <input value="Highlight the &lt;em&gt; tag">

Hierarchy

Expanded class hierarchy of Attribute

See also

\Drupal\Component\Utility\Html::escape()

\Drupal\Component\Render\PlainTextOutput::renderFromHtml()

\Drupal\Component\Utility\UrlHelper::stripDangerousProtocols()

37 files declare their use of Attribute
ActiveLinkResponseFilterTest.php in core/tests/Drupal/Tests/Core/EventSubscriber/ActiveLinkResponseFilterTest.php
AttributeHelperTest.php in core/tests/Drupal/Tests/Core/Template/AttributeHelperTest.php
AttributesTest.php in core/tests/Drupal/Tests/Core/Common/AttributesTest.php
AttributeTest.php in core/tests/Drupal/Tests/Core/Template/AttributeTest.php
bartik.theme in core/themes/bartik/bartik.theme
Functions to support theming in the Bartik theme.

... See full list

6 string references to 'Attribute'
claro_preprocess_input in core/themes/claro/claro.theme
Implements template_preprocess_HOOK() for input.
claro_preprocess_select in core/themes/claro/claro.theme
Implements template_preprocess_HOOK() for select.
CompositeFormElementTrait::preRenderCompositeFormElement in core/lib/Drupal/Core/Render/Element/CompositeFormElementTrait.php
Adds form element theming to an element if its title or description is set.
FormActionXssTest::testFormActionXss in core/tests/Drupal/KernelTests/Core/Form/FormActionXssTest.php
Tests form action attribute for XSS.
FormTestLabelForm::buildForm in core/modules/system/tests/modules/form_test/src/Form/FormTestLabelForm.php
Form constructor.

... See full list

File

core/lib/Drupal/Core/Template/Attribute.php, line 66

Namespace

Drupal\Core\Template
View source
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);
        }
        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;
    }
    
    /**
     * Checks if the storage has an attribute with the given name.
     *
     * @param string $name
     *   The name of the attribute to check for.
     *
     * @return bool
     *   Returns TRUE if the attribute exists, or FALSE otherwise.
     */
    public function hasAttribute($name) {
        return array_key_exists($name, $this->storage);
    }
    
    /**
     * 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;
    }
    
    /**
     * Gets the class attribute value if set.
     *
     * This method is implemented to take precedence over hasClass() for Twig 2.0.
     *
     * @return \Drupal\Core\Template\AttributeValueBase
     *   The class attribute value if set.
     *
     * @see twig_get_attribute()
     */
    public function getClass() {
        return $this->offsetGet('class');
    }
    
    /**
     * 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;
    }
    
    /**
     * Merges an Attribute object into the current storage.
     *
     * @param \Drupal\Core\Template\Attribute $collection
     *   The Attribute object to merge.
     *
     * @return $this
     */
    public function merge(Attribute $collection) {
        $merged_attributes = NestedArray::mergeDeep($this->toArray(), $collection->toArray());
        foreach ($merged_attributes as $name => $value) {
            $this->storage[$name] = $this->createAttributeValue($name, $value);
        }
        return $this;
    }

}

Members

Title Sort descending Modifiers Object type Summary Overriden Title
Attribute::$storage protected property Stores the attribute data.
Attribute::addClass public function Adds classes or merges them on to array of existing CSS classes.
Attribute::createAttributeValue protected function Creates the different types of attribute values.
Attribute::getClass public function Gets the class attribute value if set.
Attribute::getIterator public function
Attribute::hasAttribute public function Checks if the storage has an attribute with the given name.
Attribute::hasClass public function Checks if the class array has the given CSS class.
Attribute::jsonSerialize public function Returns a representation of the object for use in JSON serialization.
Attribute::merge public function Merges an Attribute object into the current storage.
Attribute::offsetExists public function
Attribute::offsetGet public function
Attribute::offsetSet public function
Attribute::offsetUnset public function
Attribute::removeAttribute public function Removes an attribute from an Attribute object.
Attribute::removeClass public function Removes argument values from array of existing CSS classes.
Attribute::setAttribute public function Sets values for an attribute key.
Attribute::storage public function Returns the whole array.
Attribute::toArray public function Returns all storage elements as an array.
Attribute::__clone public function Implements the magic __clone() method.
Attribute::__construct public function Constructs a \Drupal\Core\Template\Attribute object.
Attribute::__toString public function Implements the magic __toString() method. Overrides MarkupInterface::__toString

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.