Submission Queries#

You can fetch submissions in your templates or PHP code using submission queries.

{# Create a new submission query #}
{% set myQuery = craft.formie.submissions() %}

// Create a new submission query
$myQuery = \verbb\formie\elements\Submission::find();

Once you’ve created a submission query, you can set parameters on it to narrow down the results, and then execute it by calling .all(). An array of Submission objects will be returned.

See Introduction to Element Queries (opens new window) in the Craft docs to learn about how element queries work.

Example#

We can display submissions for a given form by doing the following:

Create a submission query with craft.formie.submissions().
Set the form and limit parameters on it.
Fetch all submissions with .all() and output.
Loop through the submissions using a for (opens new window) tag to output the contents.

{# Create a submissions query with the 'form' and 'limit' parameters #}
{% set submissionsQuery = craft.formie.submissions()
    .form('contactForm')
    .limit(10) %}

{# Fetch the Submissions #}
{% set submissions = submissionsQuery.all() %}

{# Display their contents #}
{% for submission in submissions %}
    <p>{{ submission.title }}</p>
{% endfor %}

Parameters#

Submission queries support the following parameters:

Param	Description
anyStatus	Clears out the status
asArray	Causes the query to return matching submissions as arrays of data, rather than Submission objects.
dateCreated	Narrows the query results based on the submissions’ creation dates.
dateUpdated	Narrows the query results based on the submissions’ last-updated dates.
fixedOrder	Causes the query results to be returned in the order specified by id.
form	Narrows the query results based on the submissions’ types.
formId	Narrows the query results based on the submissions’ types, per the types’ IDs.
id	Narrows the query results based on the submissions’ IDs.
inReverse	Causes the query results to be returned in reverse order.
isIncomplete	Narrows the query results to only submissions that are incomplete.
isSpam	Narrows the query results to only submissions that are marked as spam.
limit	Determines the number of submissions that should be returned.
offset	Determines how many submissions should be skipped in the results.
orderBy	Determines the order that the submissions should be returned in. (If empty, defaults to `postDate DESC`.)
relatedTo	Narrows the query results to only submissions that are related to certain other elements.
status	Narrows the query results based on the submissions’ statuses.
statusId	Narrows the query results based on the submissions’ statuses, per their IDs.
title	Narrows the query results based on the submissions’ titles.
trashed	Narrows the query results to only submissions that have been soft-deleted.
user	Narrows the query results based on the submissions’ user.
userId	Narrows the query results based on the submissions’ userId.
uid	Narrows the query results based on the submissions’ UIDs.

`anyStatus`#

Clears out the status() (opens new window) and enabledForSite() (opens new window) parameters.

{# Fetch all submissions, regardless of status #}
{% set submissions = craft.formie.submissions()
    .anyStatus()
    .all() %}

// Fetch all submissions, regardless of status
$submissions = \verbb\formie\elements\Submission::find()
    ->anyStatus()
    ->all();

`asArray`#

Causes the query to return matching submissions as arrays of data, rather than Submission objects.

{# Fetch submissions as arrays #}
{% set submissions = craft.formie.submissions()
    .asArray()
    .all() %}

// Fetch submissions as arrays
$submissions = \verbb\formie\elements\Submission::find()
    ->asArray()
    ->all();

`dateCreated`#

Narrows the query results based on the submissions’ creation dates.

Possible values include:

Value	Fetches submissions…
`'>= 2018-04-01'`	that were created on or after 2018-04-01.
`'< 2018-05-01'`	that were created before 2018-05-01
`['and', '>= 2018-04-04', '< 2018-05-01']`	that were created between 2018-04-01 and 2018-05-01.

{# Fetch submissions created last month #}
{% set start = date('first day of last month') | atom %}
{% set end = date('first day of this month') | atom %}

{% set submissions = craft.formie.submissions()
    .dateCreated(['and', ">= #{start}", "< #{end}"])
    .all() %}

// Fetch submissions created last month
$start = new \DateTime('first day of next month')->format(\DateTime::ATOM);
$end = new \DateTime('first day of this month')->format(\DateTime::ATOM);

$submissions = \verbb\formie\elements\Submission::find()
    ->dateCreated(['and', ">= {$start}", "< {$end}"])
    ->all();

`dateUpdated`#

Narrows the query results based on the submissions’ last-updated dates.

Possible values include:

Value	Fetches submissions…
`'>= 2018-04-01'`	that were updated on or after 2018-04-01.
`'< 2018-05-01'`	that were updated before 2018-05-01
`['and', '>= 2018-04-04', '< 2018-05-01']`	that were updated between 2018-04-01 and 2018-05-01.

{# Fetch submissions updated in the last week #}
{% set lastWeek = date('1 week ago')|atom %}

{% set submissions = craft.formie.submissions()
    .dateUpdated(">= #{lastWeek}")
    .all() %}

// Fetch submissions updated in the last week
$lastWeek = new \DateTime('1 week ago')->format(\DateTime::ATOM);

$submissions = \verbb\formie\elements\Submission::find()
    ->dateUpdated(">= {$lastWeek}")
    ->all();

`fixedOrder`#

Causes the query results to be returned in the order specified by id.

{# Fetch submissions in a specific order #}
{% set submissions = craft.formie.submissions()
    .id([1, 2, 3, 4, 5])
    .fixedOrder()
    .all() %}

// Fetch submissions in a specific order
$submissions = \verbb\formie\elements\Submission::find()
    ->id([1, 2, 3, 4, 5])
    ->fixedOrder()
    ->all();

`form`#

Narrows the query results based on the submissions’ form.

Possible values include:

Value	Fetches submissions…
`'foo'`	for a form with a handle of `foo`.
`'not foo'`	not for a form with a handle of `foo`.
`['foo', 'bar']`	for a form with a handle of `foo` or `bar`.
`['not', 'foo', 'bar']`	not for a form with a handle of `foo` or `bar`.
a Form object	for a form represented by the object.

{# Fetch submissions from a Foo form #}
{% set submissions = craft.formie.submissions()
    .form('foo')
    .all() %}

// Fetch submissions from a Foo form
$submissions = \verbb\formie\elements\Submission::find()
    ->form('foo')
    ->all();

`formId`#

Narrows the query results based on the submissions’ form IDs.

Possible values include:

Value	Fetches submissions…
`1`	for a form with an ID of 1.
`'not 1'`	not for a form with an ID of 1.
`[1, 2]`	for a form with an ID of 1 or 2.
`['not', 1, 2]`	not for a form with an ID of 1 or 2.

{# Fetch submissions for the form with an ID of 1 #}
{% set submissions = craft.formie.submissions()
    .formId(1)
    .all() %}

// Fetch submissions for the form with an ID of 1
$submissions = \verbb\formie\elements\Submission::find()
    ->formId(1)
    ->all();

`id`#

Narrows the query results based on the submissions’ IDs.

Possible values include:

Value	Fetches submissions…
`1`	with an ID of 1.
`'not 1'`	not with an ID of 1.
`[1, 2]`	with an ID of 1 or 2.
`['not', 1, 2]`	not with an ID of 1 or 2.

{# Fetch the submission by its ID #}
{% set submission = craft.formie.submissions()
    .id(1)
    .one() %}

// Fetch the submission by its ID
$submission = \verbb\formie\elements\Submission::find()
    ->id(1)
    ->one();

This can be combined with fixedOrder if you want the results to be returned in a specific order.

`inReverse`#

Causes the query results to be returned in reverse order.

{# Fetch submissions in reverse #}
{% set submissions = craft.formie.submissions()
    .inReverse()
    .all() %}

// Fetch submissions in reverse
$submissions = \verbb\formie\elements\Submission::find()
    ->inReverse()
    ->all();

`isIncomplete`#

Narrows the query results to only submissions that are incomplete.

Possible values include:

Value	Fetches submissions…
`false` (default)	that are not incomplete.
`true`	that are incomplete.
`null`	that are either incomplete or not incomplete.

{# Fetch submissions that are incomplete #}
{% set submissions = craft.formie.submissions()
    .isIncomplete()
    .all() %}

// Fetch submissions that are incomplete
$submissions = \verbb\formie\elements\Submission::find()
    ->isIncomplete()
    ->all();

`isSpam`#

Narrows the query results to only submissions that are marked as spam.

Possible values include:

Value	Fetches submissions…
`false` (default)	that are not marked as spam.
`true`	that are marked as spam.
`null`	that are either marked as spam or not marked as spam.

{# Fetch submissions that is spam #}
{% set submissions = craft.formie.submissions()
    .isSpam()
    .all() %}

// Fetch submissions that is spam
$submissions = \verbb\formie\elements\Submission::find()
    ->isSpam()
    ->all();

`limit`#

Determines the number of submissions that should be returned.

{# Fetch up to 10 submissions  #}
{% set submissions = craft.formie.submissions()
    .limit(10)
    .all() %}

// Fetch up to 10 submissions
$submissions = \verbb\formie\elements\Submission::find()
    ->limit(10)
    ->all();

`offset`#

Determines how many submissions should be skipped in the results.

{# Fetch all submissions except for the first 3 #}
{% set submissions = craft.formie.submissions()
    .offset(3)
    .all() %}

// Fetch all submissions except for the first 3
$submissions = \verbb\formie\elements\Submission::find()
    ->offset(3)
    ->all();

`orderBy`#

Determines the order that the submissions should be returned in.

{# Fetch all submissions in order of date created #}
{% set submissions = craft.formie.submissions()
    .orderBy('elements.dateCreated asc')
    .all() %}

// Fetch all submissions in order of date created
$submissions = \verbb\formie\elements\Submission::find()
    ->orderBy('elements.dateCreated asc')
    ->all();

`relatedTo`#

Narrows the query results to only submissions that are related to certain other elements.

See Relations (opens new window) for a full explanation of how to work with this parameter.

{# Fetch all submissions that are related to myCategory #}
{% set submissions = craft.formie.submissions()
    .relatedTo(myCategory)
    .all() %}

// Fetch all submissions that are related to $myCategory
$submissions = \verbb\formie\elements\Submission::find()
    ->relatedTo($myCategory)
    ->all();

`status`#

Narrows the query results based on the submissions’ statuses.

Possible values include:

Value	Fetches submissions…
`'live'` (default)	that are live.
`'pending'`	that are pending (enabled with a Post Date in the future).
`'expired'`	that are expired (enabled with an Expiry Date in the past).
`'disabled'`	that are disabled.
`['live', 'pending']`	that are live or pending.

{# Fetch disabled submissions #}
{% set submissions = craft.formie.submissions()
    .status('disabled')
    .all() %}

// Fetch disabled submissions
$submissions = \verbb\formie\elements\Submission::find()
    ->status('disabled')
    ->all();

`statusId`#

Narrows the query results based on the submission statuses, per their IDs.

Possible values include:

Value	Fetches submissions…
`1`	with a status with an ID of 1.
`'not 1'`	not with a status with an ID of 1.
`[1, 2]`	with a status with an ID of 1 or 2.
`['not', 1, 2]`	not with a status with an ID of 1 or 2.

{# Fetch submissions with a status with an ID of 1 #}
{% set submissions = craft.formie.submissions()
    .statusId(1)
    .all() %}

// Fetch submissions with a status with an ID of 1
$submissions = \verbb\formie\elements\Submission::find()
    ->statusId(1)
    ->all();

`title`#

Narrows the query results based on the submissions’ titles.

Possible values include:

Value	Fetches submissions…
`'Foo'`	with a title of `Foo`.
`'Foo*'`	with a title that begins with `Foo`.
`'*Foo'`	with a title that ends with `Foo`.
`'Foo'`	with a title that contains `Foo`.
`'not Foo'`	with a title that doesn’t contain `Foo`.
`['Foo', 'Bar'`	with a title that contains `Foo` or `Bar`.
`['not', 'Foo', 'Bar']`	with a title that doesn’t contain `Foo` or `Bar`.

{# Fetch submissions with a title that contains "Foo" #}
{% set submissions = craft.formie.submissions()
    .title('*Foo*')
    .all() %}

// Fetch submissions with a title that contains "Foo"
$submissions = \verbb\formie\elements\Submission::find()
    ->title('*Foo*')
    ->all();

`trashed`#

Narrows the query results to only submissions that have been soft-deleted.

{# Fetch trashed submissions #}
{% set entries = craft.formie.submissions()
    .trashed()
    .all() %}

// Fetch trashed submissions
$submissions = \verbb\formie\elements\Submission::find()
    ->trashed()
    ->all();

`uid`#

Narrows the query results based on the submissions’ UIDs.

{# Fetch the submission by its UID #}
{% set submission = craft.formie.submissions()
    .uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
    .one() %}

// Fetch the submission by its UID
$submission = \verbb\formie\elements\Submission::find()
    ->uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
    ->one();

`user`#

Narrows the query results based on the submission owner user.

{# Fetch submissions for the current user #}
{% set submissions = craft.formie.submissions()
    .user(currentUser)
    .all() %}

// Fetch submissions for the current user
$submissions = \verbb\formie\elements\Submission::find()
    ->user($currentUser)
    ->all();

`userId`#

Narrows the query results based on the submission owner user, per their IDs.

Possible values include:

Value	Fetches submissions…
`1`	with a user ID of 1.
`'not 1'`	not with a user ID of 1.
`[1, 2]`	with a user ID of 1 or 2.
`['not', 1, 2]`	not with a user ID of 1 or 2.

{# Fetch submissions with a user ID of 1 #}
{% set submissions = craft.formie.submissions()
    .userId(1)
    .all() %}

// Fetch submissions with a user ID of 1
$submissions = \verbb\formie\elements\Submission::find()
    ->userId(1)
    ->all();

Previous ← Form Queries Next Address Providers →

Get Started

Feature Tour

Template Guides

Getting Elements

Integrations

Developers

Guides

Submission Queries#

Example#

Parameters#

`anyStatus`#

`asArray`#

`dateCreated`#

`dateUpdated`#

`fixedOrder`#

`form`#

`formId`#

`id`#

`inReverse`#

`isIncomplete`#

`isSpam`#

`limit`#

`offset`#

`orderBy`#

`relatedTo`#

`status`#

`statusId`#

`title`#

`trashed`#

`uid`#

`user`#

`userId`#

On this page

Get Started

Feature Tour

Template Guides

Getting Elements

Integrations

Developers

Guides

​Submission Queries#

​Example#

​Parameters#

​anyStatus#

​asArray#

​dateCreated#

​dateUpdated#

​fixedOrder#

​form#

​formId#

​id#

​inReverse#

​isIncomplete#

​isSpam#

​limit#

​offset#

​orderBy#

​relatedTo#

​status#

​statusId#

​title#

​trashed#

​uid#

​user#

​userId#

On this page

Submission Queries#

Example#

Parameters#

`anyStatus`#

`asArray`#

`dateCreated`#

`dateUpdated`#

`fixedOrder`#

`form`#

`formId`#

`id`#

`inReverse`#

`isIncomplete`#

`isSpam`#

`limit`#

`offset`#

`orderBy`#

`relatedTo`#

`status`#

`statusId`#

`title`#

`trashed`#

`uid`#

`user`#

`userId`#