I have a big personal project build on Drupal 7 that has many custom entities. I want to start upgrading the project into Drupal 8 but the completly rewritten Drupal 8 core is too big for me to get my head around without any documentation(+ Symfony is totally unknown to me, I'm just a simple Drupal-only guy).

I tried to create a custom entity just by looking at some of the core modules code but without any success.

Can you point me to some articles about custom entities in Drupal 8(I haven't been able to find single one) or give me some basic step-by-step guide?


  • 1
    Could you edit the question to add a bit about how far you've got, and exactly where you're struggling? Seeing the specific code you're having problems with would be ideal. Building a custom entity isn't a small task - it's probably too broad a question, both for the site format, and for your chances of getting a good answer. Please bear in mind that requests for links/tutorials are specifically off-topic here for just that reason. Better to break it down piece by piece, and ask questions about those little pieces. Thanks – Clive Nov 23 '13 at 19:15
  • As an aside, if you don't know any Symfony you're probably going to find it difficult to apply your D7 knowledge to D8. Things have changed quite substantially (as I'm sure you already know). I'd strongly recommend reading as much of the Symfony book as you can before embarking on your journey; having that sort of grounding will make the transition a lot smoother, trust me. As another aside, I found the Category and Message entities in the core Contact module to be very good starting points for learning – Clive Nov 23 '13 at 19:21
  • @Clive Apart from the validation API has the Entity API in Drupal 8 almost nothing to do with Symfony, so I don't think it's that relevant. Otherwise agree with the question being too broad, but I tried to give an overview, more specific questions can then be answered in more detail. And it helps to have a starting point, as that isn't too obvious if you don't know D8. – Berdir Nov 23 '13 at 19:32
  • @Berdir I meant D7 -> D8 in general, not for entities specifically. Knowing about Symfony routing and services, for example, makes understanding core code a lot easier in general. Great write-up by the way, no reason to even think about closing this question now IMO, it's a valuable resource (even if it is a tad on the broad side) – Clive Nov 23 '13 at 20:00

I'm working on Entity API documentation here: https://drupal.org/developing/api/entity.

The question is too big to answer in detail, and it depends on whether you need content or config entities. Assuming you want content entities (stored in database, can be fieldable/revisionable/..., details in the link above), you need to do something like this, the documentation linked above will eventually cover each step, including tutorials, right now, it only covers the first steps.

  1. Provide an entity class and add the necessary annotations to expose it as an entity.
  2. Provide the necessary table(s), you don't have to change much if you already have your 7.x schema, but you want to add a uuid and possibly langcode column if your entity can have a language/be translatable. See the node example linked in step if you want to make some base fields (properties) translatable or revisionable, you currently need to provide the necessary tables yourself.
  3. Provide the base field definitions in your baseFieldDefinitions() method.. Note that the way this works will change in https://drupal.org/node/2047229 (from arrays to classes).
  4. Implement the necessary pre/post Save/load/Delete methods if you have custom logic that needs to happen e.g. before saving an entity (like updating the changed timestamp).
  5. Implement an access controller if you have non-trivial access logic and override the checkAccess() and checkCreateAccess() methods or specify the admin_permission in your annotation if you just have a single permission that allows full access.
  6. It is recommended although not technically required to provide an interface for your entity class (e.g. NodeInterface for Node) that includes useful (usually get/set/isSomething()) methods for your base fields, so that you can type hint on the interface and get auto-complete for those methods.

Depending on what you need, there will also be further steps, like defining the necessary forms, possibly a render controller and so on, but those should probably be separate questions if you need more information.


  • Config entities are basically similar, except you need to use the config storage controller (https://drupal.org/node/2119905 will make this easier), you don't need to define table schemas (obviously) but you need to provide a config schema file, see e.g. those for taxonomy vocabularies or node types.
  • Content entities don't have their base fields defined as public or protected properties, instead, they are automatically managed in the values and fields properties. Access them either through get()/set() or the corresponding magic methods. ($node->title is equal to $node->get('title')).
  • Help on the documentation there would be very welcome. I've created a basic outline for the content/structure I'd like to have, so just create a new page and get started on e.g. I'm also interested in having simplified tutorials, for config entities, there's one here already that I will move over to the entity documentation when ready: https://drupal.org/node/1809494
  • Core has quite a large number of content entity implementations, if you want to see working examples: Node, User, Term, Comment, CustomBlock, ... as the article linked in step 1 explains, you can always find the entity types provided by a module in the Entity namespaace.
  • @fago just gave a presentation about Entity API at the DrupalCamp Vienna this weekend, covers a lot of what I wrote here and more.