From 35880070129c58ecdf9eea58ad475d1df7ffb1ce Mon Sep 17 00:00:00 2001
From: David Rothstein <drothstein@gmail.com>
Date: Sun, 3 Jul 2016 15:28:22 -0400
Subject: [PATCH] Issue #1622964 by felribeiro, snehi, ar-jan, Girish-jerk,
jhodgdon, joachim, jp.stacey, stefan.r: docs for
EntityFieldQuery::fieldCondition are really sparse
---
includes/entity.inc | 44 ++++++++++++++++++++++++++++++++++----------
1 file changed, 34 insertions(+), 10 deletions(-)
diff --git a/includes/entity.inc b/includes/entity.inc
index 62359a94ab14..e80ce3b89fd6 100644
--- a/includes/entity.inc
+++ b/includes/entity.inc
@@ -446,7 +446,7 @@ class EntityFieldQueryException extends Exception {}
*
* This class allows finding entities based on entity properties (for example,
* node->changed), field values, and generic entity meta data (bundle,
- * entity type, entity id, and revision ID). It is not possible to query across
+ * entity type, entity ID, and revision ID). It is not possible to query across
* multiple entity types. For example, there is no facility to find published
* nodes written by users created in the last hour, as this would require
* querying both node->status and user->created.
@@ -688,14 +688,36 @@ public function entityCondition($name, $value, $operator = NULL) {
* @param $field
* Either a field name or a field array.
* @param $column
- * The column that should hold the value to be matched.
+ * The column that should hold the value to be matched, defined in the
+ * hook_field_schema() of this field. If this is omitted then all of the
+ * other parameters are ignored, except $field, and this call will just be
+ * adding a condition that says that the field has a value, rather than
+ * testing the value itself.
* @param $value
- * The value to test the column value against.
+ * The value to test the column value against. In most cases, this is a
+ * scalar. For more complex options, it is an array. The meaning of each
+ * element in the array is dependent on $operator.
* @param $operator
- * The operator to be used to test the given value.
+ * The operator to be used to test the given value. The possible values are:
+ * - '=', '<>', '>', '>=', '<', '<=', 'STARTS_WITH', 'CONTAINS': These
+ * operators expect $value to be a literal of the same type as the
+ * column.
+ * - 'IN', 'NOT IN': These operators expect $value to be an array of
+ * literals of the same type as the column.
+ * - 'BETWEEN': This operator expects $value to be an array of two literals
+ * of the same type as the column.
+ * The operator can be omitted, and will default to 'IN' if the value is an
+ * array, or to '=' otherwise.
* @param $delta_group
* An arbitrary identifier: conditions in the same group must have the same
- * $delta_group.
+ * $delta_group. For example, let's presume a multivalue field which has
+ * two columns, 'color' and 'shape', and for entity ID 1, there are two
+ * values: red/square and blue/circle. Entity ID 1 does not have values
+ * corresponding to 'red circle'; however if you pass 'red' and 'circle' as
+ * conditions, it will appear in the results -- by default queries will run
+ * against any combination of deltas. By passing the conditions with the
+ * same $delta_group it will ensure that only values attached to the same
+ * delta are matched, and entity 1 would then be excluded from the results.
* @param $language_group
* An arbitrary identifier: conditions in the same group must have the same
* $language_group.
@@ -770,9 +792,11 @@ public function fieldDeltaCondition($field, $value = NULL, $operator = NULL, $de
* @param $field
* Either a field name or a field array.
* @param $column
- * A column defined in the hook_field_schema() of this field. If this is
- * omitted then the query will find only entities that have data in this
- * field, using the entity and property conditions if there are any.
+ * The column that should hold the value to be matched, defined in the
+ * hook_field_schema() of this field. If this is omitted then all of the
+ * other parameters are ignored, except $field, and this call will just be
+ * adding a condition that says that the field has a value, rather than
+ * testing the value itself.
* @param $value
* The value to test the column value against. In most cases, this is a
* scalar. For more complex options, it is an array. The meaning of each
@@ -791,10 +815,10 @@ public function fieldDeltaCondition($field, $value = NULL, $operator = NULL, $de
* @param $delta_group
* An arbitrary identifier: conditions in the same group must have the same
* $delta_group. For example, let's presume a multivalue field which has
- * two columns, 'color' and 'shape', and for entity id 1, there are two
+ * two columns, 'color' and 'shape', and for entity ID 1, there are two
* values: red/square and blue/circle. Entity ID 1 does not have values
* corresponding to 'red circle', however if you pass 'red' and 'circle' as
- * conditions, it will appear in the results - by default queries will run
+ * conditions, it will appear in the results -- by default queries will run
* against any combination of deltas. By passing the conditions with the
* same $delta_group it will ensure that only values attached to the same
* delta are matched, and entity 1 would then be excluded from the results.
--
GitLab