annotate core/lib/Drupal/Core/Field/FieldDefinition.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents af1871eacc83
children
rev   line source
Chris@18 1 <?php
Chris@18 2
Chris@18 3 namespace Drupal\Core\Field;
Chris@18 4
Chris@18 5 use Drupal\Core\Cache\UnchangingCacheableDependencyTrait;
Chris@18 6 use Drupal\Core\Entity\FieldableEntityInterface;
Chris@18 7 use Drupal\Core\Field\TypedData\FieldItemDataDefinition;
Chris@18 8 use Drupal\Core\TypedData\ListDataDefinition;
Chris@18 9
Chris@18 10 /**
Chris@18 11 * A class for defining entity field definitions.
Chris@18 12 *
Chris@18 13 * A field definition in the context of a bundle field is different from a base
Chris@18 14 * field in that it may exist only for one or more bundles of an entity type. A
Chris@18 15 * bundle field definition may also override the definition of an existing base
Chris@18 16 * field definition on a per bundle basis. The bundle field definition is used
Chris@18 17 * for code driven overrides, while the
Chris@18 18 * \Drupal\Core\Field\Entity\BaseFieldOverride uses config to override the base
Chris@18 19 * field definition.
Chris@18 20 *
Chris@18 21 * Bundle fields can be defined in code using hook_entity_bundle_field_info() or
Chris@18 22 * via the
Chris@18 23 * \Drupal\Core\Entity\FieldableEntityInterface::bundleFieldDefinitions() method
Chris@18 24 * when defining an entity type. All bundle fields require an associated storage
Chris@18 25 * definition. A storage definition may have automatically been defined when
Chris@18 26 * overriding a base field or it may be manually provided via
Chris@18 27 * hook_entity_field_storage_info().
Chris@18 28 *
Chris@18 29 * @see \Drupal\Core\Entity\FieldableEntityInterface::bundleFieldDefinitions()
Chris@18 30 * @see \Drupal\Core\Field\FieldDefinitionInterface
Chris@18 31 * @see \Drupal\Core\Field\FieldStorageDefinitionInterface
Chris@18 32 * @see hook_entity_bundle_field_info()
Chris@18 33 * @see hook_entity_field_storage_info()
Chris@18 34 */
Chris@18 35 class FieldDefinition extends ListDataDefinition implements FieldDefinitionInterface {
Chris@18 36
Chris@18 37 use UnchangingCacheableDependencyTrait;
Chris@18 38 use FieldInputValueNormalizerTrait;
Chris@18 39
Chris@18 40 /**
Chris@18 41 * The associated field storage definition.
Chris@18 42 *
Chris@18 43 * @var \Drupal\Core\Field\FieldStorageDefinitionInterface
Chris@18 44 */
Chris@18 45 protected $fieldStorageDefinition;
Chris@18 46
Chris@18 47 /**
Chris@18 48 * Creates a new field definition.
Chris@18 49 *
Chris@18 50 * @param \Drupal\Core\Field\FieldStorageDefinitionInterface $storageDefinition
Chris@18 51 * The associated field storage definition.
Chris@18 52 *
Chris@18 53 * @return static
Chris@18 54 */
Chris@18 55 public static function createFromFieldStorageDefinition(FieldStorageDefinitionInterface $storageDefinition) {
Chris@18 56 $field_definition = new static();
Chris@18 57 $field_definition->setFieldStorageDefinition($storageDefinition);
Chris@18 58 return $field_definition;
Chris@18 59 }
Chris@18 60
Chris@18 61 /**
Chris@18 62 * {@inheritdoc}
Chris@18 63 */
Chris@18 64 public function getName() {
Chris@18 65 return $this->getFieldStorageDefinition()->getName();
Chris@18 66 }
Chris@18 67
Chris@18 68 /**
Chris@18 69 * {@inheritdoc}
Chris@18 70 */
Chris@18 71 public function getType() {
Chris@18 72 return $this->getFieldStorageDefinition()->getType();
Chris@18 73 }
Chris@18 74
Chris@18 75 /**
Chris@18 76 * {@inheritdoc}
Chris@18 77 */
Chris@18 78 public function getTargetEntityTypeId() {
Chris@18 79 return $this->getFieldStorageDefinition()->getTargetEntityTypeId();
Chris@18 80 }
Chris@18 81
Chris@18 82 /**
Chris@18 83 * Set the target bundle.
Chris@18 84 *
Chris@18 85 * @param string $bundle
Chris@18 86 * The target bundle.
Chris@18 87 *
Chris@18 88 * @return $this
Chris@18 89 */
Chris@18 90 public function setTargetBundle($bundle) {
Chris@18 91 $this->definition['bundle'] = $bundle;
Chris@18 92 return $this;
Chris@18 93 }
Chris@18 94
Chris@18 95 /**
Chris@18 96 * {@inheritdoc}
Chris@18 97 */
Chris@18 98 public function getTargetBundle() {
Chris@18 99 return $this->definition['bundle'];
Chris@18 100 }
Chris@18 101
Chris@18 102 /**
Chris@18 103 * Sets whether the display for the field can be configured.
Chris@18 104 *
Chris@18 105 * @param string $display_context
Chris@18 106 * The display context. Either 'view' or 'form'.
Chris@18 107 * @param bool $configurable
Chris@18 108 * Whether the display options can be configured (e.g., via the "Manage
Chris@18 109 * display" / "Manage form display" UI screens). If TRUE, the options
Chris@18 110 * specified via getDisplayOptions() act as defaults.
Chris@18 111 *
Chris@18 112 * @return $this
Chris@18 113 */
Chris@18 114 public function setDisplayConfigurable($display_context, $configurable) {
Chris@18 115 // If no explicit display options have been specified, default to 'hidden'.
Chris@18 116 if (empty($this->definition['display'][$display_context])) {
Chris@18 117 $this->definition['display'][$display_context]['options'] = ['region' => 'hidden'];
Chris@18 118 }
Chris@18 119 $this->definition['display'][$display_context]['configurable'] = $configurable;
Chris@18 120 return $this;
Chris@18 121 }
Chris@18 122
Chris@18 123 /**
Chris@18 124 * {@inheritdoc}
Chris@18 125 */
Chris@18 126 public function isDisplayConfigurable($display_context) {
Chris@18 127 return isset($this->definition['display'][$display_context]['configurable']) ? $this->definition['display'][$display_context]['configurable'] : FALSE;
Chris@18 128 }
Chris@18 129
Chris@18 130 /**
Chris@18 131 * Sets the display options for the field in forms or rendered entities.
Chris@18 132 *
Chris@18 133 * This enables generic rendering of the field with widgets / formatters,
Chris@18 134 * including automated support for "In place editing", and with optional
Chris@18 135 * configurability in the "Manage display" / "Manage form display" UI screens.
Chris@18 136 *
Chris@18 137 * Unless this method is called, the field remains invisible (or requires
Chris@18 138 * ad-hoc rendering logic).
Chris@18 139 *
Chris@18 140 * @param string $display_context
Chris@18 141 * The display context. Either 'view' or 'form'.
Chris@18 142 * @param array $options
Chris@18 143 * An array of display options. Refer to
Chris@18 144 * \Drupal\Core\Field\FieldDefinitionInterface::getDisplayOptions() for
Chris@18 145 * a list of supported keys. The options should include at least a 'weight',
Chris@18 146 * or specify 'type' = 'hidden'. The 'default_widget' / 'default_formatter'
Chris@18 147 * for the field type will be used if no 'type' is specified.
Chris@18 148 *
Chris@18 149 * @return $this
Chris@18 150 */
Chris@18 151 public function setDisplayOptions($display_context, array $options) {
Chris@18 152 $this->definition['display'][$display_context]['options'] = $options;
Chris@18 153 return $this;
Chris@18 154 }
Chris@18 155
Chris@18 156 /**
Chris@18 157 * {@inheritdoc}
Chris@18 158 */
Chris@18 159 public function getDisplayOptions($display_context) {
Chris@18 160 return isset($this->definition['display'][$display_context]['options']) ? $this->definition['display'][$display_context]['options'] : NULL;
Chris@18 161 }
Chris@18 162
Chris@18 163 /**
Chris@18 164 * {@inheritdoc}
Chris@18 165 */
Chris@18 166 public function getDefaultValueLiteral() {
Chris@18 167 return isset($this->definition['default_value']) ? $this->definition['default_value'] : [];
Chris@18 168 }
Chris@18 169
Chris@18 170 /**
Chris@18 171 * Set the default value callback for the field.
Chris@18 172 *
Chris@18 173 * @param string $callback
Chris@18 174 * The default value callback.
Chris@18 175 *
Chris@18 176 * @return $this
Chris@18 177 */
Chris@18 178 public function setDefaultValueCallback($callback) {
Chris@18 179 if (isset($callback) && !is_string($callback)) {
Chris@18 180 throw new \InvalidArgumentException('Default value callback must be a string, like "function_name" or "ClassName::methodName"');
Chris@18 181 }
Chris@18 182 $this->definition['default_value_callback'] = $callback;
Chris@18 183 return $this;
Chris@18 184 }
Chris@18 185
Chris@18 186 /**
Chris@18 187 * {@inheritdoc}
Chris@18 188 */
Chris@18 189 public function getDefaultValueCallback() {
Chris@18 190 return isset($this->definition['default_value_callback']) ? $this->definition['default_value_callback'] : NULL;
Chris@18 191 }
Chris@18 192
Chris@18 193 /**
Chris@18 194 * Set a default value for the field.
Chris@18 195 *
Chris@18 196 * @param mixed $value
Chris@18 197 * The default value.
Chris@18 198 *
Chris@18 199 * @return $this
Chris@18 200 */
Chris@18 201 public function setDefaultValue($value) {
Chris@18 202 $this->definition['default_value'] = $this->normalizeValue($value, $this->getFieldStorageDefinition()->getMainPropertyName());
Chris@18 203 return $this;
Chris@18 204 }
Chris@18 205
Chris@18 206 /**
Chris@18 207 * {@inheritdoc}
Chris@18 208 */
Chris@18 209 public function getDefaultValue(FieldableEntityInterface $entity) {
Chris@18 210 // Allow custom default values function.
Chris@18 211 if ($callback = $this->getDefaultValueCallback()) {
Chris@18 212 $value = call_user_func($callback, $entity, $this);
Chris@18 213 }
Chris@18 214 else {
Chris@18 215 $value = $this->getDefaultValueLiteral();
Chris@18 216 }
Chris@18 217 $value = $this->normalizeValue($value, $this->getFieldStorageDefinition()->getMainPropertyName());
Chris@18 218 // Allow the field type to process default values.
Chris@18 219 $field_item_list_class = $this->getClass();
Chris@18 220 return $field_item_list_class::processDefaultValue($value, $entity, $this);
Chris@18 221 }
Chris@18 222
Chris@18 223 /**
Chris@18 224 * Sets whether the field is translatable.
Chris@18 225 *
Chris@18 226 * @param bool $translatable
Chris@18 227 * Whether the field is translatable.
Chris@18 228 *
Chris@18 229 * @return $this
Chris@18 230 */
Chris@18 231 public function setTranslatable($translatable) {
Chris@18 232 $this->definition['translatable'] = $translatable;
Chris@18 233 return $this;
Chris@18 234 }
Chris@18 235
Chris@18 236 /**
Chris@18 237 * {@inheritdoc}
Chris@18 238 */
Chris@18 239 public function isTranslatable() {
Chris@18 240 return !empty($this->definition['translatable']) && $this->getFieldStorageDefinition()->isTranslatable();
Chris@18 241 }
Chris@18 242
Chris@18 243 /**
Chris@18 244 * Set the field storage definition.
Chris@18 245 *
Chris@18 246 * @param \Drupal\Core\Field\FieldStorageDefinitionInterface $storageDefinition
Chris@18 247 * The field storage definition associated with this field definition.
Chris@18 248 *
Chris@18 249 * @return $this
Chris@18 250 */
Chris@18 251 public function setFieldStorageDefinition(FieldStorageDefinitionInterface $storageDefinition) {
Chris@18 252 $this->fieldStorageDefinition = $storageDefinition;
Chris@18 253 $this->itemDefinition = FieldItemDataDefinition::create($this);
Chris@18 254 // Create a definition for the items, and initialize it with the default
Chris@18 255 // settings for the field type.
Chris@18 256 $field_type_manager = \Drupal::service('plugin.manager.field.field_type');
Chris@18 257 $default_settings = $field_type_manager->getDefaultFieldSettings($storageDefinition->getType());
Chris@18 258 $this->itemDefinition->setSettings($default_settings);
Chris@18 259 return $this;
Chris@18 260 }
Chris@18 261
Chris@18 262 /**
Chris@18 263 * {@inheritdoc}
Chris@18 264 */
Chris@18 265 public function getFieldStorageDefinition() {
Chris@18 266 return $this->fieldStorageDefinition;
Chris@18 267 }
Chris@18 268
Chris@18 269 /**
Chris@18 270 * {@inheritdoc}
Chris@18 271 */
Chris@18 272 public function getConfig($bundle) {
Chris@18 273 // @todo provide a FieldDefinitionOverride config entity in
Chris@18 274 // https://www.drupal.org/project/drupal/issues/2935978.
Chris@18 275 throw new \Exception('Field definitions do not currently have an override config entity.');
Chris@18 276 }
Chris@18 277
Chris@18 278 /**
Chris@18 279 * {@inheritdoc}
Chris@18 280 */
Chris@18 281 public function getUniqueIdentifier() {
Chris@18 282 return $this->getTargetEntityTypeId() . '-' . $this->getTargetBundle() . '-' . $this->getName();
Chris@18 283 }
Chris@18 284
Chris@18 285 /**
Chris@18 286 * {@inheritdoc}
Chris@18 287 */
Chris@18 288 public function getSetting($setting_name) {
Chris@18 289 if (array_key_exists($setting_name, $this->itemDefinition->getSettings())) {
Chris@18 290 return $this->itemDefinition->getSetting($setting_name);
Chris@18 291 }
Chris@18 292 else {
Chris@18 293 return $this->getFieldStorageDefinition()->getSetting($setting_name);
Chris@18 294 }
Chris@18 295 }
Chris@18 296
Chris@18 297 /**
Chris@18 298 * {@inheritdoc}
Chris@18 299 */
Chris@18 300 public function getSettings() {
Chris@18 301 return $this->getItemDefinition()->getSettings() + $this->getFieldStorageDefinition()->getSettings();
Chris@18 302 }
Chris@18 303
Chris@18 304 /**
Chris@18 305 * {@inheritdoc}
Chris@18 306 */
Chris@18 307 public function setSetting($setting_name, $value) {
Chris@18 308 $this->getItemDefinition()->setSetting($setting_name, $value);
Chris@18 309 return $this;
Chris@18 310 }
Chris@18 311
Chris@18 312 /**
Chris@18 313 * {@inheritdoc}
Chris@18 314 */
Chris@18 315 public function setSettings(array $settings) {
Chris@18 316 // Assign settings individually, in order to keep the current values
Chris@18 317 // of settings not specified in $settings.
Chris@18 318 foreach ($settings as $setting_name => $setting) {
Chris@18 319 $this->getItemDefinition()->setSetting($setting_name, $setting);
Chris@18 320 }
Chris@18 321 return $this;
Chris@18 322 }
Chris@18 323
Chris@18 324 }