Skip to main content

Drupal 8 Entity Series- Part One - Introduction to Entities

This series of blog articles will describe Drupal 8 Entities, what they are, how to create them, an explanation of the class structure necessary to integrate with Drupal 8, how to manipulate entities with the Drupal 8 Entity API, and later, how to customize entity types in a variety of ways.

Part one of this series, Introduction to Entities will describe what a Entity is, its origination in Drupal 7, and the differences and feature enhancements that Entities have in Drupal 8.

What are Drupal Entities?

With the release of the first release candidate, the era of Drupal 8 is here. Drupal 8 includes the same Entity concept as Drupal 7, including the missing pieces provided by the contribution module Entity API, and taking it several steps further.  The Entity concept is crucial to understand how Drupal works, and can be extended.

Entities, in Drupal, are objects that are used for persistent storage of content and configuration information.

Entity Types are used to define custom types of data, content, or configuration which can be used for specific purposes.  The default Content or Node type is an example of an Entity type that comes included with both Drupal core 7 and 8. 

There are many occasions when it makes sense to create your own entity type, by which you can have ultimate flexibility and control on every aspect of data, from display, to saving and editing, custom properties, and integration with other entities.  Sometimes you want to store data that will primarily be used in calculations or for storage and is not designed to be the main content item of a web page. Creating your own Entity types allows you to manage the spectrum and synthesis of data vs. content in a web site with flexibility and with an eye toward optimized performance.

In this way, data/content items such as Comments, are developed to behave and display differently than Nodes or other content data, but be manipulated with the same general Entity API.

A good starting place is to read about the basic conceptual structure of the Drupal 7 Entity concept most of which is applicable to Drupal 8 Entities. 

The Drupal concept abstraction ladder is as follows: Entity Type -> Bundle -> Fields -> Entities

  • An Entity Type is definition for a type of data. Example: Car
  • Bundles are specific instances of a Entity Type....Example: Sports car, or Van , which may need different fields to describe them, but they're both Cars.
  • Fields are the individual data units that a Entity type or Bundle utilizes. For instance, on a Car entity type, we may have fields (Transmission, Paint Color).
  • Entities are specific instances of a Entity type bundle object. I create a Car entity, one specific record of data, for instance a MiniVan with a automatic 5 speed transmission, green paint.

It bears repeating, that from a OO developer perspective:

  • An entity type is a base class
  • bundle is an extended class
  • field is a class memberpropertyvariable or field instance (depending on your naming preference)
  • An entity is an object or instance of a base or extended class

With Drupal 8 the Entity concept is expanded further by:

  • Including the full Entity API in Core
  • Fully OO, namespaces, classes, interfaces
  • Entity Validation API in Core
  • Most every type of data is now accessible and stored as an Entity via an Entity API
  • Entities are now specifically typed objects, with each entity type defining a class that will be used for instances of the given entity
  • Entity based storage in D8 vs. field based storage in D7 (read this for detailed information)
  • Entity API now implements the Typed Data API
    • Describe your data using typed data definitions
    • Based on an extendable list of data types
      • string, integer, float, entity, node, field_item:image
  • Two Entity Variants
    • Content Entities (what we think of entities generally in Drupal 7)
    • Configuration Entities (which are designed and used with the new D8 Configuration System)
  • There are no properties for content entities in D8, all entity data are now Fields
    • What was once properties, are now Base Fields.  Base fields appear on every bundle of an Entity Type, think of these as required fields for any entity of the type you create, no matter the bundle. They are still Drupal Fields though.
    • What was called Fields in Drupal 7, are now technically Configurable Fields, as normal fields, Configurable Field instances are created per bundle, but not required, same as Drupal 7.
    • Both use the standard Drupal 8 Field API, so we get all that Field wonderfulness, such as field formatters. field widgets, etc... 
  • Translations

Drupal 8 Entity Documentation

Drupal 8 Entity API and Class Reference

Future topics will include:

  • Generating a content entity type boilerplate code with Drupal Console
  • Generated files, file structure, code, and OO class structure descriptions and explanations
  • Configuration Entities
  • Overview of Entity API, Entity Metadata Wrappers, hooks
  • Adding Bundles to the Car entity
  • Add configuration options to the Entity settings page
  • Adding custom field types and base fields to the entity
  • Revisions and Translations
  • Change the menu routing paths
  • And more...

Share this post