A class used to pass variables by reference while they are used in twig.
This is done by saving a reference to the original render array within a TwigReference via the setReference() method like this:
$obj = new TwigReference();
$obj
->setReference($variable);
When a TwigReference is accessed via the offsetGet method the resulting reference is again wrapped within a TwigReference. Therefore references to render arrays within render arrays are also retained.
To unwrap TwigReference objects the reference can be retrieved out of the object by calling the getReference() method like this:
$variable =& $obj
->getReference();
This allows render(), hide() and show() to access the original variable and change it. The process of unwrapping and passing by reference to this functions is done transparently by the TwigReferenceFunctions helper class.
Expanded class hierarchy of TwigReference
class TwigReference extends \ArrayObject {
/**
* Holds an internal reference to the original array.
*
* @var array
*/
protected $writableRef = array();
/**
* Constructs a \Drupal\Core\Template\TwigReference object.
*
* The argument to the constructor is ignored as it is not safe that this will
* always be a reference.
*
* To set a reference use:
* @code
* $obj = new TwigReference();
* $obj->setReference($variable);
* @endcode
*
* @param $array
* The array parameter is ignored and not passed to the parent
*/
public function __construct($array = NULL) {
parent::__construct();
}
/**
* Sets a reference in the internal storage.
*
* @param $array
* The array to set as internal reference.
*/
public function setReference(&$array) {
$this
->exchangeArray($array);
$this->writableRef =& $array;
}
/**
* Gets a reference to the internal storage.
*
* Should be called like:
* @code
* $reference = &$obj->getReference();
* @endcode
*
* @return
* Returns the stored internal reference.
*/
public function &getReference() {
return $this->writableRef;
}
/**
* Sets offset in internal reference and internal storage to value.
*
* This is just for completeness, but should never be used, because
* twig cannot set properties and should not.
*
* @link http://php.net/manual/en/arrayaccess.offsetset.php
* @param mixed $offset
* The offset to assign the value to.
* @param mixed $value
* The value to set.
*/
public function offsetSet($offset, $value) {
$this->writableRef[$offset] = $value;
parent::offsetSet($offset, $value);
}
/**
* Retrieves offset from internal reference.
*
* In case of a render array, it is wrapped again within a TwigReference
* object.
*
* @param mixed $offset
* The offset to retrieve.
*
* @return mixed
* Returns a TwigReference object wrapping the array if the retrieved offset
* is a complex array (i.e. not an attribute). Else it returns the retrived
* offset directly.
*/
public function offsetGet($offset) {
if (!is_array($this->writableRef[$offset]) || $offset[0] == '#') {
return $this->writableRef[$offset];
}
// Wrap the returned array in a new TwigReference.
$x = clone $this;
// clone is faster than new
$x
->setReference($this->writableRef[$offset]);
return $x;
}
}
Name | Modifiers | Type | Description | Overrides |
---|---|---|---|---|
TwigReference:: |
protected | property | Holds an internal reference to the original array. | |
TwigReference:: |
public | function | Gets a reference to the internal storage. | |
TwigReference:: |
public | function | Retrieves offset from internal reference. | |
TwigReference:: |
public | function | Sets offset in internal reference and internal storage to value. | |
TwigReference:: |
public | function | Sets a reference in the internal storage. | |
TwigReference:: |
public | function | Constructs a \Drupal\Core\Template\TwigReference object. |