3 namespace Drupal\Core\TypedData;
5 use Drupal\Component\Plugin\PluginManagerInterface;
6 use Drupal\Component\Plugin\Discovery\CachedDiscoveryInterface;
7 use Drupal\Core\Validation\ConstraintManager;
8 use Symfony\Component\Validator\Validator\ValidatorInterface;
11 * Defines an interface for typed data manager.
13 interface TypedDataManagerInterface extends PluginManagerInterface, CachedDiscoveryInterface {
16 * Instantiates a typed data object.
18 * @param string $data_type
19 * The data type, for which a typed object should be instantiated.
20 * @param array $configuration
21 * The plugin configuration array, i.e. an array with the following keys:
22 * - data_definition: The data definition object, i.e. an instance of
23 * \Drupal\Core\TypedData\DataDefinitionInterface.
24 * - name: The name of the property or the delta of the list item if a
25 * property or list item is to be created. Otherwise, this should be set
26 * to NULL, but the key must be specified.
27 * - parent: The parent typed data object implementing either the
28 * ListInterface or the ComplexDataInterface if a property or list item is
29 * to be created. Otherwise, this should be set to NULL, but the key must
32 * @return \Drupal\Core\TypedData\TypedDataInterface
33 * The instantiated typed data object.
35 * @see \Drupal\Core\TypedData\TypedDataManager::create()
37 public function createInstance($data_type, array $configuration = []);
40 * Creates a new typed data object instance.
42 * @param \Drupal\Core\TypedData\DataDefinitionInterface $definition
43 * The data definition of the typed data object. For backwards-compatibility
44 * an array representation of the data definition may be passed also.
46 * (optional) The data value. If set, it has to match one of the supported
47 * data type format as documented for the data type classes.
49 * (optional) If a property or list item is to be created, the name of the
50 * property or the delta of the list item.
51 * @param mixed $parent
52 * (optional) If a property or list item is to be created, the parent typed
53 * data object implementing either the ListInterface or the
54 * ComplexDataInterface.
56 * @return \Drupal\Core\TypedData\TypedDataInterface
57 * The instantiated typed data object.
59 * @see \Drupal\Core\TypedData\TypedDataManager::getPropertyInstance()
60 * @see \Drupal\Core\TypedData\Plugin\DataType\BinaryData
61 * @see \Drupal\Core\TypedData\Plugin\DataType\BooleanData
62 * @see \Drupal\Core\TypedData\Plugin\DataType\Date
63 * @see \Drupal\Core\TypedData\Plugin\DataType\Duration
64 * @see \Drupal\Core\TypedData\Plugin\DataType\FloatData
65 * @see \Drupal\Core\TypedData\Plugin\DataType\IntegerData
66 * @see \Drupal\Core\TypedData\Plugin\DataType\StringData
67 * @see \Drupal\Core\TypedData\Plugin\DataType\Uri
69 public function create(DataDefinitionInterface $definition, $value = NULL, $name = NULL, $parent = NULL);
72 * Creates a new data definition object.
74 * While data definitions objects may be created directly if the definition
75 * class used by a data type is known, this method allows the creation of data
76 * definitions for any given data type.
78 * For example, if a definition for a map is to be created, the following code
79 * could be used instead of calling this method with the argument 'map':
81 * $map_definition = \Drupal\Core\TypedData\MapDataDefinition::create();
84 * @param string $data_type
85 * The data type plugin ID, for which a data definition object should be
88 * @return \Drupal\Core\TypedData\DataDefinitionInterface
89 * A data definition object for the given data type. The class of this
90 * object is provided by the definition_class in the plugin annotation.
92 * @see \Drupal\Core\TypedData\TypedDataManager::createListDataDefinition()
94 public function createDataDefinition($data_type);
97 * Creates a new list data definition for items of the given data type.
99 * @param string $item_type
100 * The item type, for which a list data definition should be created.
102 * @return \Drupal\Core\TypedData\ListDataDefinitionInterface
103 * A list definition for items of the given data type.
105 * @see \Drupal\Core\TypedData\TypedDataManager::createDataDefinition()
107 public function createListDataDefinition($item_type);
112 * @param array $options
113 * An array of options with the following keys:
114 * - object: The parent typed data object, implementing the
115 * TypedDataInterface and either the ListInterface or the
116 * ComplexDataInterface.
117 * - property: The name of the property to instantiate, or the delta of the
118 * the list item to instantiate.
119 * - value: The value to set. If set, it has to match one of the supported
120 * data type formats as documented by the data type classes.
122 * @return \Drupal\Core\TypedData\TypedDataInterface
123 * The new property instance.
125 * @throws \InvalidArgumentException
126 * If the given property is not known, or the passed object does not
127 * implement the ListInterface or the ComplexDataInterface.
129 * @see \Drupal\Core\TypedData\TypedDataManager::getPropertyInstance()
131 public function getInstance(array $options);
134 * Get a typed data instance for a property of a given typed data object.
136 * This method will use prototyping for fast and efficient instantiation of
137 * many property objects with the same property path; for example,
138 * when multiple comments are used comment_body.0.value needs to be
139 * instantiated very often.
141 * Prototyping is done by the root object's data type and the given
142 * property path, i.e. all property instances having the same property path
143 * and inheriting from the same data type are prototyped.
145 * @param \Drupal\Core\TypedData\TypedDataInterface $object
146 * The parent typed data object, implementing the TypedDataInterface and
147 * either the ListInterface or the ComplexDataInterface.
148 * @param string $property_name
149 * The name of the property to instantiate, or the delta of an list item.
150 * @param mixed $value
151 * (optional) The data value. If set, it has to match one of the supported
152 * data type formats as documented by the data type classes.
154 * @return \Drupal\Core\TypedData\TypedDataInterface
155 * The new property instance.
157 * @throws \InvalidArgumentException
158 * If the given property is not known, or the passed object does not
159 * implement the ListInterface or the ComplexDataInterface.
161 * @see \Drupal\Core\TypedData\TypedDataManager::create()
163 public function getPropertyInstance(TypedDataInterface $object, $property_name, $value = NULL);
166 * Gets the validator for validating typed data.
168 * @return \Symfony\Component\Validator\Validator\ValidatorInterface
169 * The validator object.
171 public function getValidator();
174 * Sets the validator for validating typed data.
176 * @param \Symfony\Component\Validator\Validator\ValidatorInterface $validator
177 * The validator object to set.
179 public function setValidator(ValidatorInterface $validator);
182 * Gets the validation constraint manager.
184 * @return \Drupal\Core\Validation\ConstraintManager
185 * The constraint manager.
187 public function getValidationConstraintManager();
190 * Sets the validation constraint manager.
192 * The validation constraint manager is used to instantiate validation
193 * constraint plugins.
195 * @param \Drupal\Core\Validation\ConstraintManager $constraintManager
196 * The constraint manager to set.
198 public function setValidationConstraintManager(ConstraintManager $constraintManager);
201 * Gets default constraints for the given data definition.
203 * This generates default constraint definitions based on the data definition;
204 * for example, a NotNull constraint is generated if the data is defined as
205 * required. Besides that, any constraints defined for the data type (that is,
206 * below the 'constraint' key of the type's plugin definition) are taken into
209 * @param \Drupal\Core\TypedData\DataDefinitionInterface $definition
213 * An array of validation constraint definitions, keyed by constraint name.
214 * Each constraint definition can be used for instantiating
215 * \Symfony\Component\Validator\Constraint objects.
217 public function getDefaultConstraints(DataDefinitionInterface $definition);
220 * Gets the canonical representation of a TypedData object.
222 * The canonical representation is typically used when data is passed on to
223 * other code components. In many use cases, the TypedData object is mostly
224 * unified adapter wrapping a primary value (a string, an entity, etc.) which
225 * is the canonical representation that consuming code like constraint
226 * validators are really interested in. For some APIs, though, the domain
227 * object (for example, Field API's FieldItem and FieldItemList) directly
228 * implements TypedDataInterface, and the canonical representation is thus the
229 * data object itself.
231 * When a TypedData object gets validated, for example, its canonical
232 * representation is passed on to constraint validators, which thus receive
233 * an Entity unwrapped, but a FieldItem as is.
235 * Data types specify whether their data objects need unwrapping by using the
236 * 'unwrap_for_canonical_representation' property in the data definition
237 * (defaults to TRUE).
239 * @param \Drupal\Core\TypedData\TypedDataInterface $data
243 * The canonical representation of the passed data.
245 public function getCanonicalRepresentation(TypedDataInterface $data);