Chris@0
|
1 <?php
|
Chris@0
|
2
|
Chris@0
|
3 namespace Drupal\Core\Field;
|
Chris@0
|
4
|
Chris@0
|
5 use Drupal\Core\Config\Entity\ConfigEntityInterface;
|
Chris@0
|
6
|
Chris@0
|
7 /**
|
Chris@0
|
8 * Defines an interface for configurable field definitions.
|
Chris@0
|
9 *
|
Chris@0
|
10 * This interface allows both configurable fields and overridden base fields to
|
Chris@0
|
11 * share a common interface. The interface also extends ConfigEntityInterface
|
Chris@0
|
12 * to ensure that implementations have the expected save() method.
|
Chris@0
|
13 *
|
Chris@0
|
14 * @see \Drupal\Core\Field\Entity\BaseFieldOverride
|
Chris@0
|
15 * @see \Drupal\field\Entity\FieldConfig
|
Chris@0
|
16 */
|
Chris@0
|
17 interface FieldConfigInterface extends FieldDefinitionInterface, ConfigEntityInterface {
|
Chris@0
|
18
|
Chris@0
|
19 /**
|
Chris@0
|
20 * Sets the field definition label.
|
Chris@0
|
21 *
|
Chris@0
|
22 * @param string $label
|
Chris@0
|
23 * The label to set.
|
Chris@0
|
24 *
|
Chris@0
|
25 * @return $this
|
Chris@0
|
26 */
|
Chris@0
|
27 public function setLabel($label);
|
Chris@0
|
28
|
Chris@0
|
29 /**
|
Chris@0
|
30 * Sets a human readable description.
|
Chris@0
|
31 *
|
Chris@0
|
32 * Descriptions are usually used on user interfaces where the data is edited
|
Chris@0
|
33 * or displayed.
|
Chris@0
|
34 *
|
Chris@0
|
35 * @param string $description
|
Chris@0
|
36 * The description for this field.
|
Chris@0
|
37 *
|
Chris@0
|
38 * @return $this
|
Chris@0
|
39 */
|
Chris@0
|
40 public function setDescription($description);
|
Chris@0
|
41
|
Chris@0
|
42 /**
|
Chris@0
|
43 * Sets whether the field is translatable.
|
Chris@0
|
44 *
|
Chris@0
|
45 * @param bool $translatable
|
Chris@0
|
46 * Whether the field is translatable.
|
Chris@0
|
47 *
|
Chris@0
|
48 * @return $this
|
Chris@0
|
49 */
|
Chris@0
|
50 public function setTranslatable($translatable);
|
Chris@0
|
51
|
Chris@0
|
52 /**
|
Chris@0
|
53 * Sets field settings.
|
Chris@0
|
54 *
|
Chris@0
|
55 * Note that the method does not unset existing settings not specified in the
|
Chris@0
|
56 * incoming $settings array.
|
Chris@0
|
57 *
|
Chris@0
|
58 * For example:
|
Chris@0
|
59 * @code
|
Chris@0
|
60 * // Given these are the default settings.
|
Chris@0
|
61 * $field_definition->getSettings() === [
|
Chris@0
|
62 * 'fruit' => 'apple',
|
Chris@0
|
63 * 'season' => 'summer',
|
Chris@0
|
64 * ];
|
Chris@0
|
65 * // Change only the 'fruit' setting.
|
Chris@0
|
66 * $field_definition->setSettings(['fruit' => 'banana']);
|
Chris@0
|
67 * // The 'season' setting persists unchanged.
|
Chris@0
|
68 * $field_definition->getSettings() === [
|
Chris@0
|
69 * 'fruit' => 'banana',
|
Chris@0
|
70 * 'season' => 'summer',
|
Chris@0
|
71 * ];
|
Chris@0
|
72 * @endcode
|
Chris@0
|
73 *
|
Chris@0
|
74 * For clarity, it is preferred to use setSetting() if not all available
|
Chris@0
|
75 * settings are supplied.
|
Chris@0
|
76 *
|
Chris@0
|
77 * @param array $settings
|
Chris@0
|
78 * The array of field settings.
|
Chris@0
|
79 *
|
Chris@0
|
80 * @return $this
|
Chris@0
|
81 */
|
Chris@0
|
82 public function setSettings(array $settings);
|
Chris@0
|
83
|
Chris@0
|
84 /**
|
Chris@0
|
85 * Sets the value for a field setting by name.
|
Chris@0
|
86 *
|
Chris@0
|
87 * @param string $setting_name
|
Chris@0
|
88 * The name of the setting.
|
Chris@0
|
89 * @param mixed $value
|
Chris@0
|
90 * The value of the setting.
|
Chris@0
|
91 *
|
Chris@0
|
92 * @return $this
|
Chris@0
|
93 */
|
Chris@0
|
94 public function setSetting($setting_name, $value);
|
Chris@0
|
95
|
Chris@0
|
96 /**
|
Chris@0
|
97 * Sets whether the field can be empty.
|
Chris@0
|
98 *
|
Chris@0
|
99 * If a field is required, an entity needs to have at least a valid,
|
Chris@0
|
100 * non-empty item in that field's FieldItemList in order to pass validation.
|
Chris@0
|
101 *
|
Chris@0
|
102 * An item is considered empty if its isEmpty() method returns TRUE.
|
Chris@0
|
103 * Typically, that is if at least one of its required properties is empty.
|
Chris@0
|
104 *
|
Chris@0
|
105 * @param bool $required
|
Chris@0
|
106 * TRUE if the field is required. FALSE otherwise.
|
Chris@0
|
107 *
|
Chris@0
|
108 * @return $this
|
Chris@0
|
109 * The current object, for a fluent interface.
|
Chris@0
|
110 */
|
Chris@0
|
111 public function setRequired($required);
|
Chris@0
|
112
|
Chris@0
|
113 /**
|
Chris@0
|
114 * Sets a default value.
|
Chris@0
|
115 *
|
Chris@0
|
116 * Note that if a default value callback is set, it will take precedence over
|
Chris@0
|
117 * any value set here.
|
Chris@0
|
118 *
|
Chris@0
|
119 * @param mixed $value
|
Chris@0
|
120 * The default value for the field. This can be either:
|
Chris@0
|
121 * - a literal, in which case it will be assigned to the first property of
|
Chris@0
|
122 * the first item.
|
Chris@0
|
123 * - a numerically indexed array of items, each item being a property/value
|
Chris@0
|
124 * array.
|
Chris@0
|
125 * - a non-numerically indexed array, in which case the array is assumed to
|
Chris@0
|
126 * be a property/value array and used as the first item
|
Chris@0
|
127 * - NULL or array() for no default value.
|
Chris@0
|
128 *
|
Chris@0
|
129 * @return $this
|
Chris@0
|
130 */
|
Chris@0
|
131 public function setDefaultValue($value);
|
Chris@0
|
132
|
Chris@0
|
133 /**
|
Chris@0
|
134 * Sets a custom default value callback.
|
Chris@0
|
135 *
|
Chris@0
|
136 * If set, the callback overrides any set default value.
|
Chris@0
|
137 *
|
Chris@0
|
138 * @param string|null $callback
|
Chris@0
|
139 * The callback to invoke for getting the default value (pass NULL to unset
|
Chris@0
|
140 * a previously set callback). The callback will be invoked with the
|
Chris@0
|
141 * following arguments:
|
Chris@0
|
142 * - \Drupal\Core\Entity\FieldableEntityInterface $entity
|
Chris@0
|
143 * The entity being created.
|
Chris@0
|
144 * - \Drupal\Core\Field\FieldDefinitionInterface $definition
|
Chris@0
|
145 * The field definition.
|
Chris@0
|
146 * It should return the default value in the format accepted by the
|
Chris@0
|
147 * setDefaultValue() method.
|
Chris@0
|
148 *
|
Chris@0
|
149 * @return $this
|
Chris@0
|
150 */
|
Chris@0
|
151 public function setDefaultValueCallback($callback);
|
Chris@0
|
152
|
Chris@0
|
153 /**
|
Chris@0
|
154 * Sets constraints for a given field item property.
|
Chris@0
|
155 *
|
Chris@0
|
156 * Note: this overwrites any existing property constraints. If you need to
|
Chris@0
|
157 * add to the existing constraints, use
|
Chris@0
|
158 * \Drupal\Core\Field\FieldConfigInterface::addPropertyConstraints()
|
Chris@0
|
159 *
|
Chris@0
|
160 * Note that constraints added via this method are not stored in configuration
|
Chris@0
|
161 * and as such need to be added at runtime using
|
Chris@0
|
162 * hook_entity_bundle_field_info_alter().
|
Chris@0
|
163 *
|
Chris@0
|
164 * @param string $name
|
Chris@0
|
165 * The name of the property to set constraints for.
|
Chris@0
|
166 * @param array $constraints
|
Chris@0
|
167 * The constraints to set.
|
Chris@0
|
168 *
|
Chris@0
|
169 * @return static
|
Chris@0
|
170 * The object itself for chaining.
|
Chris@0
|
171 *
|
Chris@0
|
172 * @see hook_entity_bundle_field_info_alter()
|
Chris@0
|
173 */
|
Chris@0
|
174 public function setPropertyConstraints($name, array $constraints);
|
Chris@0
|
175
|
Chris@0
|
176 /**
|
Chris@0
|
177 * Adds constraints for a given field item property.
|
Chris@0
|
178 *
|
Chris@0
|
179 * Adds a constraint to a property of a field item. e.g.
|
Chris@0
|
180 * @code
|
Chris@0
|
181 * // Limit the field item's value property to the range 0 through 10.
|
Chris@0
|
182 * // e.g. $node->field_how_many->value.
|
Chris@0
|
183 * $field->addPropertyConstraints('value', [
|
Chris@0
|
184 * 'Range' => [
|
Chris@0
|
185 * 'min' => 0,
|
Chris@0
|
186 * 'max' => 10,
|
Chris@0
|
187 * ]
|
Chris@0
|
188 * ]);
|
Chris@0
|
189 * @endcode
|
Chris@0
|
190 *
|
Chris@0
|
191 * If you want to add a validation constraint that applies to the
|
Chris@0
|
192 * \Drupal\Core\Field\FieldItemList, use FieldConfigInterface::addConstraint()
|
Chris@0
|
193 * instead.
|
Chris@0
|
194 *
|
Chris@0
|
195 * Note: passing a new set of options for an existing property constraint will
|
Chris@0
|
196 * overwrite with the new options.
|
Chris@0
|
197 *
|
Chris@0
|
198 * Note that constraints added via this method are not stored in configuration
|
Chris@0
|
199 * and as such need to be added at runtime using
|
Chris@0
|
200 * hook_entity_bundle_field_info_alter().
|
Chris@0
|
201 *
|
Chris@0
|
202 * @param string $name
|
Chris@0
|
203 * The name of the property to set constraints for.
|
Chris@0
|
204 * @param array $constraints
|
Chris@0
|
205 * The constraints to set.
|
Chris@0
|
206 *
|
Chris@0
|
207 * @return static
|
Chris@0
|
208 * The object itself for chaining.
|
Chris@0
|
209 *
|
Chris@0
|
210 * @see \Drupal\Core\Field\FieldConfigInterface::addConstraint()
|
Chris@0
|
211 * @see hook_entity_bundle_field_info_alter()
|
Chris@0
|
212 */
|
Chris@0
|
213 public function addPropertyConstraints($name, array $constraints);
|
Chris@0
|
214
|
Chris@0
|
215 /**
|
Chris@0
|
216 * Adds a validation constraint to the FieldItemList.
|
Chris@0
|
217 *
|
Chris@0
|
218 * Note: If you wish to apply a constraint to just a property of a FieldItem
|
Chris@0
|
219 * use \Drupal\Core\Field\FieldConfigInterface::addPropertyConstraints()
|
Chris@0
|
220 * instead.
|
Chris@0
|
221 * @code
|
Chris@0
|
222 * // Add a constraint to the 'field_username' FieldItemList.
|
Chris@0
|
223 * // e.g. $node->field_username
|
Chris@0
|
224 * $fields['field_username']->addConstraint('UniqueField');
|
Chris@0
|
225 * @endcode
|
Chris@0
|
226 *
|
Chris@0
|
227 * If you wish to apply a constraint to a \Drupal\Core\Field\FieldItem instead
|
Chris@0
|
228 * of a property or FieldItemList, you can use the
|
Chris@0
|
229 * \Drupal\Core\Field\FieldConfigBase::getItemDefinition() method.
|
Chris@0
|
230 * @code
|
Chris@0
|
231 * // Add a constraint to the 'field_entity_reference' FieldItem (entity
|
Chris@0
|
232 * // reference item).
|
Chris@0
|
233 * $fields['field_entity_reference']->getItemDefinition()->addConstraint('MyCustomFieldItemValidationPlugin', []);
|
Chris@0
|
234 * @endcode
|
Chris@0
|
235 *
|
Chris@0
|
236 * See \Drupal\Core\TypedData\DataDefinitionInterface::getConstraints() for
|
Chris@0
|
237 * details.
|
Chris@0
|
238 *
|
Chris@0
|
239 * Note that constraints added via this method are not stored in configuration
|
Chris@0
|
240 * and as such need to be added at runtime using
|
Chris@0
|
241 * hook_entity_bundle_field_info_alter().
|
Chris@0
|
242 *
|
Chris@0
|
243 * @param string $constraint_name
|
Chris@0
|
244 * The name of the constraint to add, i.e. its plugin id.
|
Chris@0
|
245 * @param array|null $options
|
Chris@0
|
246 * The constraint options as required by the constraint plugin, or NULL.
|
Chris@0
|
247 *
|
Chris@0
|
248 * @return static
|
Chris@0
|
249 * The object itself for chaining.
|
Chris@0
|
250 *
|
Chris@0
|
251 * @see \Drupal\Core\Field\FieldItemList
|
Chris@0
|
252 * @see \Drupal\Core\Field\FieldConfigInterface::addPropertyConstraints()
|
Chris@0
|
253 * @see hook_entity_bundle_field_info_alter()
|
Chris@0
|
254 */
|
Chris@0
|
255 public function addConstraint($constraint_name, $options = NULL);
|
Chris@0
|
256
|
Chris@0
|
257 /**
|
Chris@0
|
258 * Sets the array of validation constraints for the FieldItemList.
|
Chris@0
|
259 *
|
Chris@0
|
260 * NOTE: This will overwrite any previously set constraints. In most cases
|
Chris@0
|
261 * FieldConfigInterface::addConstraint() should be used instead.
|
Chris@0
|
262 *
|
Chris@0
|
263 * Note that constraints added via this method are not stored in configuration
|
Chris@0
|
264 * and as such need to be added at runtime using
|
Chris@0
|
265 * hook_entity_bundle_field_info_alter().
|
Chris@0
|
266 *
|
Chris@0
|
267 * @param array $constraints
|
Chris@0
|
268 * The array of constraints. See
|
Chris@0
|
269 * \Drupal\Core\TypedData\TypedDataManager::getConstraints() for details.
|
Chris@0
|
270 *
|
Chris@0
|
271 * @return $this
|
Chris@0
|
272 *
|
Chris@0
|
273 * @see \Drupal\Core\TypedData\DataDefinition::addConstraint()
|
Chris@0
|
274 * @see \Drupal\Core\TypedData\DataDefinition::getConstraints()
|
Chris@0
|
275 * @see \Drupal\Core\Field\FieldItemList
|
Chris@0
|
276 * @see hook_entity_bundle_field_info_alter()
|
Chris@0
|
277 */
|
Chris@0
|
278 public function setConstraints(array $constraints);
|
Chris@0
|
279
|
Chris@0
|
280 }
|