www.aleph1.co.uk Git - yaffs-website/blob - web/core/includes/entity.inc

   1 <?php
   2
   3 /**
   4  * @file
   5  * Entity API for handling entities like nodes or users.
   6  */
   7
   8 use Drupal\Core\Entity\EntityInterface;
   9 use Drupal\Core\Entity\Entity\EntityFormDisplay;
  10 use Drupal\Core\Entity\Entity\EntityViewDisplay;
  11
  12 /**
  13  * Clears the entity render cache for all entity types.
  14  */
  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();
  20     }
  21   }
  22 }
  23
  24 /**
  25  * Returns the entity bundle info.
  26  *
  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.
  30  *
  31  * @return array
  32  *   The bundle info for a specific entity type, or all entity types.
  33  *
  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
  36  *   single bundle, or
  37  *   \Drupal\Core\Entity\EntityTypeBundleInfoInterface::getAllBundleInfo() for
  38  *   all bundles.
  39  *
  40  * @see \Drupal\Core\Entity\EntityTypeBundleInfoInterface::getBundleInfo()
  41  * @see \Drupal\Core\Entity\EntityTypeBundleInfoInterface::getAllBundleInfo()
  42  */
  43 function entity_get_bundles($entity_type = NULL) {
  44   if (isset($entity_type)) {
  45     return \Drupal::entityManager()->getBundleInfo($entity_type);
  46   }
  47   else {
  48     return \Drupal::entityManager()->getAllBundleInfo();
  49   }
  50 }
  51
  52 /**
  53  * Loads an entity from the database.
  54  *
  55  * @param string $entity_type
  56  *   The entity type to load, e.g. node or user.
  57  * @param mixed $id
  58  *   The id of the entity to load.
  59  * @param bool $reset
  60  *   Whether to reset the internal cache for the requested entity type.
  61  *
  62  * @return \Drupal\Core\Entity\EntityInterface|null
  63  *   The entity object, or NULL if there is no entity with the given ID.
  64  *
  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:
  70  * @code
  71  * \Drupal::entityTypeManager()->getStorage($entity_type)->load($id);
  72  * @endcode
  73  *
  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
  79  */
  80 function entity_load($entity_type, $id, $reset = FALSE) {
  81   $controller = \Drupal::entityManager()->getStorage($entity_type);
  82   if ($reset) {
  83     $controller->resetCache([$id]);
  84   }
  85   return $controller->load($id);
  86 }
  87
  88 /**
  89  * Loads an entity from the database.
  90  *
  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.
  95  *
  96  * @return \Drupal\Core\Entity\EntityInterface|null
  97  *   The entity object, or NULL if there is no entity with the given revision
  98  *   id.
  99  *
 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
 102  *   revision:
 103  * @code
 104  * \Drupal::entityTypeManager()
 105  *   ->getStorage($entity_type)
 106  *   ->loadRevision($revision_id);
 107  * @endcode
 108  *
 109  * @see \Drupal\Core\Entity\EntityTypeManagerInterface::getStorage()
 110  * @see \Drupal\Core\Entity\EntityStorageInterface::loadRevision()
 111  * @see \Drupal\Core\Entity\Sql\SqlContentEntityStorage
 112  */
 113 function entity_revision_load($entity_type, $revision_id) {
 114   return \Drupal::entityManager()
 115     ->getStorage($entity_type)
 116     ->loadRevision($revision_id);
 117 }
 118
 119 /**
 120  * Deletes an entity revision.
 121  *
 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.
 126  *
 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
 129  *   revision:
 130  * @code
 131  * \Drupal::entityTypeManager()
 132  *   ->getStorage($entity_type)
 133  *   ->deleteRevision($revision_id);
 134  * @endcode
 135  *
 136  * @see \Drupal\Core\Entity\EntityTypeManagerInterface::getStorage()
 137  * @see \Drupal\Core\Entity\EntityStorageInterface::deleteRevision()
 138  */
 139 function entity_revision_delete($entity_type, $revision_id) {
 140   \Drupal::entityManager()
 141     ->getStorage($entity_type)
 142     ->deleteRevision($revision_id);
 143 }
 144
 145 /**
 146  * Loads multiple entities from the database.
 147  *
 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.
 151  *
 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.
 162  *
 163  * @param string $entity_type
 164  *   The entity type to load, e.g. node or user.
 165  * @param array $ids
 166  *   (optional) An array of entity IDs. If omitted, all entities are loaded.
 167  * @param bool $reset
 168  *   Whether to reset the internal cache for the requested entity type.
 169  *
 170  * @return array
 171  *   An array of entity objects indexed by their IDs.
 172  *
 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:
 178  * @code
 179  * \Drupal::entityTypeManager()->getStorage($entity_type)->loadMultiple($id);
 180  * @endcode
 181  *
 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
 187  */
 188 function entity_load_multiple($entity_type, array $ids = NULL, $reset = FALSE) {
 189   $controller = \Drupal::entityManager()->getStorage($entity_type);
 190   if ($reset) {
 191     $controller->resetCache($ids);
 192   }
 193   return $controller->loadMultiple($ids);
 194 }
 195
 196 /**
 197  * Load entities by their property values.
 198  *
 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.
 204  *
 205  * @return array
 206  *   An array of entity objects indexed by their IDs. Returns an empty array if
 207  *   no matching entities are found.
 208  *
 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
 211  *   property values:
 212  * @code
 213  * \Drupal::entityTypeManager()
 214  *   ->getStorage($entity_type)
 215  *   ->loadByProperties($values);
 216  * @endcode
 217  *
 218  * @see \Drupal\Core\Entity\EntityTypeManagerInterface::getStorage()
 219  * @see \Drupal\Core\Entity\EntityStorageInterface::loadByProperties()
 220  */
 221 function entity_load_multiple_by_properties($entity_type, array $values) {
 222   return \Drupal::entityManager()
 223     ->getStorage($entity_type)
 224     ->loadByProperties($values);
 225 }
 226
 227 /**
 228  * Loads the unchanged, i.e. not modified, entity from the database.
 229  *
 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
 233  * stored entity.
 234  *
 235  * @param $entity_type
 236  *   The entity type to load, e.g. node or user.
 237  * @param $id
 238  *   The ID of the entity to load.
 239  *
 240  * @return \Drupal\Core\Entity\EntityInterface|null
 241  *   The unchanged entity, or FALSE if the entity cannot be loaded.
 242  *
 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:
 245  * @code
 246  * \Drupal::entityTypeManager()->getStorage($entity_type)->loadUnchanged($id);
 247  * @endcode
 248  *
 249  * @see \Drupal\Core\Entity\EntityTypeManagerInterface::getStorage()
 250  * @see \Drupal\Core\Entity\EntityStorageInterface::loadUnchanged()
 251  */
 252 function entity_load_unchanged($entity_type, $id) {
 253   return \Drupal::entityManager()
 254     ->getStorage($entity_type)
 255     ->loadUnchanged($id);
 256 }
 257
 258 /**
 259  * Deletes multiple entities permanently.
 260  *
 261  * @param string $entity_type
 262  *   The type of the entity.
 263  * @param array $ids
 264  *   An array of entity IDs of the entities to delete.
 265  *
 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:
 268  * @code
 269  * $storage_handler = \Drupal::entityTypeManager()->getStorage($entity_type);
 270  * $entities = $storage_handler->loadMultiple($ids);
 271  * $storage_handler->delete($entities);
 272  * @endcode
 273  *
 274  * @see \Drupal\Core\Entity\EntityTypeManagerInterface::getStorage()
 275  * @see \Drupal\Core\Entity\EntityStorageInterface::loadMultiple()
 276  * @see \Drupal\Core\Entity\EntityStorageInterface::delete()
 277  */
 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);
 282 }
 283
 284 /**
 285  * Constructs a new entity object, without permanently saving it.
 286  *
 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.
 292  *
 293  * @return \Drupal\Core\Entity\EntityInterface
 294  *   A new entity object.
 295  *
 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:
 301  * @code
 302  * \Drupal::entityTypeManager()->getStorage($entity_type)->create($values);
 303  * @endcode
 304  *
 305  * @see \Drupal\Core\Entity\EntityTypeManagerInterface::getStorage()
 306  * @see \Drupal\Core\Entity\EntityStorageInterface::create()
 307  */
 308 function entity_create($entity_type, array $values = []) {
 309   return \Drupal::entityManager()
 310     ->getStorage($entity_type)
 311     ->create($values);
 312 }
 313
 314 /**
 315  * Returns the label of an entity.
 316  *
 317  * @param \Drupal\Core\Entity\EntityInterface $entity
 318  *   The entity for which to generate the label.
 319  * @param $langcode
 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
 322  *   used.
 323  *
 324  * @return string|null
 325  *   The label of the entity, or NULL if there is no label defined.
 326  *
 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:
 329  * @code
 330  * $entity->label($langcode);
 331  * @endcode
 332  *
 333  * @see \Drupal\Core\Entity\EntityInterface::label()
 334  */
 335 function entity_page_label(EntityInterface $entity, $langcode = NULL) {
 336   return $entity->label($langcode);
 337 }
 338
 339 /**
 340  * Returns the render array for an entity.
 341  *
 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.
 349  * @param bool $reset
 350  *   (optional) Whether to reset the render cache for the requested entity.
 351  *   Defaults to FALSE.
 352  *
 353  * @return array
 354  *   A render array for the entity.
 355  *
 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:
 358  * @code
 359  * $view_builder = \Drupal::entityTypeManager()
 360  *   ->getViewBuilder($entity->getEntityTypeId());
 361  * return $view_builder->view($entity, $view_mode, $langcode);
 362  * @endcode
 363  *
 364  * @see \Drupal\Core\Entity\EntityTypeManagerInterface::getViewBuilder()
 365  * @see \Drupal\Core\Entity\EntityViewBuilderInterface::view()
 366  */
 367 function entity_view(EntityInterface $entity, $view_mode, $langcode = NULL, $reset = FALSE) {
 368   $render_controller = \Drupal::entityManager()->getViewBuilder($entity->getEntityTypeId());
 369   if ($reset) {
 370     $render_controller->resetCache([$entity]);
 371   }
 372   return $render_controller->view($entity, $view_mode, $langcode);
 373 }
 374
 375 /**
 376  * Returns the render array for the provided entities.
 377  *
 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.
 385  * @param bool $reset
 386  *   (optional) Whether to reset the render cache for the requested entities.
 387  *   Defaults to FALSE.
 388  *
 389  * @return array
 390  *   A render array for the entities, indexed by the same keys as the
 391  *   entities array passed in $entities.
 392  *
 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:
 396  * @code
 397  * $view_builder = \Drupal::entityTypeManager()
 398  *   ->getViewBuilder($entity->getEntityTypeId());
 399  * return $view_builder->viewMultiple($entities, $view_mode, $langcode);
 400  * @endcode
 401  *
 402  * @see \Drupal\Core\Entity\EntityTypeManagerInterface::getViewBuilder()
 403  * @see \Drupal\Core\Entity\EntityViewBuilderInterface::viewMultiple()
 404  */
 405 function entity_view_multiple(array $entities, $view_mode, $langcode = NULL, $reset = FALSE) {
 406   $render_controller = \Drupal::entityManager()->getViewBuilder(reset($entities)->getEntityTypeId());
 407   if ($reset) {
 408     $render_controller->resetCache($entities);
 409   }
 410   return $render_controller->viewMultiple($entities, $view_mode, $langcode);
 411 }
 412
 413 /**
 414  * Returns the entity view display associated with a bundle and view mode.
 415  *
 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.
 420  *
 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
 425  * configuration.
 426  *
 427  * Example usage:
 428  * - Set the 'body' field to be displayed and the 'field_image' field to be
 429  *   hidden on article nodes in the 'default' display.
 430  * @code
 431  * entity_get_display('node', 'article', 'default')
 432  *   ->setComponent('body', array(
 433  *     'type' => 'text_summary_or_trimmed',
 434  *     'settings' => array('trim_length' => '200')
 435  *     'weight' => 1,
 436  *   ))
 437  *   ->removeComponent('field_image')
 438  *   ->save();
 439  * @endcode
 440  *
 441  * @param string $entity_type
 442  *   The entity type.
 443  * @param string $bundle
 444  *   The bundle.
 445  * @param string $view_mode
 446  *   The view mode, or 'default' to retrieve the 'default' display object for
 447  *   this bundle.
 448  *
 449  * @return \Drupal\Core\Entity\Display\EntityViewDisplayInterface
 450  *   The entity view display associated with the view mode.
 451  *
 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:
 454  *   @code
 455  *   \Drupal::entityTypeManager()
 456  *     ->getStorage('entity_view_display')
 457  *     ->load($entity_type . '.' . $bundle . '.' . $view_mode);
 458  *   @endcode
 459  *   When the display is not available in configuration, you can create a new
 460  *   EntityViewDisplay object using:
 461  *   @code
 462  *   $values = array(
 463  *     'targetEntityType' => $entity_type,
 464  *     'bundle' => $bundle,
 465  *     'mode' => $view_mode,
 466  *     'status' => TRUE,
 467  *   );
 468  *   \Drupal::entityTypeManager()
 469  *     ->getStorage('entity_view_display')
 470  *     ->create($values);
 471  *   @endcode
 472  *
 473  * @see \Drupal\Core\Entity\EntityStorageInterface::create()
 474  * @see \Drupal\Core\Entity\EntityStorageInterface::load()
 475  */
 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);
 479
 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.
 485   if (!$display) {
 486     $display = EntityViewDisplay::create([
 487       'targetEntityType' => $entity_type,
 488       'bundle' => $bundle,
 489       'mode' => $view_mode,
 490       'status' => TRUE,
 491     ]);
 492   }
 493
 494   return $display;
 495 }
 496
 497 /**
 498  * Returns the entity form display associated with a bundle and form mode.
 499  *
 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.
 505  *
 506  * Example usage:
 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.
 510  * @code
 511  * entity_get_form_display('node', 'article', 'default')
 512  *   ->setComponent('body', array(
 513  *     'type' => 'text_textarea_with_summary',
 514  *     'weight' => 1,
 515  *   ))
 516  *   ->setComponent('field_image', array(
 517  *     'region' => 'hidden',
 518  *   ))
 519  *   ->save();
 520  * @endcode
 521  *
 522  * @param string $entity_type
 523  *   The entity type.
 524  * @param string $bundle
 525  *   The bundle.
 526  * @param string $form_mode
 527  *   The form mode.
 528  *
 529  * @return \Drupal\Core\Entity\Display\EntityFormDisplayInterface
 530  *   The entity form display associated with the given form mode.
 531  *
 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:
 534  *   @code
 535  *     \Drupal::entityTypeManager()
 536  *       ->getStorage('entity_form_display')
 537  *       ->load($entity_type . '.' . $bundle . '.' . $form_mode);
 538  *   @endcode
 539  *   When the entity form display is not available in configuration, you can
 540  *   create a new EntityFormDisplay object using:
 541  *   @code
 542  *   $values = array(
 543  *    'targetEntityType' => $entity_type,
 544  *    'bundle' => $bundle,
 545  *    'mode' => $form_mode,
 546  *    'status' => TRUE,
 547  *   );
 548  *   \Drupal::entityTypeManager()
 549  *     ->getStorage('entity_form_display')
 550  *     ->create($values);
 551  *   @endcode
 552  *
 553  * @see \Drupal\Core\Entity\EntityStorageInterface::create()
 554  * @see \Drupal\Core\Entity\EntityStorageInterface::load()
 555  */
 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);
 559
 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,
 568       'bundle' => $bundle,
 569       'mode' => $form_mode,
 570       'status' => TRUE,
 571     ]);
 572   }
 573
 574   return $entity_form_display;
 575 }