EntityManagerInterface.php 17.3 KB
Newer Older
1 2 3 4 5 6 7 8 9
<?php

/**
 * @file
 * Contains \Drupal\Core\Entity\EntityManagerInterface.
 */

namespace Drupal\Core\Entity;

10
use Drupal\Component\Plugin\Discovery\CachedDiscoveryInterface;
11
use Drupal\Component\Plugin\PluginManagerInterface;
12
use Drupal\Core\Field\FieldDefinitionListenerInterface;
13
use Drupal\Core\Field\FieldStorageDefinitionListenerInterface;
14 15 16 17

/**
 * Provides an interface for entity type managers.
 */
18
interface EntityManagerInterface extends PluginManagerInterface, EntityTypeListenerInterface, EntityBundleListenerInterface, FieldStorageDefinitionListenerInterface, FieldDefinitionListenerInterface, CachedDiscoveryInterface {
19 20 21 22

  /**
   * Builds a list of entity type labels suitable for a Form API options list.
   *
23 24 25 26
   * @param bool $group
   *   (optional) Whether to group entity types by plugin group (e.g. 'content',
   *   'config'). Defaults to FALSE.
   *
27 28 29
   * @return array
   *   An array of entity type labels, keyed by entity type name.
   */
30
  public function getEntityTypeLabels($group = FALSE);
31 32

  /**
33
   * Gets the base field definitions for a content entity type.
34
   *
35 36 37
   * Only fields that are not specific to a given bundle or set of bundles are
   * returned. This excludes configurable fields, as they are always attached
   * to a specific bundle.
38
   *
39
   * @param string $entity_type_id
40
   *   The entity type ID. Only entity types that implement
41
   *   \Drupal\Core\Entity\FieldableEntityInterface are supported.
42
   *
43
   * @return \Drupal\Core\Field\FieldDefinitionInterface[]
44 45 46 47 48 49 50 51 52 53
   *   The array of base field definitions for the entity type, keyed by field
   *   name.
   *
   * @throws \LogicException
   *   Thrown if one of the entity keys is flagged as translatable.
   */
  public function getBaseFieldDefinitions($entity_type_id);

  /**
   * Gets the field definitions for a specific bundle.
54
   *
55 56
   * @param string $entity_type_id
   *   The entity type ID. Only entity types that implement
57
   *   \Drupal\Core\Entity\FieldableEntityInterface are supported.
58 59 60 61 62
   * @param string $bundle
   *   The bundle.
   *
   * @return \Drupal\Core\Field\FieldDefinitionInterface[]
   *   The array of field definitions for the bundle, keyed by field name.
63
   */
64
  public function getFieldDefinitions($entity_type_id, $bundle);
65

66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85
  /**
   * Gets the field storage definitions for a content entity type.
   *
   * This returns all field storage definitions for base fields and bundle
   * fields of an entity type. Note that field storage definitions of a base
   * field equal the full base field definition (i.e. they implement
   * FieldDefinitionInterface), while the storage definitions for bundle fields
   * may implement FieldStorageDefinitionInterface only.
   *
   * @param string $entity_type_id
   *   The entity type ID. Only content entities are supported.
   *
   * @return \Drupal\Core\Field\FieldStorageDefinitionInterface[]
   *   The array of field storage definitions for the entity type, keyed by
   *   field name.
   *
   * @see \Drupal\Core\Field\FieldStorageDefinitionInterface
   */
  public function getFieldStorageDefinitions($entity_type_id);

86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120
  /**
   * Gets the entity type's most recently installed field storage definitions.
   *
   * During the application lifetime, field storage definitions can change. For
   * example, updated code can be deployed. The getFieldStorageDefinitions()
   * method will always return the definitions as determined by the current
   * codebase. This method, however, returns what the definitions were when the
   * last time that one of the
   * \Drupal\Core\Field\FieldStorageDefinitionListenerInterface events was last
   * fired and completed successfully. In other words, the definitions that
   * the entity type's handlers have incorporated into the application state.
   * For example, if the entity type's storage handler is SQL-based, the
   * definitions for which database tables were created.
   *
   * Application management code can check if getFieldStorageDefinitions()
   * differs from getLastInstalledFieldStorageDefinitions() and decide whether
   * to:
   * - Invoke the appropriate
   *   \Drupal\Core\Field\FieldStorageDefinitionListenerInterface
   *   events so that handlers react to the new definitions.
   * - Raise a warning that the application state is incompatible with the
   *   codebase.
   * - Perform some other action.
   *
   * @param string $entity_type_id
   *   The entity type ID.
   *
   * @return \Drupal\Core\Field\FieldStorageDefinitionInterface[]
   *   The array of installed field storage definitions for the entity type,
   *   keyed by field name.
   *
   * @see \Drupal\Core\Entity\EntityTypeListenerInterface
   */
  public function getLastInstalledFieldStorageDefinitions($entity_type_id);

121
  /**
122
   * Gets a lightweight map of fields across bundles.
123 124 125 126 127 128 129 130 131
   *
   * @return array
   *   An array keyed by entity type. Each value is an array which keys are
   *   field names and value is an array with two entries:
   *   - type: The field type.
   *   - bundles: The bundles in which the field appears.
   */
  public function getFieldMap();

132
  /**
133
   * Gets a lightweight map of fields across bundles filtered by field type.
134 135 136 137 138 139 140 141 142 143 144 145
   *
   * @param string $field_type
   *   The field type to filter by.
   *
   * @return array
   *   An array keyed by entity type. Each value is an array which keys are
   *   field names and value is an array with two entries:
   *   - type: The field type.
   *   - bundles: The bundles in which the field appears.
   */
  public function getFieldMapByFieldType($field_type);

146
  /**
147
   * Creates a new access control handler instance.
148 149
   *
   * @param string $entity_type
150
   *   The entity type for this access control handler.
151
   *
152 153
   * @return \Drupal\Core\Entity\EntityAccessControlHandlerInterface.
   *   A access control handler instance.
154
   */
155
  public function getAccessControlHandler($entity_type);
156 157

