With the introduction of Drupal 7, the entities architecture was introduced. It allowed users to move away from the concept of “everything is a node”. An entity is a generic object that has a standard API that allows you to do things like attaching fields, track revisions, and write custom displays. Essentially they are an abstraction of nodes. If a developer needs to create custom data tables, they can expose their custom tables as an entity and still retain core functionality.
Moving from Node to Entity
My problem began when I had to find a way to create instances of some of these entities from JSON data received from a series of web service calls. I already knew how to create nodes programmatically, but what about entities? I did a quick Google search and didn’t see much. So I thought that since nodes are entities and I already knew how to manipulate and create new nodes, I figured that I could create new entity instances in a similar manner to nodes. Perhaps changing some settings on the class would work. Normally when creating a new node instance, I would do:
[php]$node = new stdClass(); $node->type = 'candidate'; $node->bundle = 'node'; $node->language = LANGUAGE_NONE; node_object_prepare($node);[/php]So I tried to rework that by assigning the name of my entity to the type and removing bundle (our entities did not have bundles). This did not seem to work either. Back to Google I went, looking for some more information.
The Entity Creation Problem
Again I came up with very little. Searching for “Drupal 7 create entity” and a dozen other varieties pulled up very little info on how to create actual instances of an entity. Most blog posts revolved around creating an entity type, altering an entity type or searching for an entity. A few of the resources I came across supported the idea of creating entities by using something like:
[php]entity_get_controller('entity_type_name')->save($entity);[/php]This wasn’t very clear to me. I knew what to use in place of the entity_type_name, but where did the $entity come from? The references seemed to skip over this. Or they assumed you were trying to save an entity from a form entry. Sure, we already had forms for creating the entities, but trying to hook into them didn’t feel like a proper way of creating a new entity. It felt cumbersome and it smelled bad.
I tried to work with this method, but I was never able to get it to work.
Just write directly to the database!
Along came some other ideas on how to create new instances of entities. There were some suggestions that the way to create new entities is by writing directly to the database. Okay, that would work, but I’d really rather keep it to the “Drupal Way” and not resort to hacks. There are pitfalls abound with this solution. What happens if the storage engine changes? Our custom entity types already had custom controllers and their save and load functions. Chances are, these wouldn’t be reflected in this solution.
A New Solution: Entity API Module
At this point, I was getting really frustrated, having spent hours on finding a solution to handling this. Discussing this issue with our Director of Engineering Chris Johnson, I was shown a very simple and straight forward method of programmatically handling entity creation.
[php]$entity_property_value_array = array(); $entity_property_value_array['first_name'] = "Brian"; $entity_property_value_array['last_name'] = "Nash"; $entity = entity_create($entity_type_name, $entity_property_value_array); $entity->save();[/php]
And that was it! The entity_create function comes from the Entity API module. It provides functionality that greatly increases the ability to access and set entity data. When assigning a value to a property in a node, one would do something like:
[php]$node->title = "Brian";[/php]Assigning properties to both a node and an entity are straightforward. The Entity API module also provides meta data functionality that handles the language as well, so assigning field values is less verbose as seen below.
[php]$node->field_foo['value'] = "Bar";[/php]
Once I had this figured out, I could process my JSON data by creating a new array that was a entity_property => value array. Granted, that part wasn’t so simple and required handling mapping the names of the fields as they appeared in the JSON object to what they should be in the entity as well as parsing taxonomy lists. But this solution worked and it felt much more straight forward and Drupal-ish than the other methods I saw. The Entity API module is a huge help when creating entities. Here or some resources I ended up reading up on once I found Entity API module. These links provide a good introduction to harnessing entities. Entity API module Entity API module tutorial page Fagos DrupalCon talk on Entity API