5 * Entity API for handling entities like nodes or users.
8 use Drupal\Core\Entity\EntityInterface;
9 use Drupal\Core\Entity\Entity\EntityFormDisplay;
10 use Drupal\Core\Entity\Entity\EntityViewDisplay;
13 * Clears the entity render cache for all entity types.
15 function entity_render_cache_clear() {
16 $entity_manager = Drupal::entityManager();
17 foreach ($entity_manager->getDefinitions() as $entity_type => $info) {
18 if ($entity_manager->hasHandler($entity_type, 'view_builder')) {
19 $entity_manager->getViewBuilder($entity_type)->resetCache();
25 * Returns the entity bundle info.
27 * @param string|null $entity_type
28 * The entity type whose bundle info should be returned, or NULL for all
29 * bundles info. Defaults to NULL.
32 * The bundle info for a specific entity type, or all entity types.
34 * @deprecated in Drupal 8.x-dev and will be removed before Drupal 9.0.0. Use
35 * \Drupal\Core\Entity\EntityTypeBundleInfoInterface::getBundleInfo() for a
37 * \Drupal\Core\Entity\EntityTypeBundleInfoInterface::getAllBundleInfo() for
40 * @see \Drupal\Core\Entity\EntityTypeBundleInfoInterface::getBundleInfo()
41 * @see \Drupal\Core\Entity\EntityTypeBundleInfoInterface::getAllBundleInfo()
43 function entity_get_bundles($entity_type = NULL) {
44 if (isset($entity_type)) {
45 return \Drupal::entityManager()->getBundleInfo($entity_type);
48 return \Drupal::entityManager()->getAllBundleInfo();
53 * Loads an entity from the database.
55 * @param string $entity_type
56 * The entity type to load, e.g. node or user.
58 * The id of the entity to load.
60 * Whether to reset the internal cache for the requested entity type.
62 * @return \Drupal\Core\Entity\EntityInterface|null
63 * The entity object, or NULL if there is no entity with the given ID.
65 * @deprecated in Drupal 8.0.x, will be removed before Drupal 9.0.0. Use
66 * The method overriding Entity::load() for the entity type, e.g.
67 * \Drupal\node\Entity\Node::load() if the entity type is known. If the
68 * entity type is variable, use the entity manager service to load the entity
69 * from the entity storage:
71 * \Drupal::entityTypeManager()->getStorage($entity_type)->load($id);
74 * @see \Drupal\Core\Entity\EntityInterface::load()
75 * @see \Drupal\Core\Entity\EntityTypeManagerInterface::getStorage()
76 * @see \Drupal\Core\Entity\EntityStorageInterface::load()
77 * @see \Drupal\Core\Entity\Sql\SqlContentEntityStorage
78 * @see \Drupal\Core\Entity\Query\QueryInterface
80 function entity_load($entity_type, $id, $reset = FALSE) {
81 $controller = \Drupal::entityManager()->getStorage($entity_type);
83 $controller->resetCache([$id]);
85 return $controller->load($id);
89 * Loads an entity from the database.
91 * @param string $entity_type
92 * The entity type to load, e.g. node or user.
93 * @param int $revision_id
94 * The id of the entity to load.
96 * @return \Drupal\Core\Entity\EntityInterface|null
97 * The entity object, or NULL if there is no entity with the given revision
100 * @deprecated as of Drupal 8.0.x, will be removed before Drupal 9.0.0. Use
101 * the entity storage's loadRevision() method to load a specific entity
104 * \Drupal::entityTypeManager()
105 * ->getStorage($entity_type)
106 * ->loadRevision($revision_id);
109 * @see \Drupal\Core\Entity\EntityTypeManagerInterface::getStorage()
110 * @see \Drupal\Core\Entity\EntityStorageInterface::loadRevision()
111 * @see \Drupal\Core\Entity\Sql\SqlContentEntityStorage
113 function entity_revision_load($entity_type, $revision_id) {
114 return \Drupal::entityManager()
115 ->getStorage($entity_type)
116 ->loadRevision($revision_id);
120 * Deletes an entity revision.
122 * @param string $entity_type
123 * The entity type to load, e.g. node or user.
124 * @param $revision_id
125 * The revision ID to delete.
127 * @deprecated as of Drupal 8.0.x, will be removed before Drupal 9.0.0. Use
128 * the entity storage's deleteRevision() method to delete a specific entity
131 * \Drupal::entityTypeManager()
132 * ->getStorage($entity_type)
133 * ->deleteRevision($revision_id);
136 * @see \Drupal\Core\Entity\EntityTypeManagerInterface::getStorage()
137 * @see \Drupal\Core\Entity\EntityStorageInterface::deleteRevision()
139 function entity_revision_delete($entity_type, $revision_id) {
140 \Drupal::entityManager()
141 ->getStorage($entity_type)
142 ->deleteRevision($revision_id);
146 * Loads multiple entities from the database.
148 * This function should be used whenever you need to load more than one entity
149 * from the database. The entities are loaded into memory and will not require
150 * database access if loaded again during the same page request.
152 * The actual loading is done through a class that has to implement the
153 * \Drupal\Core\Entity\EntityStorageInterface interface. By default,
154 * \Drupal\Core\Entity\Sql\SqlContentEntityStorage is used for content entities
155 * and Drupal\Core\Config\Entity\ConfigEntityStorage for config entities. Entity
156 * types can specify that a different class should be used by setting the
157 * "handlers['storage']" key in the entity plugin annotation. These classes
158 * can either implement the \Drupal\Core\Entity\EntityStorageInterface
159 * interface, or, most commonly, extend the
160 * \Drupal\Core\Entity\Sql\SqlContentEntityStorage class. See
161 * \Drupal\node\Entity\Node and \Drupal\node\NodeStorage for an example.
163 * @param string $entity_type
164 * The entity type to load, e.g. node or user.
166 * (optional) An array of entity IDs. If omitted, all entities are loaded.
168 * Whether to reset the internal cache for the requested entity type.
171 * An array of entity objects indexed by their IDs.
173 * @deprecated in Drupal 8.0.x, will be removed before Drupal 9.0.0. Use
174 * The method overriding Entity::loadMultiple() for the entity type, e.g.
175 * \Drupal\node\Entity\Node::loadMultiple() if the entity type is known. If
176 * the entity type is variable, use the entity manager service to load the
177 * entity from the entity storage:
179 * \Drupal::entityTypeManager()->getStorage($entity_type)->loadMultiple($id);
182 * @see \Drupal\Core\Entity\EntityInterface::loadMultiple()
183 * @see \Drupal\Core\Entity\EntityTypeManagerInterface::getStorage()
184 * @see \Drupal\Core\Entity\EntityStorageInterface::loadMultiple()
185 * @see \Drupal\Core\Entity\Sql\SqlContentEntityStorage
186 * @see \Drupal\Core\Entity\Query\QueryInterface
188 function entity_load_multiple($entity_type, array $ids = NULL, $reset = FALSE) {
189 $controller = \Drupal::entityManager()->getStorage($entity_type);
191 $controller->resetCache($ids);
193 return $controller->loadMultiple($ids);
197 * Load entities by their property values.
199 * @param string $entity_type
200 * The entity type to load, e.g. node or user.
201 * @param array $values
202 * An associative array where the keys are the property names and the
203 * values are the values those properties must have.
206 * An array of entity objects indexed by their IDs. Returns an empty array if
207 * no matching entities are found.
209 * @deprecated as of Drupal 8.0.x, will be removed before Drupal 9.0.0. Use
210 * the entity storage's loadByProperties() method to load an entity by their
213 * \Drupal::entityTypeManager()
214 * ->getStorage($entity_type)
215 * ->loadByProperties($values);
218 * @see \Drupal\Core\Entity\EntityTypeManagerInterface::getStorage()
219 * @see \Drupal\Core\Entity\EntityStorageInterface::loadByProperties()
221 function entity_load_multiple_by_properties($entity_type, array $values) {
222 return \Drupal::entityManager()
223 ->getStorage($entity_type)
224 ->loadByProperties($values);
228 * Loads the unchanged, i.e. not modified, entity from the database.
230 * Unlike entity_load() this function ensures the entity is directly loaded from
231 * the database, thus bypassing any static cache. In particular, this function
232 * is useful to determine changes by comparing the entity being saved to the
235 * @param $entity_type
236 * The entity type to load, e.g. node or user.
238 * The ID of the entity to load.
240 * @return \Drupal\Core\Entity\EntityInterface|null
241 * The unchanged entity, or FALSE if the entity cannot be loaded.
243 * @deprecated as of Drupal 8.0.x, will be removed before Drupal 9.0.0. Use
244 * the entity storage's loadUnchanged() method to load an unchanged entity:
246 * \Drupal::entityTypeManager()->getStorage($entity_type)->loadUnchanged($id);
249 * @see \Drupal\Core\Entity\EntityTypeManagerInterface::getStorage()
250 * @see \Drupal\Core\Entity\EntityStorageInterface::loadUnchanged()
252 function entity_load_unchanged($entity_type, $id) {
253 return \Drupal::entityManager()
254 ->getStorage($entity_type)
255 ->loadUnchanged($id);
259 * Deletes multiple entities permanently.
261 * @param string $entity_type
262 * The type of the entity.
264 * An array of entity IDs of the entities to delete.
266 * @deprecated as of Drupal 8.0.x, will be removed before Drupal 9.0.0. Use
267 * the entity storage's delete() method to delete multiple entities:
269 * $storage_handler = \Drupal::entityTypeManager()->getStorage($entity_type);
270 * $entities = $storage_handler->loadMultiple($ids);
271 * $storage_handler->delete($entities);
274 * @see \Drupal\Core\Entity\EntityTypeManagerInterface::getStorage()
275 * @see \Drupal\Core\Entity\EntityStorageInterface::loadMultiple()
276 * @see \Drupal\Core\Entity\EntityStorageInterface::delete()
278 function entity_delete_multiple($entity_type, array $ids) {
279 $controller = \Drupal::entityManager()->getStorage($entity_type);
280 $entities = $controller->loadMultiple($ids);
281 $controller->delete($entities);
285 * Constructs a new entity object, without permanently saving it.
287 * @param string $entity_type
288 * The type of the entity.
289 * @param array $values
290 * (optional) An array of values to set, keyed by property name. If the
291 * entity type has bundles, the bundle key has to be specified.
293 * @return \Drupal\Core\Entity\EntityInterface
294 * A new entity object.
296 * @deprecated in Drupal 8.0.x, will be removed before Drupal 9.0.0. Use
297 * The method overriding Entity::create() for the entity type, e.g.
298 * \Drupal\node\Entity\Node::create() if the entity type is known. If the
299 * entity type is variable, use the entity storage's create() method to
300 * construct a new entity:
302 * \Drupal::entityTypeManager()->getStorage($entity_type)->create($values);
305 * @see \Drupal\Core\Entity\EntityTypeManagerInterface::getStorage()
306 * @see \Drupal\Core\Entity\EntityStorageInterface::create()
308 function entity_create($entity_type, array $values = []) {
309 return \Drupal::entityManager()
310 ->getStorage($entity_type)
315 * Returns the label of an entity.
317 * @param \Drupal\Core\Entity\EntityInterface $entity
318 * The entity for which to generate the label.
320 * (optional) The language code of the language that should be used for
321 * getting the label. If set to NULL, the entity's default language is
324 * @return string|null
325 * The label of the entity, or NULL if there is no label defined.
327 * @deprecated as of Drupal 8.0.x, will be removed before Drupal 9.0.0. Use
328 * the entity's label() method to get the label of the entity:
330 * $entity->label($langcode);
333 * @see \Drupal\Core\Entity\EntityInterface::label()
335 function entity_page_label(EntityInterface $entity, $langcode = NULL) {
336 return $entity->label($langcode);
340 * Returns the render array for an entity.
342 * @param \Drupal\Core\Entity\EntityInterface $entity
343 * The entity to be rendered.
344 * @param string $view_mode
345 * The view mode that should be used to display the entity.
346 * @param string $langcode
347 * (optional) For which language the entity should be rendered, defaults to
348 * the current content language.
350 * (optional) Whether to reset the render cache for the requested entity.
354 * A render array for the entity.
356 * @deprecated as of Drupal 8.0.x, will be removed before Drupal 9.0.0.
357 * Use the entity view builder's view() method for creating a render array:
359 * $view_builder = \Drupal::entityTypeManager()
360 * ->getViewBuilder($entity->getEntityTypeId());
361 * return $view_builder->view($entity, $view_mode, $langcode);
364 * @see \Drupal\Core\Entity\EntityTypeManagerInterface::getViewBuilder()
365 * @see \Drupal\Core\Entity\EntityViewBuilderInterface::view()
367 function entity_view(EntityInterface $entity, $view_mode, $langcode = NULL, $reset = FALSE) {
368 $render_controller = \Drupal::entityManager()->getViewBuilder($entity->getEntityTypeId());
370 $render_controller->resetCache([$entity]);
372 return $render_controller->view($entity, $view_mode, $langcode);
376 * Returns the render array for the provided entities.
378 * @param \Drupal\Core\Entity\EntityInterface[] $entities
379 * The entities to be rendered, must be of the same type.
380 * @param string $view_mode
381 * The view mode that should be used to display the entity.
382 * @param string $langcode
383 * (optional) For which language the entity should be rendered, defaults to
384 * the current content language.
386 * (optional) Whether to reset the render cache for the requested entities.
390 * A render array for the entities, indexed by the same keys as the
391 * entities array passed in $entities.
393 * @deprecated as of Drupal 8.0.x, will be removed before Drupal 9.0.0.
394 * Use the entity view builder's viewMultiple() method for creating a render
395 * array for the provided entities:
397 * $view_builder = \Drupal::entityTypeManager()
398 * ->getViewBuilder($entity->getEntityTypeId());
399 * return $view_builder->viewMultiple($entities, $view_mode, $langcode);
402 * @see \Drupal\Core\Entity\EntityTypeManagerInterface::getViewBuilder()
403 * @see \Drupal\Core\Entity\EntityViewBuilderInterface::viewMultiple()
405 function entity_view_multiple(array $entities, $view_mode, $langcode = NULL, $reset = FALSE) {
406 $render_controller = \Drupal::entityManager()->getViewBuilder(reset($entities)->getEntityTypeId());
408 $render_controller->resetCache($entities);
410 return $render_controller->viewMultiple($entities, $view_mode, $langcode);
414 * Returns the entity view display associated with a bundle and view mode.
416 * Use this function when assigning suggested display options for a component
417 * in a given view mode. Note that they will only be actually used at render
418 * time if the view mode itself is configured to use dedicated display settings
419 * for the bundle; if not, the 'default' display is used instead.
421 * The function reads the entity view display from the current configuration, or
422 * returns a ready-to-use empty one if configuration entry exists yet for this
423 * bundle and view mode. This streamlines manipulation of display objects by
424 * always returning a consistent object that reflects the current state of the
428 * - Set the 'body' field to be displayed and the 'field_image' field to be
429 * hidden on article nodes in the 'default' display.
431 * entity_get_display('node', 'article', 'default')
432 * ->setComponent('body', array(
433 * 'type' => 'text_summary_or_trimmed',
434 * 'settings' => array('trim_length' => '200')
437 * ->removeComponent('field_image')
441 * @param string $entity_type
443 * @param string $bundle
445 * @param string $view_mode
446 * The view mode, or 'default' to retrieve the 'default' display object for
449 * @return \Drupal\Core\Entity\Display\EntityViewDisplayInterface
450 * The entity view display associated with the view mode.
452 * @deprecated as of Drupal 8.0.x, will be removed before Drupal 9.0.0.
453 * If the display is available in configuration use:
455 * \Drupal::entityTypeManager()
456 * ->getStorage('entity_view_display')
457 * ->load($entity_type . '.' . $bundle . '.' . $view_mode);
459 * When the display is not available in configuration, you can create a new
460 * EntityViewDisplay object using:
463 * 'targetEntityType' => $entity_type,
464 * 'bundle' => $bundle,
465 * 'mode' => $view_mode,
468 * \Drupal::entityTypeManager()
469 * ->getStorage('entity_view_display')
473 * @see \Drupal\Core\Entity\EntityStorageInterface::create()
474 * @see \Drupal\Core\Entity\EntityStorageInterface::load()
476 function entity_get_display($entity_type, $bundle, $view_mode) {
477 // Try loading the display from configuration.
478 $display = EntityViewDisplay::load($entity_type . '.' . $bundle . '.' . $view_mode);
480 // If not found, create a fresh display object. We do not preemptively create
481 // new entity_view_display configuration entries for each existing entity type
482 // and bundle whenever a new view mode becomes available. Instead,
483 // configuration entries are only created when a display object is explicitly
484 // configured and saved.
486 $display = EntityViewDisplay::create([
487 'targetEntityType' => $entity_type,
489 'mode' => $view_mode,
498 * Returns the entity form display associated with a bundle and form mode.
500 * The function reads the entity form display object from the current
501 * configuration, or returns a ready-to-use empty one if no configuration entry
502 * exists yet for this bundle and form mode. This streamlines manipulation of
503 * entity form displays by always returning a consistent object that reflects
504 * the current state of the configuration.
507 * - Set the 'body' field to be displayed with the 'text_textarea_with_summary'
508 * widget and the 'field_image' field to be hidden on article nodes in the
509 * 'default' form mode.
511 * entity_get_form_display('node', 'article', 'default')
512 * ->setComponent('body', array(
513 * 'type' => 'text_textarea_with_summary',
516 * ->setComponent('field_image', array(
517 * 'region' => 'hidden',
522 * @param string $entity_type
524 * @param string $bundle
526 * @param string $form_mode
529 * @return \Drupal\Core\Entity\Display\EntityFormDisplayInterface
530 * The entity form display associated with the given form mode.
532 * @deprecated as of Drupal 8.0.x, will be removed before Drupal 9.0.0.
533 * If the entity form display is available in configuration use:
535 * \Drupal::entityTypeManager()
536 * ->getStorage('entity_form_display')
537 * ->load($entity_type . '.' . $bundle . '.' . $form_mode);
539 * When the entity form display is not available in configuration, you can
540 * create a new EntityFormDisplay object using:
543 * 'targetEntityType' => $entity_type,
544 * 'bundle' => $bundle,
545 * 'mode' => $form_mode,
548 * \Drupal::entityTypeManager()
549 * ->getStorage('entity_form_display')
553 * @see \Drupal\Core\Entity\EntityStorageInterface::create()
554 * @see \Drupal\Core\Entity\EntityStorageInterface::load()
556 function entity_get_form_display($entity_type, $bundle, $form_mode) {
557 // Try loading the entity from configuration.
558 $entity_form_display = EntityFormDisplay::load($entity_type . '.' . $bundle . '.' . $form_mode);
560 // If not found, create a fresh entity object. We do not preemptively create
561 // new entity form display configuration entries for each existing entity type
562 // and bundle whenever a new form mode becomes available. Instead,
563 // configuration entries are only created when an entity form display is
564 // explicitly configured and saved.
565 if (!$entity_form_display) {
566 $entity_form_display = EntityFormDisplay::create([
567 'targetEntityType' => $entity_type,
569 'mode' => $form_mode,
574 return $entity_form_display;