  /**
158
   * Creates a new storage instance.
159 160
   *
   * @param string $entity_type
161
   *   The entity type for this storage.
162
   *
163 164
   * @return \Drupal\Core\Entity\EntityStorageInterface
   *   A storage instance.
165 166
   *
   * @throws \Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException
167
   */
168
  public function getStorage($entity_type);
169 170 171 172 173 174 175 176 177 178 179 180 181 182

  /**
   * Get the bundle info of all entity types.
   *
   * @return array
   *   An array of all bundle information.
   */
  public function getAllBundleInfo();

  /**
   * {@inheritdoc}
   */
  public function clearCachedDefinitions();

183 184 185 186 187 188 189 190 191 192
  /**
   * Clears static and persistent field definition caches.
   */
  public function clearCachedFieldDefinitions();

  /**
   * Clears static and persistent bundles.
   */
  public function clearCachedBundles();

193 194 195 196 197 198 199
  /**
   * Creates a new view builder instance.
   *
   * @param string $entity_type
   *   The entity type for this view builder.
   *
   * @return \Drupal\Core\Entity\EntityViewBuilderInterface.
200
   *   A view builder instance.
201 202 203 204
   */
  public function getViewBuilder($entity_type);

  /**
205
   * Creates a new entity list builder.
206 207
   *
   * @param string $entity_type
208
   *   The entity type for this list builder.
209
   *
210 211
   * @return \Drupal\Core\Entity\EntityListBuilderInterface
   *   An entity list builder instance.
212
   */
213
  public function getListBuilder($entity_type);
214 215

