How to use EntityFieldQuery's entityCondition() in Drupal 7

2017/02/27Drupal 7

Drupal 7 has a powerful query class EntityFieldQuery in its core.

EntityFieldQuery | entity.inc | Drupal 7.x | Drupal API

There're 3 main methods to specify conditions (which become WHERE clauses when converted to SQL) in EntityFieldQuery.

entityCondition()
propertyCondition()
fieldCondition()

The following is a typical usage for that.

// Get node ids with the following conditions.
// - ccontent type: "page"
// - language: "neutral"
// - body contains "hello" in it.
$query = new EntityFieldQuery();
$query->entityCondition('entity_type', 'node')
  ->entityCondition('bundle', 'page')
  ->propertyCondition('language', LANGUAGE_NONE)
  ->fieldCondition('body', 'format', 'filtered_html')
  ->fieldCondition('body', 'value', '%hello%', 'LIKE');

$result = $query->execute();

propertyCondition() and fieldCondition() are simple and intuitive but entityCondition() is a little tricky (I think).

As the name suggests, propertyCondition() can be used to set conditions for the entity base table. On the other hand, fieldCondition() is a method for setting conditions for value columns in field data tables.

entityCondition() is not like them. This is a special method to specify other types of conditions.

Basically four types of parameters can be passed to entityCondition().

entity_type
bundle
entity_id
revision_id

Among them, most used and tricky one is entity_type.

In some cases entity_type must be specified, but in other cases, it can be optional. Whether entity_type is mandatory or not depends on the other conditions specified in the query instance.

Here are the 3 simplest patterns to understand the rule.

Pattern A:

// [x] entity condition
// [ ] property condition
// [ ] field condition
// -> entity_type is mandatory.
// -> Only single entity type can be searched.
$query = new EntityFieldQuery();
$query->entityCondition('entity_type', 'node')
  ->entityCondition('bundle', 'page');

$result = $query->execute();

Pattern B:

// [ ] entity condition
// [x] property condition
// [ ] field condition
// -> entity_type is mandatory.
// -> Only single entity type can be searched.
$query = new EntityFieldQuery();
$query->entityCondition('entity_type', 'node')
  ->propertyCondition('uid', 15);

$result = $query->execute();

Pattern C:

// [ ] entity condition
// [ ] property condition
// [x] field condition
// -> entity_type is optional.
// -> Multiple entity types can be searched.
$query = new EntityFieldQuery();
$query->fieldCondition('body', 'value', '%hello%', 'LIKE');

$result = $query->execute();

That is, basically it's necessary to specify entity_type. But in limited cases where only field conditions need to be specified, entity_type becomes optional.

The other types of entity condition can be used without complicated rules like above.

bundle
entity_id
revision_id

Actually this information is documented in the official comment. If you are interested, please try checking it for more information.