public function TypedDataManager::getPropertyInstance

Get a typed data instance for a property of a given typed data object.

This method will use prototyping for fast and efficient instantiation of many property objects with the same property path; e.g., when multiple comments are used comment_body.0.value needs to be instantiated very often. Prototyping is done by the root object's data type and the given property path, i.e. all property instances having the same property path and inheriting from the same data type are prototyped.

@todo: Add type-hinting to $object once entities implement the TypedDataInterface.

Parameters

\Drupal\Core\TypedData\TypedDataInterface $object: The parent typed data object, implementing the TypedDataInterface and either the ListInterface or the ComplexDataInterface.

string $property_name: The name of the property to instantiate, or the delta of an list item.

mixed $value: (optional) The data value. If set, it has to match one of the supported data type formats as documented by the data type classes.

Return value

\Drupal\Core\TypedData\TypedDataInterface The new property instance.

Throws

\InvalidArgumentException If the given property is not known, or the passed object does not implement the ListInterface or the ComplexDataInterface.

See also

\Drupal\Core\TypedData\TypedDataManager::create()

File

drupal/core/lib/Drupal/Core/TypedData/TypedDataManager.php, line 211

Contains \Drupal\Core\TypedData\TypedDataManager.

Class

TypedDataManager

Manages data type plugins.

Namespace

Code

public function getPropertyInstance($object, $property_name, $value = NULL) {
  if ($root = $object
    ->getRoot()) {
    $key = $root
      ->getType() . ':' . $object
      ->getPropertyPath() . '.';

    // If we are creating list items, we always use 0 in the key as all list
    // items look the same.
    $key .= is_numeric($property_name) ? 0 : $property_name;
  }
  else {

    // Missing context, thus we cannot determine a unique key for prototyping.
    // Fall back to create a new prototype on each call.
    $key = FALSE;
  }

  // Make sure we have a prototype. Then, clone the prototype and set object
  // specific values, i.e. the value and the context.
  if (!isset($this->prototypes[$key]) || !$key) {

    // Create the initial prototype. For that we need to fetch the definition
    // of the to be created property instance from the parent.
    if ($object instanceof ComplexDataInterface) {
      $definition = $object
        ->getPropertyDefinition($property_name);
    }
    elseif ($object instanceof ListInterface) {
      $definition = $object
        ->getItemDefinition();
    }
    else {
      throw new InvalidArgumentException("The passed object has to either implement the ComplexDataInterface or the ListInterface.");
    }

    // Make sure we have got a valid definition.
    if (!$definition) {
      throw new InvalidArgumentException('Property ' . check_plain($property_name) . ' is unknown.');
    }

    // Now create the prototype using the definition, but do not pass the
    // given value as it will serve as prototype for any further instance.
    $this->prototypes[$key] = $this
      ->create($definition, NULL, $property_name, $object);
  }

  // Clone from the prototype, then update the parent relationship and set the
  // data value if necessary.
  $property = clone $this->prototypes[$key];
  $property
    ->setContext($property_name, $object);
  if (isset($value)) {
    $property
      ->setValue($value, FALSE);
  }
  return $property;
}