Introduction
The GFAPI::entry_exists()
, GFAPI::get_entry()
, GFAPI::get_entries()
, GFAPI::get_entry_ids()
, and GFAPI::count_entries()
methods are used to search, count, get, and check if entries exist.
Checking if a specific entry exists
The GFAPI::entry_exists()
method is used to check if an entry exists with a specific ID.
Source Code
public static function entry_exists( $entry_id ) {}
This method is located in /includes/api.php.
Parameters
Param | Type | Description |
---|---|---|
$entry_id | integer | The ID of the entry to check. |
Returns
Boolean. true
if the entry exists. false
if the entry doesn’t exist.
Usage Example
$result = GFAPI::entry_exists( $entry_id );
Getting a specific entry
The GFAPI::get_entry()
method is used to get an entry by it’s ID.
Source Code
public static function get_entry( $entry_id ) {}
This method is located in /includes/api.php.
Parameters
Param | Type | Description |
---|---|---|
$entry_id | integer | The ID of the entry to retrieve. |
Returns
An array (Entry Object), if the entry exists. Boolean, false, if an error occurs.
Usage Example
$result = GFAPI::get_entry( $entry_id );
Searching entries
The GFAPI::get_entries()
and GFAPI::get_entry_ids()
methods are used to find entries that match the given arguments.
Source Code
public static function get_entries( $form_ids, $search_criteria = array(), $sorting = null, $paging = null, &$total_count = null ) {}
public static function get_entry_ids( $form_ids, $search_criteria = array(), $sorting = null, $paging = null, &$total_count = null ) {}
These method are located in /includes/api.php.
Parameters
Param | Type | Description |
---|---|---|
$form_ids | integer|array | 0 to search all forms or a form ID to search a specific form or an array of form IDs to search only the specified forms. |
$search_criteria | array | Optional. An associative array containing the search arguments. |
$sorting | array | Optional. An associative array containing the sorting arguments. |
$paging | null|array | Optional. An associative array containing the paging arguments. IMPORTANT TIP: use paging to limit the number of entries otherwise you may find the database times out. |
&$total_count | null|integer | Optional. An output parameter containing the total number of entries found to match the given arguments. Pass a non- null value, such as 0 , to get the total count. |
Returns
GFAPI::get_entries()
returns an array of entries (Entry Objects) that match the given arguments or an empty array.
GFAPI::get_entry_ids()
returns an array of IDs (integers) that match the given arguments or an empty array.
Usage Examples
Basic usage
This example shows how to find the 20 most recent entries for a specific form.
// Getting the entries
$result = GFAPI::get_entries( $form_id );
// Getting just the IDs
$result = GFAPI::get_entry_ids( $form_id );
Two field filters
This example shows how to get the 20 most recent entries for a specific form that match at least one of two field filters.
$search_criteria = array(
'status' => 'active',
'field_filters' => array(
'mode' => 'any',
array(
'key' => '1',
'value' => 'Second Choice'
),
array(
'key' => '5',
'value' => 'My text'
)
)
);
// Getting the entries
$result = GFAPI::get_entries( $form_id, $search_criteria );
// Getting just the IDs
$result = GFAPI::get_entry_ids( $form_id, $search_criteria );
Sorting
This example shows how to sort the found entries by a specific field.
$search_criteria = array();
$sorting = array( 'key' => '5', 'direction' => 'ASC' );
$results = GFAPI::get_entries( $form_id, $search_criteria, $sorting );
Paging
This example shows how to increase the page size.
$search_criteria = array();
$sorting = array();
$paging = array( 'offset' => 0, 'page_size' => 25 );
$results = GFAPI::get_entries( $form_id, $search_criteria, $sorting, $paging );
Getting the total count
This example shows how to get the total number of entries that match the given criteria.
$search_criteria = array();
$sorting = array();
$paging = array( 'offset' => 0, 'page_size' => 25 );
$total_count = 0;
$results = GFAPI::get_entries( $form_id, $search_criteria, $sorting, $paging, $total_count );
When the found entries are returned, up to the page size, the $total_count
is populated with the total number of found entries. If the total exceeds the number of returned entries you’ll know you need to make further requests adjusting the offset
property of the $paging
argument.
Getting entries from the last 30 days
This example shows how to get 20 entries submitted in the last 30 days.
$search_criteria = array();
$form_id = 4;
$start_date = date( 'Y-m-d', strtotime('-30 days') );
$end_date = date( 'Y-m-d', time() );
$search_criteria['start_date'] = $start_date;
$search_criteria['end_date'] = $end_date;
$results = GFAPI::get_entries( $form_id, $search_criteria );
Counting entries
The GFAPI::count_entries()
method is used to get a count of all entries that match the given arguments.
Source Code
public static function count_entries( $form_ids, $search_criteria = array() ) {}
This method is located in /includes/api.php.
Parameters
Param | Type | Description |
---|---|---|
$form_ids | integer|array | 0 to search all forms.A form ID to search a specific form. An array of form IDs to search only the specified forms. |
$search_criteria | array | Optional. An associative array containing the search arguments. |
Returns
An integer, the total number of entries that match the given arguments.
Usage Example
$result = GFAPI::count_entries( $form_ids, $search_criteria );
Common Parameters
Search Arguments
An associative array supporting the following properties.
Prop | Type | Description |
---|---|---|
status | string | The entry status property. Possible values: active , spam , or trash |
start_date | string | Optional. Recommended format: Y-m-d H:i:s The date of the oldest entry. Compared with the entry date_created property. The time defaults to 00:00:00 if not included. |
end_date | string | Optional. Recommended format: Y-m-d H:i:s The end date to be compared with the entry date_created property. The time defaults to 23:59:59 if not included. |
field_filters | array | Optional. See Field Filters |
$search_criteria = array();
// Filtering by status.
$search_criteria['status'] = 'active';
// Filtering by entry properties, meta, and/or field values.
$search_criteria['field_filters'] = array();
// Filtering by date range.
$search_criteria['start_date'] = $start_date;
$search_criteria['end_date'] = $end_date;
Field Filters
Prop | Type | Description |
---|---|---|
array | One or more associative arrays. See Field Filter. | |
mode | string | Optional. Defaults to all .Possible values: all or any .Determines if the found entries have to match all the field filters or any. |
$search_criteria['field_filters'] = array();
// Filtering by entry properties, meta, and/or field values.
$search_criteria['field_filters'][] = $filter;
// Changing the mode.
$search_criteria['field_filters']['mode'] = 'any';
Field Filter
An associative array supporting the following properties.
Prop | Type | Description |
---|---|---|
key | string | The field ID, entry property, or entry meta key. |
value | string|integer|float|array | The value to find for the specified key . |
operator | string | Optional. Defaults to = .Possible values: = , IS , CONTAINS , IS NOT , ISNOT , <> , LIKE , NOT IN , NOTIN , or IN .Lowercase is also supported. |
is_numeric | boolean | Optional. Indicates if the values of the specified key are numeric. |
// Filtering by entry properties.
$search_criteria['field_filters'][] = array( 'key' => 'currency', 'value' => 'USD' );
$search_criteria['field_filters'][] = array( 'key' => 'is_read', 'value' => true );
$search_criteria['field_filters'][] = array( 'key' => 'created_by', 'value' => get_current_user_id() );
// Filtering by field values.
$search_criteria['field_filters'][] = array( 'key' => '1', 'value' => 'gquiz159982170' );
// Supported operators for scalar values: is/=, isnot, contains.
$search_criteria['field_filters'][] = array( 'key' => '1', 'operator' => 'contains', 'value' => 'Steve' );
// Supported operators for array values: in/=, not in/!=
$search_criteria['field_filters'][] = array( 'key' => '1', 'operator' => 'not in', 'value' => array( 'Alex', 'David', 'Dana' ) );
// Filter by a checkbox value (not recommended).
$search_criteria['field_filters'][] = array( 'key' => '2.2', 'value' => 'gquiz246fec995' );
// Notes
// Using input IDs as search keys will work for checkboxes but it won't work if the checkboxes have been re-ordered since the first submission.
// The 'not in' operator is not currently supported for checkbox values.
// Filter by a checkbox value (recommended).
$search_criteria['field_filters'][] = array( 'key' => '2', 'value' => 'gquiz246fec995' );
$search_criteria['field_filters'][] = array( 'key' => '2', 'operator' => 'in', 'value' => array( 'First Choice', 'Third Choice' ) );
// Note
// Neither 'not in' nor '' operators are not currently supported for checkboxes using field IDs as search keys.
// Filter by a global/free-form search of values of any form field.
$search_criteria['field_filters'][] = array( 'value' => $search_value );
// OR
$search_criteria['field_filters'][] = array( 'key' => 0, 'value' => $search_value );
// Filter entries by Entry meta (added using the gform_entry_meta hook).
$search_criteria['field_filters'][] = array( 'key' => 'gquiz_score', 'value' => '1' );
$search_criteria['field_filters'][] = array( 'key' => 'gquiz_is_pass', 'value' => '1' );
Sorting Arguments
An associative array supporting the following properties.
Prop | Type | Description |
---|---|---|
key | string | Optional. The field ID, entry property, or entry meta key to sort the results. Default: id |
direction | string | Optional. The direction to sort the results. Accepted values: ASC , DESC , or RAND .Default: DESC |
is_numeric | boolean | Optional. Indicates if the values of the specified key are numeric. |
$sorting = array( 'key' => $sort_field, 'direction' => 'ASC', 'is_numeric' => true );
Paging Arguments
An associative array supporting the following properties.
Prop | Type | Description |
---|---|---|
offset | integer | Optional. The row to start from when retreiving the results. Default: 0 |
page_size | integer | Optional. The maximum number of results to return. Default: 20 |
$paging = array( 'offset' => 0, 'page_size' => 30 );