Drupal Entities - Part 2 - The what, where and when of Entities

In a previous post I had a look at how Drupal moved from nodes as its main unit of abstraction to entities. That trip through Drupal history tried to explain why entities exists but only partly touched on exactly what they are. Here we are going to answer in some more detail what they are, as well as, where and when to use them. I am not going to get too technical (i.e. no code) - the aim is to allow everyone to figure out what entities are and what they can do. In a follow-up, and final in the series, post we are going to get really technical (i.e. mostly code) and look at the how.

What are Drupal Entities

The word entity can take on many meanings in computer science. The most commonly referred to meaning, and the one that seems to popup very often when first mentioning Drupal entities, comes from the database world. In DB-speak entities are the "things" we wish to represent in our application domain. Typically, this is explained in the flow of explaining Entity-Relationship diagrams - the bane of many a first year computer science undergrad. Drupal entities are, in a loose way, similar. Entities are the things, the data, the information, the "stuff", that we want to deal with in our Drupal application. The similarities, however, pretty much end there. When you think of Drupal entities you really should think of them exclusively within the Drupal way of doing things. As with nodes, entities in Drupal take on a new meaning and life and become a term native to and truly definable only within the context of Drupal. So what is the "stuff" that we want to represent in a Drupal application? Well we have nodes, taxonomy terms, users, comments. These are our main building blocks and they are all entities in Drupal 7. Now, that is fine - but it's the same stuff we had in Drupal 6 right? So what's the big bruhaha all about? Just that we are now calling all these things entities? Well, not quite. Entities are all dealt with in the same way in Drupal 7 while in Drupal 6 they each did their own thing (or repeated similar things in different ways). Entities have a common programmatic interface through which (most) of their behaviour is defined. So the first thing Drupal entities are is means to streamline how we deal with the basic Drupal "stuff" of nodes, comments, terms and users. Now comes the really interesting part to people that don't worry so much about how the core of Drupal does things. 1. You can define your own entities that plug into the whole Drupal way of doing stuff. 2. Any entity can have fields attached to it. Remember CCK? How great that is for Drupal 6? How you can turn nodes into anything you want just by adding fields to them? Well In Drupal 7 you have all that goodness for all entities - which means nodes, users, terms and comments. Also, and here is the beauty of it, you also get this functionality for any entities you define yourself. This makes it a whole new ballgame. You can now actually create data structures specific to your application domain with their own database table (or any other storage mechanism really) plus a standardised way to add fields to them. No need to turn nodes into something they are not. A few examples:

• The Drupal 7 Commerce solution uses Entities to describe a line item in an invoice. As ChX explained to me in IRC they found this a convenient way to group all the fields related to a line item without having to re-purpose nodes for the job but also without having to introduce a completely custom way to deal with data.
• The team over at Examiner.com use entities to store user profile revisioning information (functionality they are hoping to release soon).
• The Drupal 7 Rules module uses entities to store Rules configurations.

So Drupal entities are:

• A way to describe to the rest of your Drupal application something that is relevant and unique to your domain, that can have its own database table, but at the same time...
• ...use Drupal APIs to add fields to it and interact with it in a variety of ways, which means...
• ...that you get lots of stuff for free such as Views integration or the ability to use MongoDB for storage.

But how do you make the choice of when to create a new entity, whether you just attach fields to it or keep all the data in its own table, or simply do it the old way and re-purpose nodes?

When and why should one use entities

Entities are still a pretty new concept so best practice will still take some defining. However, ChX and DamZ gave some good advice on IRC. Essentially, if you are faced with having to put information into a custom table consider whether defining an entity and attaching fields to it through the Drupal APIs might be worthwhile. And let me give you a hint - the answer is: yes, it probably makes more sense to use entities. There is practically no drawback to exposing a custom table as an entity. While in Drupal 6 re-purposing nodes to do your bidding is very useful, there is something inherently inelegant about it because after all nodes are really designed to do one very specific thing - store articles. In Drupal 7, however, you can create your own lean entity and attach to it just the fields you need. You don't need to carry along node functionality (e.g. author, publish date, etc) that you don't really need. According to both ChX and DamZ the base table representing your entity in the database should generally be kept simple and you can attach fields to entities to define your data structure. The only reasons to consider adding data attributes directly to the entity and not through the Drupal Field API is if the data is quite specific and is not well served by any available field type or if performance-wise it makes more sense to query only the base table (for example if you plan to frequently query it) to get information out rather than having to query both the base table and the table where the field information is saved. Keep in mind, however, that a major driving force behind the architecture of entities and fields is scalability - so if you are really concerned about performance you probably still want to use fields where you can decide exactly how they are stored (e.g. in a MongoDB database rather than MySQL). When not to use entities? Well, there isn't any user interface for defining and dealing with entities (yet). So right now if you want a quick way to get something done without writing any code re-purposing nodes it still the best way to do it. But, if you are willing to write a bit of code (and as we will see in the next post it really is not complicated) you can have a more elegant web app at your disposal that can still call itself a fully-qualified member of the Drupal way of doing things.

Not all roses...

As I mentioned before entities are still pretty new. And the overhaul to get them into Drupal 7 was huge - so there are still a few things missing. While you have a unified interface to define and load entities there isn't (in core) a means to do all entity operations (Create, Read, Update, Delete) but work is taking place in the contrib module space to get there. Another issue is how to define relationships between entities. Nodes, comments, taxonomy terms and users are all related between them. But these relationships are hard-coded. Again, there is work underway in the contrib space to explore how to deal with this issue as well.

...but it definitely exciting!

While things aren't perfect yet they are really on a very good path to Drupal nirvana. As ChX mentioned to me on IRC it is going to take a couple of years before we figure out all the things that we can do with Drupal 7. Which sounds just about right - as hopefully Drupal 8 will be coming out then and will be even more awesome! ------- Thanks to ChX for taking the time to spell a few things out during an IRC chat and reviewing the article and DamZ for joining in and adding some very useful comments Any inaccuracies are entirely mine. Check out the third part in the series for info on how to code your own entities in Drupal 7