  /**
216
   * Creates a new form instance.
217 218
   *
   * @param string $entity_type
219
   *   The entity type for this form.
220 221 222
   * @param string $operation
   *   The name of the operation to use, e.g., 'default'.
   *
223 224
   * @return \Drupal\Core\Entity\EntityFormInterface
   *   A form instance.
225
   */
226
  public function getFormObject($entity_type, $operation);
227

228 229 230 231 232 233 234 235 236 237
  /**
   * Gets all route provider instances.
   *
   * @param string $entity_type
   *   The entity type for this route providers.
   *
   * @return \Drupal\Core\Entity\Routing\EntityRouteProviderInterface[]
   */
  public function getRouteProviders($entity_type);

238
  /**
239
   * Checks whether a certain entity type has a certain handler.
240 241 242
   *
   * @param string $entity_type
   *   The name of the entity type.
243 244
   * @param string $handler_type
   *   The name of the handler.
245 246
   *
   * @return bool
247
   *   Returns TRUE if the entity type has the handler, else FALSE.
248
   */
249
  public function hasHandler($entity_type, $handler_type);
250

251
  /**
252
   * Creates a new handler instance for a entity type and handler type.
253 254 255
   *
   * @param string $entity_type
   *   The entity type for this controller.
256
   * @param string $handler_type
257 258
   *   The controller type to create an instance for.
   *
259
   * @return object
260
   *   A handler instance.
261 262 263
   *
   * @throws \Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException
   */
264
  public function getHandler($entity_type, $handler_type);
265

266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282
  /**
   * Creates new handler instance.
   *
   * Usually \Drupal\Core\Entity\EntityManagerInterface::getHandler() is
   * preferred since that method has additional checking that the class exists
   * and has static caches.
   *
   * @param mixed $class
   *   The handler class to instantiate.
   * @param \Drupal\Core\Entity\EntityTypeInterface $definition
   *   The entity type definition.
   *
   * @return object
   *   A handler instance.
   */
  public function createHandlerInstance($class, EntityTypeInterface $definition = null);

283
  /**
284
   * Gets the bundle info of an entity type.
285 286 287 288 289 290 291 292 293
   *
   * @param string $entity_type
   *   The entity type.
   *
   * @return array
   *   Returns the bundle information for the specified entity type.
   */
  public function getBundleInfo($entity_type);

294
  /**
295
   * Gets the "extra fields" for a bundle.
296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322
   *
   * @param string $entity_type_id
   *   The entity type ID.
   * @param string $bundle
   *   The bundle name.
   *
   * @return array
   *   A nested array of 'pseudo-field' elements. Each list is nested within the
   *   following keys: entity type, bundle name, context (either 'form' or
   *   'display'). The keys are the name of the elements as appearing in the
   *   renderable array (either the entity form or the displayed entity). The
   *   value is an associative array:
   *   - label: The human readable name of the element. Make sure you sanitize
   *     this appropriately.
   *   - description: A short description of the element contents.
   *   - weight: The default weight of the element.
   *   - visible: (optional) The default visibility of the element. Defaults to
   *     TRUE.
   *   - edit: (optional) String containing markup (normally a link) used as the
   *     element's 'edit' operation in the administration interface. Only for
   *     'form' context.
   *   - delete: (optional) String containing markup (normally a link) used as the
   *     element's 'delete' operation in the administration interface. Only for
   *     'form' context.
   */
  public function getExtraFields($entity_type_id, $bundle);

323
  /**
324
   * Gets the entity translation to be used in the given context.
325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341
   *
   * This will check whether a translation for the desired language is available
   * and if not, it will fall back to the most appropriate translation based on
   * the provided context.
   *
   * @param \Drupal\Core\Entity\EntityInterface $entity
   *   The entity whose translation will be returned.
   * @param string $langcode
   *   (optional) The language of the current context. Defaults to the current
   *   content language.
   * @param array $context
   *   (optional) An associative array of arbitrary data that can be useful to
   *   determine the proper fallback sequence.
   *
   * @return \Drupal\Core\Entity\EntityInterface
   *   An entity object for the translated data.
   *
342
   * @see \Drupal\Core\Language\LanguageManagerInterface::getFallbackCandidates()
343 344 345
   */
  public function getTranslationFromContext(EntityInterface $entity, $langcode = NULL, $context = array());

346
  /**
347
   * {@inheritdoc}
348 349 350
   *
   * @return \Drupal\Core\Entity\EntityTypeInterface|null
   */
351
  public function getDefinition($entity_type_id, $exception_on_invalid = TRUE);
352

353
  /**
354
   * Gets the entity type definition in its most recently installed state.
355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384
   *
   * During the application lifetime, entity type definitions can change. For
   * example, updated code can be deployed. The getDefinition() method will
   * always return the definition as determined by the current codebase. This
   * method, however, returns what the definition was when the last time that
   * one of the \Drupal\Core\Entity\EntityTypeListenerInterface events was last
   * fired and completed successfully. In other words, the definition that
   * the entity type's handlers have incorporated into the application state.
   * For example, if the entity type's storage handler is SQL-based, the
   * definition for which database tables were created.
   *
   * Application management code can check if getDefinition() differs from
   * getLastInstalledDefinition() and decide whether to:
   * - Invoke the appropriate \Drupal\Core\Entity\EntityTypeListenerInterface
   *   event so that handlers react to the new definition.
   * - Raise a warning that the application state is incompatible with the
   *   codebase.
   * - Perform some other action.
   *
   * @param string $entity_type_id
   *   The entity type ID.
   *
   * @return \Drupal\Core\Entity\EntityTypeInterface|null
   *   The installed entity type definition, or NULL if the entity type has
   *   not yet been installed via onEntityTypeCreate().
   *
   * @see \Drupal\Core\Entity\EntityTypeListenerInterface
   */
  public function getLastInstalledDefinition($entity_type_id);

385
  /**
386
   * {@inheritdoc}
387 388 389 390 391
   *
   * @return \Drupal\Core\Entity\EntityTypeInterface[]
   */
  public function getDefinitions();

392
  /**
393
   * Gets the entity view mode info for all entity types.
394 395 396 397 398 399 400
   *
   * @return array
   *   The view mode info for all entity types.
   */
  public function getAllViewModes();

