Searching and Getting Entries with the GFAPI

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

ParamTypeDescription
$entry_idintegerThe 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

ParamTypeDescription
$entry_idintegerThe 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

ParamTypeDescription
$form_idsinteger|array0 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_criteriaarrayOptional.
An associative array containing the search arguments.
$sortingarray Optional.
An associative array containing the sorting arguments.
$pagingnull|arrayOptional.
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_countnull|integerOptional.
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

ParamTypeDescription
$form_idsinteger|array0 to search all forms.
A form ID to search a specific form.
An array of form IDs to search only the specified forms.
$search_criteriaarrayOptional.
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.

PropTypeDescription
statusstringThe entry status property.
Possible values: active, spam, or trash
start_datestringOptional.
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_datestringOptional.
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_filtersarrayOptional.
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

PropTypeDescription
arrayOne or more associative arrays. See Field Filter.
modestringOptional.
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.

PropTypeDescription
keystringThe field ID, entry property, or entry meta key.
valuestring|integer|float|arrayThe value to find for the specified key.
operatorstringOptional.
Defaults to =.
Possible values: =, IS, CONTAINS, IS NOT, ISNOT, <>, LIKE, NOT IN, NOTIN, or IN.
Lowercase is also supported.
is_numericbooleanOptional.
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.

PropTypeDescription
keystringOptional.
The field ID, entry property, or entry meta key to sort the results.
Default: id
directionstringOptional.
The direction to sort the results.
Accepted values: ASC, DESC, or RAND.
Default: DESC
is_numericbooleanOptional.
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.

PropTypeDescription
offsetintegerOptional.
The row to start from when retreiving the results.
Default: 0
page_sizeintegerOptional.
The maximum number of results to return.
Default: 20
$paging = array( 'offset' => 0, 'page_size' => 30 );