Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 37 ยท Concepts and Installation

Entities, Bundles and Fields: The Content Model

Understand Drupal's content model: entity types, bundles, fields, nodes, users, taxonomy terms, config entities versus content entities, and how they fit together.

If you remember only one concept from Drupal, make it the entity. Almost everything Drupal stores and shows is an entity: a page, a user, a comment, a category term, an uploaded image, a block, even a View's definition. Once you see the pattern of entity type, bundle and field, the admin UI stops feeling like a maze, because every screen is a variation on it.

This lesson explains the vocabulary in plain words, shows the real PHP and YAML that correspond to it, and gives you a runnable model to play with.

Four words

  • Entity type: a kind of thing Drupal knows how to store. Examples: node, user, taxonomy_term, comment, media, file, block_content.
  • Bundle: a subtype of an entity type. For nodes, the bundles are content types (Article, Basic page, Event). For taxonomy terms the bundles are vocabularies. For media they are media types (Image, Document).
  • Entity: one concrete item, such as the article titled "Spring schedule".
  • Field: a named piece of data attached to a bundle: body, image, date, price, reference to another entity.
flowchart TD
    ET["Entity type: node"] --> B1["Bundle: article"]
    ET --> B2["Bundle: event"]
    B1 --> F1["Fields: title, body, image, tags"]
    B2 --> F2["Fields: title, date, place, speakers"]
    F1 --> E1["Entity: 'Spring schedule'"]
    F2 --> E2["Entity: 'Open day'"]

Entity type contains bundles, bundles define fields, and entities hold values for those fields.

Content entities and configuration entities

Drupal separates two families:

Family Examples Holds Lives in
Content entities node, user, comment, media Data created by users Database tables
Configuration entities content type, vocabulary, View, role, block placement Site-building definitions Config storage, exportable as YAML

This explains an earlier idea: the Article content type is a configuration entity (it travels from development to production in config/sync), while an article is a content entity (it stays in each site's database).

Base fields and configurable fields

Some fields exist on every bundle of an entity type. These are base fields and are defined in code: a node always has nid, uuid, title, status, created and uid. Others are configurable fields you add through the UI or YAML, such as field_image or field_event_date. By convention, fields you create start with field_.

Each field has three layers:

  1. Field storage: its machine name, type (text, integer, entity reference...), and cardinality (how many values).
  2. Field instance (per bundle): label, required or not, default value, help text.
  3. Widgets and formatters: how it is edited and displayed (covered later).

Entity IDs, UUIDs and revisions

Each entity has a numeric ID (unique per type and site) and a UUID, a globally unique identifier that stays the same when content or configuration moves between environments. Many content entities also support revisions: saving a node can keep the previous state, with a revision log message.

Reading an entity in code

You work with entities through the entity type manager. This is real Drupal code, shown read-only:

PHP
<?php

$node = \Drupal::entityTypeManager()->getStorage('node')->load(1);

echo $node->bundle();                 // "article"
echo $node->label();                  // the title
echo $node->get('field_summary')->value;
echo $node->getOwner()->getDisplayName();

Creating one:

PHP
$node = \Drupal::entityTypeManager()->getStorage('node')->create([
  'type' => 'article',
  'title' => 'Spring schedule',
  'field_summary' => 'Courses start in April.',
  'status' => 1,
]);
$node->save();

Notice there is no SQL. Drupal's storage layer turns this into queries, fires hooks and events, clears the right caches and records revisions.

A model you can run

This stand-in reproduces the structure: entity types containing bundles, bundles with field definitions, and a create function that validates values against those definitions. It is not Drupal's API, but it has the same shape.

JS Stand-in: entity types, bundles and fields

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice how adding a field to a bundle is a model change, not a code change in every place that shows the data.

Why the model matters

Because everything is an entity with fields:

  • Views can list any entity type and filter by any field.
  • Forms and displays are generated from the field definitions.
  • Permissions can be set per bundle ("edit any article").
  • Translation can happen per field.
  • APIs such as JSON:API can expose every entity automatically.

Learning the model once pays off in every later chapter.

Exploring relationships

Entities refer to each other with entity reference fields: an article references its author, a taxonomy term, a media item. Following references is how you build rich pages without duplicating data. Here is a second stand-in resolving references; it demonstrates the "load by ID" idea behind real reference fields.

JS Stand-in: following entity references

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In Drupal, what is a content type like Article?

    Node is the entity type; Article and Basic page are bundles of it.
  2. 2. Which is a configuration entity?

    Views definitions are configuration: exportable as YAML and deployed between environments.
  3. 3. What is the benefit of a UUID?

    UUIDs identify an entity across sites, unlike numeric IDs that can differ.
  4. 4. Which code approach is recommended for loading an entity?

    The entity API handles caching, hooks, access and revisions for you.

Summary

  • Entity types (node, user, term...) contain bundles (content types, vocabularies), which define fields.
  • Content entities hold data; configuration entities hold site-building definitions.
  • Fields have storage, per-bundle instances, widgets and formatters.
  • Use the entity API, not raw SQL; the model powers Views, forms, permissions and APIs.

Next: Routing and the Request Lifecycle