Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.
By xjm on
Change record status:
Published (View all published change records)
Project:
Introduced in branch:
8.x
Issue links:
Description:
Summary
- Entities are now classed objects that implement the
Drupal\Core\Entity\EntityInterface
. - The default implementation is the
Drupal\Core\Entity\Entity
class. - Entity create, update, and delete functionality is now provided via the interface.
- Users, nodes, comments, files, taxonomy terms and vocabularies have been converted to extend the new base class and interface.
- entity_uri() and entity_label() have been removed in favor of methods. (entity_page_label() has been added for title callbacks and similar use cases)
- See Support for saving and deleting revisions in the default storage controller and entity classes for information on using revisions with entities.
- Full roadmap for entity changes: #1346204: [meta] Drupal 8 Entity API improvements.
- See also: The change notification for Configuration entities (configurables).
Impact on modules
Contributed and custom modules should:
- Convert custom entity types to extend the
Drupal\Core\Entity\Entity
class with a custom class that uses the PSR-4 standard. - Replace
hook_entity_info()
implementations with an annotation on the custom entity class. - Use the common interface for CRUD operations.
- Use the common interface for property getters and setters.
- Replace use of
entity_uri()
andentity_label()
with the corresponding methods provided in the interface. - New entities should be created with
entity_create()
, directly using the PHPnew
keyword and a specific class is discouraged.
API Changes
Added interfaces
- Drupal\Core\Entity\EntityInterface
- Drupal\Core\Entity\Sql\SqlContentEntityStorageInterface (implemented by SqlContentEntityStorage)
Added public methods (compared to the Drupal 7 DrupalEntityControllerInterface):- loadMulitple()
- create()
- delete()
- save()
- Entity classes can implement a series of methods to act when they are created, saved or deleted, for example postSave(), preSave() and corresponding methods for creation and deletion. Implementations must call the parent to also execute anything defined there.
Added and changed classes
Old name | New name | Extends/Implements/ |
---|---|---|
- | Drupal\Core\Entity\Entity | Drupal\Core\Entity\EntityInterface |
- | Drupal\Core\Entity\EntityStorageException | Exception |
- | Drupal\Core\Entity\Sql\SqlContentEntityStorage | Drupal\Core\Entity\EntityStorageControllerInterface |
- | Drupal\comment\Entity\Comment | Drupal\Core\Entity\Entity; Drupal\Core\Entity\ContentEntityInterface |
CommentController | Drupal\comment\CommentStorageController | Drupal\Core\Entity\Sql\SqlContentEntityStorage |
- | Drupal\taxonomy\Entity\Term | Drupal\Core\Entity\Entity; Drupal\Core\Entity\ContentEntityInterface |
- | Drupal\taxonomy\Entity\Vocabulary | Drupal\Core\Entity\Entity |
TaxonomyTermController | Drupal\taxonomy\TermStorageController | Drupal\Core\Entity\Sql\SqlContentEntityStorage |
TaxonomyVocabularyController | Drupal\taxonomy\VocabularyStorageController | Drupal\Core\Entity\Sql\SqlContentEntityStorage |
- | Drupal\node\Entity\Node | Drupal\Core\Entity\Entity; Drupal\Core\Entity\ContentEntityInterface |
NodeController | Drupal\node\NodeStorageController | Drupal\Core\Entity\Sql\SqlContentEntityStorage |
- | Drupal\user\Entity\User | Drupal\Core\Entity\Entity |
UserController | Drupal\user\UserStorageController | Drupal\Core\Entity\Sql\SqlContentEntityStorage |
- | Drupal\file\Entity\File | Drupal\Core\Entity\Entity; Drupal\Core\Entity\ContentEntityInterface |
- | Drupal\file\FileStorageController | Drupal\Core\Entity\Sql\SqlContentEntityStorage |
Added API functions
- entity_delete_multiple()
- entity_create()
Removed API functions
- node_delete()
- comment_delete()
- taxonomy_term_delete()
- taxonomy_vocabulary_delete()
- user_save()
- node_save()
- comment_save()
- taxonomy_term_save()
- taxonomy_vocabulary_save()
Example implementation
- Custom entity that extends the base class and adds a property:
Inmy_module/src/Entity/MyForum.php
namespace Drupal\my_module\Plugin\Core\Entity; use Drupal\Core\Entity\Entity; use Drupal\Core\Entity\EntityStorageControllerInterface; use Drupal\Core\Entity\ContentEntityInterface; use Drupal\Core\Entity\Annotation\EntityType; use Drupal\Core\Annotation\Translation; /** * Defines the MyForum entity type. * * @EntityType( * id = "my_forum", * label = @Translation("My forum"), * ... * ) */ class MyForum extends Entity implements ContentEntityInterface { /** * @var int */ public $threadId = 0; /** * {@inheritdoc} */ protected function postSave(EntityStorageControllerInterface $storage, $update = TRUE) { parent::postSave($storage, $update); if ($forum->threadId) { module_invoke_all('forum_thread_save', $forum); } } }
-
Entity usage:
// Create a new forum instance. $forum = entity_create('myforum', array('threadId' => 5)); // Save entity to the database. $forum->save(); // Do some arbitrary processing of the entity. myforum_process_forum_data($forum); // Save entity again. $forum->save();
Impacts:
Site builders, administrators, editors
Module developers
Themers