When and why to choose to use a Drupal custom entity

Introduction

Entities introduced into Drupal 7 and a number of contrib modules significantly improved the data modelling capabilities of Drupal. Prior to entities we were stuck with add-hoc solutions and data modelling that was essentially based on making modifications to data structures designed for page related content.

It is still not trivial to get started with entities however, especially difficult to get past the ingrained response to solving every data modelling problem by creating a new content type and adding fields.

Entities require a little time/experience

If you don't have much time and you have not worked directly with the Entity API before, then now may not be the best time to start (if you are working on project with limited scope or tight deadlines), there is a steep learning curve.

It may be possible to short-circuit the curve somewhat by using the Entity construction kit(ECK) a module that enables you to work with entities in the administration interface. To be honest though to reap the full benefits of using custom entities you are still going to need to add some programming to the mix. ECK supports Features and exporting a feature from a custom entity allows you to keep configuration in code and provides a ready-made module where you can place your custom code.

If there is not time to start working with custom entities right away on your current it may be worth investing some time to start learning about them.

What type of thing is it?

If the thing you are modelling is some kind of content, particularly content that can be accessed and viewed via a unique url then it is almost certainly a node rather than a type of custom entity. An example would be a news article.

At the other extreme, if the thing you are modelling is just pure data, data which may get aggregated before display or is only displayed as part of another page then it should probably be best as a custom entity. An example would be data to be displayed on a flight arrivals or departure board (webpage version).

Many things will fall in between extremes, experience data modelling with other frameworks will probably tell you whether node is an appropriate choice or whether you should go with a custom entity.

Some indicators are:

• Relatively short lived things are more likely to be custom entities than long-lived things (which may have a web presence)
• Meta data which is used to fetch other data or content (for example meta data about videos stored on cloud service) is probably best as a custom entity
• Data not displayed (perhaps something fetched from a third-party API to be used programatically later but not in the same request) is probably best as a custom entity
• Things that are only ever displayed as part of other things will tend towards custom entities

If you can think of any other obvious indicators then please leave a comment and I will add them to this post, it is beginning to get a little hard to see the wood from the trees.

Performance and clarity

If you have a large complicated site with lots of things to model and all of those are implemented as nodes then everything that listens in on node related hooks is aware of them even if it doesn't do anything useful with them. By default the administration sections of the site that traditionally deal with node related content become cumbersome and bloated.

Nodes are revisioned, adding more performance overhead when this is not required for your thing.

Some the things that you have modeled may not even need fields, their properties could work simply as Entity properties cutting out the database joins required to look up fields on these things (ironic that originally we wanted fields on everything but now it might be better to go the other way and cut the fields out in some cases).

Finding candidates for entities can clean a site up significantly and potentially provide a significant performance boost.

In preparation for upgrade to Drupal 8

Whilst the time when ou will be thinking about upgrading to Drupal 8 may seem a long time off, at some point it is going to happen. Using the APIs in Drupal 7 and in the Entity API module should give you a good basis with lots of examples (and other people helping with  painpoints) online.

Take advantage of other Entity modules

Using a custom entity can give you opportunities to take advantage of other modules that are working through the Entity Api for example you may implement caching through the Entity cache module.

Are you (or your predecessors) being evil?

Perhaps you realize that evilness has been propagated to model the data on your site, and it would be a good idea save yourself (or those that come along later) from technical debt.

One entity anti-pattern is when taxonomy terms are seriously overloaded. Because they are already there in core, because they are field-able and have administration pages they are used as stand-in entities and filled with fields etc. whilst being used for something that taxonomies clearly weren't intended for.

Sites that have been upgraded from Drupal 6 to Drupal 7 will probably carry an evilness debt.