Change record status: 
Project: 
Introduced in branch: 
8.x
Description: 

Summary

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() and entity_label() with the corresponding methods provided in the interface.
  • New entities should be created with entity_create(), directly using the PHP new 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:
    In my_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
Updates Done (doc team, etc.)
Online documentation: 
Not done
Theming guide: 
Not done
Module developer documentation: 
Not done
Examples project: 
Not done
Coder Review: 
Not done
Coder Upgrade: 
Not done
Other: 
Other updates done