Drupal 7 Module Development

Chapter 7
To demonstrate how entity and field queries work, let's start by creating a new menu
item to list recently created artworks. We'll put it in the artwork module for now.
function artwork_menu() {
// ...
$items['artwork/recent'] = array(
'title' => 'Recently added artworks',
'page callback' => 'artwork_page_list_recent',
'access arguments' => array('view artworks'),
'file' => 'artwork.pages.inc',
);
}
return $items;
Just as Drupal provides a query builder for SQL databases that abstracts
database-specific logic, it also provides a query builder for Entities and Fields.
The API for it is a single class named, boringly enough, EntityFieldQuery.
Before we have a look at EntityFieldQuery directly, let's take a step back and
consider what sorts of things we can search on. At the conceptual level, there
are three "levels" of data by which we can filter:
• Entity level data: It is data that is common to all entities of all types. This
includes the entity type itself, the bundle name, the entity ID, and the
revision ID (if applicable). All entities of any type will have these items.
• Properties: They are those data elements that are common to all objects of
a given entity type, but not to all entities. That is, they are pieces of data
common to all nodes, or to all users, or to all artworks. Examples include the
'node title' and 'creator uid' for nodes, user 'login name' for user entities, and
the 'artwork title' and 'creation date' for artworks.
• Fields: They are, of course, specific to a given bundle definition (painting or
sculpture). However, they may also be shared by entities of different types.
When searching for entities, we can filter by or order by data at each of those levels.
Not all combinations make sense, however, and the query will reject nonsensical
combinations by throwing an exception.
Since we cannot know what the storage engine or engines are that an entity uses, that
too limits the complexity of the searches we can do. For instance, we are only able to
do "AND" searches, not complex conditions with OR. We also cannot search across
different data stores. Nonetheless, that still leaves a huge range of use cases that can
be solved very easily.
[ 207 ]