Updating the Search API to D8 – Part 1: Creating an entity type

TL; DR:

The 8.x version of Drupal has entered Alpha stage and people everywhere are telling you to port your modules now. However, proper documentation is scarce and existing tutorials or examples only explain the simplest steps. Bad for modules like the Search API, which define new entity types and plugins and aren’t as easy to port.
Still, I decided to venture into the unknown and start porting now. It was about as bad as I’d feared and I’m still far, far from finished, but I nevertheless wanted to share the first advanced pieces of updating wisdom I’ve found. Hopefully it will help others get started more smoothly than I did.

Where to start

So, you’ve decided to port your complex module (which, e.g., lets you take your pant entities off) to D8. Great! But where to start?
Of course, there’s the much-praise list of change records. A quick glance will tell you that there’s currently 464 entries in there – so better close that tab again and move on. (The search is also very bad, as it finds everything and sorts it by date instead of relevance. So even if you know something has changed (e.g., the entity system) and just need information on that, it’s rather hard to find it. It will also be mostly spread across multiple records.)
The documentation is surprisingly detailed and up-to-date in some areas (e.g., Plugins) and as out-of-date and monosyllabic as you’d fear in others (e.g., entities), so it’s really a hit-or-miss there. If you’re looking for something, try to find it in change records or the documentation first, but prepare for the possibility that you’ll have to resort to the surest, but also most exhausting option: digging through core code and seeing how they do it.

Caveat

Before I start, a word of caution which probably isn’t necessary: the whole D8 code is still very much in flux, so everything is volatile and very much subject to change. I myself expect to have to revisit much of what I talk about here to adapt it to upcoming core changes (not that I’m even trying to keep track of them beforehand). Especially since the entity system seems to be among the particularly volatile, as some things simply don’t work right now, others aren’t very elegant and there seem to be three versions of entities (a backwards-compatibility (BC) layer, “normal” entities and something by the name of EntityNG). I’m curious what they’ll come up with there, in the end.

Creating an entity type in D8

So, let’s get started! How to create a new entity type …

Different kinds of entities

First off, you’ll have to decide what kind of entity you want: content entities, like nodes or users, are typically stored in the database, same as D7 entities. They should be used for content which usually isn’t deployed from a staging server but can be created in any amount on the production site. Configuration entities, on the other hand, integrate with the new configuration system in D8 and can thus be easily deployed from a staging environment to a production site. Use these, therefore, for entities which are basically site configuration – blocks or content types are good examples here.