I’m trying to wrap my head around D8 Configuration Entities (CFE). The concept of a Content Entity (CTE) seems easy – if you want an application that keeps the information for a CD music collection you can build a content entity that creates a table and stores the fields of your CDs (e.g. Artist and Title).

What is a CFE is used for? When the CFE example in the “examples” module is installed the result is a link to a page that shows a table that contains one default “robot” (Marvin) and a button to "Add A Robot". How is this different from creating a robot entity via a CTE?

I do appreciate that there is a structural database difference. The data for each robot gets stored in the config table.


4 Answers 4


I would like to add some additional general thoughts on the differences…

Content entities are generally external facing, meaning your site viewers will interact with your content – ie. they will read your pages & articles; they will look at your images, they will browse thru your product catalog, they will post comments and reviews, etc.

Config entities are generally internal facing, normally only site administrators & content editors interact with a config entity such as setting up a new view or adding a block to a page.

There are many, many, instances of content entities – think of a news website and how many hundreds or thousands of articles there are, but there are only a few instances of config entities – with the article, there may just be one content type (content types are config entities) needed for all those articles.

Content entities generally store data in their own database tables and fields though you don’t have to use hook_schema to create them, they are more often instantiated in the class annotations, with yaml files or by using the UI. Config entities can have database fields, but by default they do not. That is not to say they don’t have fields, they do have fields. The content type entity has fields, such as name and description (you just won’t find them in the database as such).

  • Saying that content types are configuration entities sounds right and makes sense. And I thought that was what the configuration entity example from the examples module, which creates a robot, was doing. But it doesn’t show up in the table on the Home->Administration->Structure page, nor am I able to add one through the normal Add Content method; it has it’s own Add form.
    – Mike
    Commented May 19, 2017 at 20:05
  • One thing that confuses the issue is the name "Content." Drupal core provides the node entity (and node type entity) - node is the main content entity and it's called "Content" in umpteen million places (and node types are called "Content Types"). Sometimes when people talk about "Content" entities they are talking about different node types (ie page or article) and sometimes they are talking about a completely different entity - which is a Content Entity with it's own class definition and UI. The Robot example is it's own entity with no relationship whatsover to node or node types.
    – rjl
    Commented May 19, 2017 at 20:39
  • I agree, I've found much of Drupal's terminology confusing. So is the "Robot" a content "type" and why doesn't is appear in the Add Content list?
    – Mike
    Commented May 19, 2017 at 22:39
  • It is a config entity type. See the line @ConfigEntityType( in api.drupal.org/api/examples/… and it has no relationship to nodes which is what is is added with Add Content
    – rjl
    Commented May 20, 2017 at 5:00
  • 1
    That is a tough question, the creator of the robot module decided that he (or she) needed a config entity and not a content entity as a solution for what they needed. That example is both good as it is pretty straight forward, and bad as it doesn't really provide a use case and why a robot was the solution. That poor robot doesn't do much, but you can configure it (humor). Here is a good slide show from Acquia that provides a nice over view of entities (and a little history) slideshare.net/AcquiaInc/…
    – rjl
    Commented May 23, 2017 at 21:36

The configuration entity is used to create configuration items. Entities allow you to store more complex configuration structures, which can be listed, edited, deleted, etc., but, above all, can be instantiated multiple times.

Examples of configuration entities include date formats, vocabularies, image styles, roles, menus, views, Pathauto URL patterns, and text formats. All have in common that you can create multiple such elements, and perform other common operations like edit and delete. They also have in common that they are entities that are only managed from the configuration or administration of the site, without exposing them to the end user.

Configuration entities are translatable and can provide default values ​​that will be taken into account during installation. Configuration entities can not have fields.

Content Entity. Content entities are used to create content items. They differ mainly because they have fields. The Manage fields, Manage presentation, etc. options are common in content entities. They are also translatable and, optionally, may have revisions.

Examples of content entities are nodes, comments, taxonomy terms, users, files, custom block types, etc.

A fundamental difference between the two variants is that the configuration entities use the configuration system to store the information, instead of the database, which is the storage used by the content entities.

  • I’ve grasped the structural difference – I think – between a content and config entity. What I think I’m confused about perhaps is what and how to use a configuration entity. Can I create a new view with one? Change the access to content by adding or modifying a role?
    – Mike
    Commented May 23, 2017 at 14:38
  • @Mike take a look in admin/config/media/image-styles this is a config entity, is just a config that you can change from the UI. Think in a config entity as a config that you can change in the UI. Commented May 23, 2017 at 15:14
  • So is a config entity just a content entity that is “configurable”?
    – Mike
    Commented May 23, 2017 at 21:26
  • 1
    @Mike a Config entity is not a Content entity because you can't export a Content entity but you can do it with a Config entity and import the config in other enviroments, read all the answer again and the drupal.org/docs/8/api/entity-api/configuration-entity and maybe this will help you. Commented May 23, 2017 at 21:29
  • @AdrianCidAlmaguer when building a custom module, that needs simple configuration we don't use config entities right? we use admin config forms which end up being saved in configuration. Can you give an example on when to use a configuration entity?
    – awm
    Commented Dec 31, 2018 at 20:46

Configuration entities are useing the entity API in order to keep configuration in the database, not content.

Differences compared to Content Entity

  1. Integrates with CMI API for exportability (yml files)
  2. No fields
  3. Schema file (Content Entity uses hook_schema())

If you create a module that needs to store some configuration per "whatever" (i.e. role), use config entities.

More about this on Drupal.org


Another way to ask and answer this question is "why".

If you look at some contributed modules in Drupal 7, and particularly if you look at their uninstall code, you'll see some pretty ugly stuff getting jammed into the variables table, because this was the easy and default way to store "user" configuration from a module (if you want a random example, try "fivestar").

So if you start thinking about how to handle these "dynamic" kinds of configuration, and you've got this nice "entity" abstraction sitting around, you'll appreciate that it's a great fit - you get stuff like CRUD and listings sort of for free which is typically what you want for this kind of configuration-type thingy.

The hardest part (IMHO) is updating your brain to separate entities from content, which is what entities are often used for. The real key is to understand "user configuration with multiple entries" - that's the thing that is such a nice match to entities and why configuration entities were developed.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.