class Attribute
Same name in other branches
- 9 core/lib/Drupal/Core/Template/Attribute.php \Drupal\Core\Template\Attribute
- 10 core/lib/Drupal/Core/Template/Attribute.php \Drupal\Core\Template\Attribute
- 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("xss");">
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 <em> tag">
Hierarchy
- class \Drupal\Core\Template\Attribute implements \Drupal\Core\Template\ArrayAccess, \Drupal\Core\Template\IteratorAggregate, \Drupal\Component\Render\MarkupInterface
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.
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.
File
-
core/
lib/ Drupal/ Core/ Template/ Attribute.php, line 66
Namespace
Drupal\Core\TemplateView 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.