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

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 1fec387a4317
children
rev   line source
Chris@0 1 <?php
Chris@0 2
Chris@0 3 namespace Drupal\Core\Field;
Chris@0 4
Chris@0 5 use Drupal\Core\Cache\CacheableDependencyInterface;
Chris@0 6 use Drupal\Core\Entity\FieldableEntityInterface;
Chris@0 7 use Drupal\Core\TypedData\ListDataDefinitionInterface;
Chris@0 8
Chris@0 9 /**
Chris@0 10 * Defines an interface for entity field definitions.
Chris@0 11 *
Chris@0 12 * An entity field is a data object that holds the values of a particular field
Chris@0 13 * for a particular entity (see \Drupal\Core\Field\FieldItemListInterface). For
Chris@0 14 * example, $node_1->body and $node_2->body contain different data and therefore
Chris@0 15 * are different field objects.
Chris@0 16 *
Chris@0 17 * In contrast, an entity field *definition* is an object that returns
Chris@0 18 * information *about* a field (e.g., its type and settings) rather than its
Chris@0 19 * values. As such, if all the information about $node_1->body and $node_2->body
Chris@0 20 * is the same, then the same field definition object can be used to describe
Chris@0 21 * both.
Chris@0 22 *
Chris@0 23 * It is up to the class implementing this interface to manage where the
Chris@0 24 * information comes from. For example, field.module provides an implementation
Chris@0 25 * based on two levels of configuration. It allows the site administrator to add
Chris@0 26 * custom fields to any entity type and bundle via the "field_storage_config"
Chris@0 27 * and "field_config" configuration entities. The former for storing
Chris@0 28 * configuration that is independent of which entity type and bundle the field
Chris@0 29 * is added to, and the latter for storing configuration that is specific to the
Chris@0 30 * entity type and bundle. The class that implements "field_config"
Chris@0 31 * configuration entities also implements this interface, returning information
Chris@0 32 * from either itself, or from the corresponding "field_storage_config"
Chris@0 33 * configuration, as appropriate.
Chris@0 34 *
Chris@0 35 * However, entity base fields, such as $node->title, are not managed by
Chris@0 36 * field.module and its "field_storage_config"/"field_config"
Chris@0 37 * configuration entities. Therefore, their definitions are provided by
Chris@0 38 * different objects based on the class \Drupal\Core\Field\BaseFieldDefinition,
Chris@0 39 * which implements this interface as well.
Chris@0 40 *
Chris@0 41 * Field definitions may fully define a concrete data object (e.g.,
Chris@0 42 * $node_1->body), or may provide a best-guess definition for a data object that
Chris@0 43 * might come into existence later. For example, $node_1->body and $node_2->body
Chris@0 44 * may have different definitions (e.g., if the node types are different). When
Chris@0 45 * adding the "body" field to a View that can return nodes of different types,
Chris@0 46 * the View can get a field definition that represents the "body" field
Chris@0 47 * abstractly, and present Views configuration options to the administrator
Chris@0 48 * based on that abstract definition, even though that abstract definition can
Chris@0 49 * differ from the concrete definition of any particular node's body field.
Chris@0 50 */
Chris@0 51 interface FieldDefinitionInterface extends ListDataDefinitionInterface, CacheableDependencyInterface {
Chris@0 52
Chris@0 53 /**
Chris@0 54 * Returns the machine name of the field.
Chris@0 55 *
Chris@0 56 * This defines how the field data is accessed from the entity. For example,
Chris@0 57 * if the field name is "foo", then $entity->foo returns its data.
Chris@0 58 *
Chris@0 59 * @return string
Chris@0 60 * The field name.
Chris@0 61 */
Chris@0 62 public function getName();
Chris@0 63
Chris@0 64 /**
Chris@0 65 * Returns the field type.
Chris@0 66 *
Chris@0 67 * @return string
Chris@0 68 * The field type, i.e. the id of a field type plugin. For example 'text'.
Chris@0 69 *
Chris@0 70 * @see \Drupal\Core\Field\FieldTypePluginManagerInterface
Chris@0 71 */
Chris@0 72 public function getType();
Chris@0 73
Chris@0 74 /**
Chris@0 75 * Returns the ID of the entity type the field is attached to.
Chris@0 76 *
Chris@0 77 * This method should not be confused with EntityInterface::getEntityTypeId()
Chris@0 78 * (configurable fields are config entities, and thus implement both
Chris@0 79 * interfaces):
Chris@0 80 * - FieldDefinitionInterface::getTargetEntityTypeId() answers "as a field,
Chris@0 81 * which entity type are you attached to?".
Chris@0 82 * - EntityInterface::getEntityTypeId() answers "as a (config) entity, what
Chris@0 83 * is your own entity type?".
Chris@0 84 *
Chris@0 85 * @return string
Chris@0 86 * The entity type ID.
Chris@0 87 */
Chris@0 88 public function getTargetEntityTypeId();
Chris@0 89
Chris@0 90 /**
Chris@0 91 * Gets the bundle the field is attached to.
Chris@0 92 *
Chris@0 93 * This method should not be confused with EntityInterface::bundle()
Chris@0 94 * (configurable fields are config entities, and thus implement both
Chris@0 95 * interfaces):
Chris@0 96 * - FieldDefinitionInterface::getTargetBundle() answers "as a field,
Chris@0 97 * which bundle are you attached to?".
Chris@0 98 * - EntityInterface::bundle() answers "as a (config) entity, what
Chris@0 99 * is your own bundle?" (not relevant in our case, the config entity types
Chris@0 100 * used to store the definitions of configurable fields do not have
Chris@0 101 * bundles).
Chris@0 102 *
Chris@0 103 * @return string|null
Chris@0 104 * The bundle the field is defined for, or NULL if it is a base field; i.e.,
Chris@0 105 * it is not bundle-specific.
Chris@0 106 */
Chris@0 107 public function getTargetBundle();
Chris@0 108
Chris@0 109 /**
Chris@0 110 * Returns whether the display for the field can be configured.
Chris@0 111 *
Chris@0 112 * @param string $display_context
Chris@0 113 * The display context. Either 'view' or 'form'.
Chris@0 114 *
Chris@0 115 * @return bool
Chris@0 116 * TRUE if the display for this field is configurable in the given context.
Chris@0 117 * If TRUE, the display options returned by getDisplayOptions() may be
Chris@0 118 * overridden via the respective entity display.
Chris@0 119 *
Chris@0 120 * @see \Drupal\Core\Entity\Display\EntityDisplayInterface
Chris@0 121 */
Chris@0 122 public function isDisplayConfigurable($display_context);
Chris@0 123
Chris@0 124 /**
Chris@0 125 * Returns the default display options for the field.
Chris@0 126 *
Chris@0 127 * If the field's display is configurable, the returned display options act
Chris@0 128 * as default values and may be overridden via the respective entity display.
Chris@0 129 * Otherwise, the display options will be applied to entity displays as is.
Chris@0 130 *
Chris@0 131 * @param string $display_context
Chris@0 132 * The display context. Either 'view' or 'form'.
Chris@0 133 *
Chris@0 134 * @return array|null
Chris@0 135 * The array of display options for the field, or NULL if the field is not
Chris@0 136 * displayed. The following key/value pairs may be present:
Chris@0 137 * - label: (string) Position of the field label. The default 'field' theme
Chris@0 138 * implementation supports the values 'inline', 'above' and 'hidden'.
Chris@0 139 * Defaults to 'above'. Only applies to 'view' context.
Chris@0 140 * - region: (string) The region the field is in, or 'hidden'. If not
Chris@0 141 * specified, the default region will be used.
Chris@0 142 * - type: (string) The plugin (widget or formatter depending on
Chris@0 143 * $display_context) to use. If not specified or if the requested plugin
Chris@0 144 * is unknown, the 'default_widget' / 'default_formatter' for the field
Chris@0 145 * type will be used. Previously 'hidden' was a valid value, it is now
Chris@0 146 * deprecated in favor of specifying 'region' => 'hidden'.
Chris@0 147 * - settings: (array) Settings for the plugin specified above. The default
Chris@0 148 * settings for the plugin will be used for settings left unspecified.
Chris@0 149 * - third_party_settings: (array) Settings provided by other extensions
Chris@0 150 * through hook_field_formatter_third_party_settings_form().
Chris@0 151 * - weight: (float) The weight of the element. Not needed if 'type' is
Chris@0 152 * 'hidden'.
Chris@0 153 * The defaults of the various display options above get applied by the used
Chris@0 154 * entity display.
Chris@0 155 *
Chris@0 156 * @see \Drupal\Core\Entity\Display\EntityDisplayInterface
Chris@0 157 */
Chris@0 158 public function getDisplayOptions($display_context);
Chris@0 159
Chris@0 160 /**
Chris@0 161 * Returns whether the field can be empty.
Chris@0 162 *
Chris@0 163 * If a field is required, an entity needs to have at least a valid,
Chris@0 164 * non-empty item in that field's FieldItemList in order to pass validation.
Chris@0 165 *
Chris@0 166 * An item is considered empty if its isEmpty() method returns TRUE.
Chris@0 167 * Typically, that is if at least one of its required properties is empty.
Chris@0 168 *
Chris@0 169 * @return bool
Chris@0 170 * TRUE if the field is required.
Chris@0 171 *
Chris@0 172 * @see \Drupal\Core\TypedData\Plugin\DataType\ItemList::isEmpty()
Chris@0 173 * @see \Drupal\Core\Field\FieldItemInterface::isEmpty()
Chris@0 174 * @see \Drupal\Core\TypedData\DataDefinitionInterface:isRequired()
Chris@0 175 * @see \Drupal\Core\TypedData\TypedDataManager::getDefaultConstraints()
Chris@0 176 */
Chris@0 177 public function isRequired();
Chris@0 178
Chris@0 179 /**
Chris@0 180 * Returns the default value literal for the field.
Chris@0 181 *
Chris@0 182 * This method retrieves the raw property assigned to the field definition.
Chris@0 183 * When computing the runtime default value for a field in a given entity,
Chris@0 184 * ::getDefaultValue() should be used instead.
Chris@0 185 *
Chris@0 186 * @return array
Chris@0 187 * The default value for the field, as a numerically indexed array of items,
Chris@0 188 * each item being a property/value array (array() for no default value).
Chris@0 189 *
Chris@0 190 * @see FieldDefinitionInterface::getDefaultValue()
Chris@0 191 * @see FieldDefinitionInterface::getDefaultValueCallback()
Chris@0 192 */
Chris@0 193 public function getDefaultValueLiteral();
Chris@0 194
Chris@0 195 /**
Chris@0 196 * Returns the default value callback for the field.
Chris@0 197 *
Chris@0 198 * This method retrieves the raw property assigned to the field definition.
Chris@0 199 * When computing the runtime default value for a field in a given entity,
Chris@0 200 * ::getDefaultValue() should be used instead.
Chris@0 201 *
Chris@0 202 * @return string|null
Chris@0 203 * The default value callback for the field.
Chris@0 204 *
Chris@0 205 * @see FieldDefinitionInterface::getDefaultValue()
Chris@0 206 * @see FieldDefinitionInterface::getDefaultValueLiteral()
Chris@0 207 */
Chris@0 208 public function getDefaultValueCallback();
Chris@0 209
Chris@0 210 /**
Chris@0 211 * Returns the default value for the field in a newly created entity.
Chris@0 212 *
Chris@0 213 * This method computes the runtime default value for a field in a given
Chris@0 214 * entity. To access the raw properties assigned to the field definition,
Chris@0 215 * ::getDefaultValueLiteral() or ::getDefaultValueCallback() should be used
Chris@0 216 * instead.
Chris@0 217 *
Chris@0 218 * @param \Drupal\Core\Entity\FieldableEntityInterface $entity
Chris@0 219 * The entity for which the default value is generated.
Chris@0 220 *
Chris@0 221 * @return array
Chris@0 222 * The default value for the field, as a numerically indexed array of items,
Chris@0 223 * each item being a property/value array (array() for no default value).
Chris@0 224 *
Chris@0 225 * @see FieldDefinitionInterface::getDefaultValueLiteral()
Chris@0 226 * @see FieldDefinitionInterface::getDefaultValueCallback()
Chris@0 227 */
Chris@0 228 public function getDefaultValue(FieldableEntityInterface $entity);
Chris@0 229
Chris@0 230 /**
Chris@0 231 * Returns whether the field is translatable.
Chris@0 232 *
Chris@0 233 * @return bool
Chris@0 234 * TRUE if the field is translatable.
Chris@0 235 */
Chris@0 236 public function isTranslatable();
Chris@0 237
Chris@0 238 /**
Chris@0 239 * Returns the field storage definition.
Chris@0 240 *
Chris@0 241 * @return \Drupal\Core\Field\FieldStorageDefinitionInterface
Chris@0 242 * The field storage definition.
Chris@0 243 */
Chris@0 244 public function getFieldStorageDefinition();
Chris@0 245
Chris@0 246 /**
Chris@0 247 * Gets an object that can be saved in configuration.
Chris@0 248 *
Chris@0 249 * Base fields are defined in code. In order to configure field definition
Chris@0 250 * properties per bundle use this method to create an override that can be
Chris@0 251 * saved in configuration.
Chris@0 252 *
Chris@0 253 * @see \Drupal\Core\Field\Entity\BaseFieldBundleOverride
Chris@0 254 *
Chris@0 255 * @param string $bundle
Chris@0 256 * The bundle to get the configurable field for.
Chris@0 257 *
Chris@0 258 * @return \Drupal\Core\Field\FieldConfigInterface
Chris@0 259 */
Chris@0 260 public function getConfig($bundle);
Chris@0 261
Chris@14 262 /**
Chris@14 263 * Returns a unique identifier for the field.
Chris@14 264 *
Chris@14 265 * @return string
Chris@14 266 */
Chris@14 267 public function getUniqueIdentifier();
Chris@14 268
Chris@0 269 }