  /**
401
   * Gets the entity view mode info for a specific entity type.
402 403 404 405 406 407 408 409 410 411
   *
   * @param string $entity_type_id
   *   The entity type whose view mode info should be returned.
   *
   * @return array
   *   The view mode info for a specific entity type.
   */
  public function getViewModes($entity_type_id);

  /**
412
   * Gets the entity form mode info for all entity types.
413 414 415 416 417 418 419
   *
   * @return array
   *   The form mode info for all entity types.
   */
  public function getAllFormModes();

  /**
420
   * Gets the entity form mode info for a specific entity type.
421 422 423 424 425 426 427 428 429 430
   *
   * @param string $entity_type_id
   *   The entity type whose form mode info should be returned.
   *
   * @return array
   *   The form mode info for a specific entity type.
   */
  public function getFormModes($entity_type_id);

  /**
431
   * Gets an array of view mode options.
432 433 434 435 436 437 438 439 440 441 442 443
   *
   * @param string $entity_type_id
   *   The entity type whose view mode options should be returned.
   * @param bool $include_disabled
   *   Force to include disabled view modes. Defaults to FALSE.
   *
   * @return array
   *   An array of view mode labels, keyed by the display mode ID.
   */
  public function getViewModeOptions($entity_type_id, $include_disabled = FALSE);

  /**
444
   * Gets an array of form mode options.
445 446 447 448 449 450 451 452 453 454 455
   *
   * @param string $entity_type_id
   *   The entity type whose form mode options should be returned.
   * @param bool $include_disabled
   *   Force to include disabled form modes. Defaults to FALSE.
   *
   * @return array
   *   An array of form mode labels, keyed by the display mode ID.
   */
  public function getFormModeOptions($entity_type_id, $include_disabled = FALSE);

456 457 458 459 460 461 462 463 464 465
  /**
   * Loads an entity by UUID.
   *
   * Note that some entity types may not support UUIDs.
   *
   * @param string $entity_type_id
   *   The entity type ID to load from.
   * @param string $uuid
   *   The UUID of the entity to load.
   *
466 467
   * @return \Drupal\Core\Entity\EntityInterface|null
   *   The entity object, or NULL if there is no entity with the given UUID.
468 469 470 471 472 473
   *
   * @throws \Drupal\Core\Entity\EntityStorageException
   *   Thrown in case the requested entity type does not support UUIDs.
   */
  public function loadEntityByUuid($entity_type_id, $uuid);

474 475 476 477 478 479 480 481 482
  /**
   * Loads an entity by the config target identifier.
   *
   * @param string $entity_type_id
   *   The entity type ID to load from.
   * @param string $target
   *   The configuration target to load, as returned from
   *   \Drupal\Core\Entity\EntityInterface::getConfigTarget().
   *
483 484 485
   * @return \Drupal\Core\Entity\EntityInterface|null
   *   The entity object, or NULL if there is no entity with the given config
   *   target identifier.
486 487 488 489 490 491 492 493 494
   *
   * @throws \Drupal\Core\Entity\EntityStorageException
   *   Thrown if the target identifier is a UUID but the entity type does not
   *   support UUIDs.
   *
   * @see \Drupal\Core\Entity\EntityInterface::getConfigTarget()
   */
  public function loadEntityByConfigTarget($entity_type_id, $target);

495
  /**
496
   * Gets the entity type ID based on the class that is called on.
497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517
   *
   * Compares the class this is called on against the known entity classes
   * and returns the entity type ID of a direct match or a subclass as fallback,
   * to support entity type definitions that were altered.
   *
   * @param string $class_name
   *   Class name to use for searching the entity type ID.
   *
   * @return string
   *   The entity type ID.
   *
   * @throws \Drupal\Core\Entity\Exception\AmbiguousEntityClassException
   *   Thrown when multiple subclasses correspond to the called class.
   * @throws \Drupal\Core\Entity\Exception\NoCorrespondingEntityClassException
   *   Thrown when no entity class corresponds to the called class.
   *
   * @see \Drupal\Core\Entity\Entity::load()
   * @see \Drupal\Core\Entity\Entity::loadMultiple()
   */
  public function getEntityTypeFromClass($class_name);

518
}