List Queries#

You can fetch lists in your templates or PHP code using list queries.

{# Create a new list query #}
{% set myQuery = craft.wishlist.lists() %}
// Create a new list query
$myQuery = \verbb\wishlist\elements\ListElement::find();

Once you’ve created a list query, you can set parameters on it to narrow down the results, and then execute it by calling .all(). An array of List 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 lists for a given user by doing the following:

  1. Create a list query with craft.wishlist.lists().
  2. Set the typeId, limit and status parameters on it.
  3. Fetch all lists with .all() and output.
  4. Loop through the lists using a for (opens new window) tag to output the contents.
{# Create a lists query with the 'typeId', 'limit', and 'status' parameters #}
{% set listsQuery = craft.wishlist.lists()
    .typeId(1)
    .limit(10)
    .status(true) %}

{# Fetch the Lists #}
{% set lists = listsQuery.all() %}

{# Display their contents #}
{% for list in lists %}
    <p>{{ list.list }}</p>
{% endfor %}

Parameters#

List queries support the following parameters:

anyStatus#

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

{# Fetch all lists, regardless of status #}
{% set lists = craft.wishlist.lists()
    .anyStatus()
    .all() %}
// Fetch all lists, regardless of status
$lists = \verbb\wishlist\elements\ListElement::find()
    ->anyStatus()
    ->all();

asArray#

Causes the query to return matching lists as arrays of data, rather than List objects.

{# Fetch lists as arrays #}
{% set lists = craft.wishlist.lists()
    .asArray()
    .all() %}
// Fetch lists as arrays
$lists = \verbb\wishlist\elements\ListElement::find()
    ->asArray()
    ->all();

dateCreated#

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

Possible values include:

ValueFetches lists…
'>= 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 lists created last month #}
{% set start = date('first day of last month') | atom %}
{% set end = date('first day of this month') | atom %}

{% set lists = craft.wishlist.lists()
    .dateCreated(['and', ">= #{start}", "< #{end}"])
    .all() %}
// Fetch lists 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);

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

dateUpdated#

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

Possible values include:

ValueFetches lists…
'>= 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 lists updated in the last week #}
{% set lastWeek = date('1 week ago')|atom %}

{% set lists = craft.wishlist.lists()
    .dateUpdated(">= #{lastWeek}")
    .all() %}
// Fetch lists updated in the last week
$lastWeek = new \DateTime('1 week ago')->format(\DateTime::ATOM);

$lists = \verbb\wishlist\elements\ListElement::find()
    ->dateUpdated(">= {$lastWeek}")
    ->all();

default#

Fetch the list that is set as the default.

{# Fetch list that is the default #}
{% set list = craft.wishlist.lists()
    .default(true)
    .one() %}
// Fetch list that is the default
$list = \verbb\wishlist\elements\ListElement::find()
    ->default(true)
    ->one();

fixedOrder#

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

{# Fetch lists in a specific order #}
{% set lists = craft.wishlist.lists()
    .id([1, 2, 3, 4, 5])
    .fixedOrder()
    .all() %}
// Fetch lists in a specific order
$lists = \verbb\wishlist\elements\ListElement::find()
    ->id([1, 2, 3, 4, 5])
    ->fixedOrder()
    ->all();

id#

Narrows the query results based on the lists’ IDs.

Possible values include:

ValueFetches lists…
1with 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 list by its ID #}
{% set list = craft.wishlist.lists()
    .id(1)
    .one() %}
// Fetch the list by its ID
$list = \verbb\wishlist\elements\ListElement::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 lists in reverse #}
{% set lists = craft.wishlist.lists()
    .inReverse()
    .all() %}
// Fetch lists in reverse
$lists = \verbb\wishlist\elements\ListElement::find()
    ->inReverse()
    ->all();

limit#

Determines the number of lists that should be returned.

{# Fetch up to 10 lists  #}
{% set lists = craft.wishlist.lists()
    .limit(10)
    .all() %}
// Fetch up to 10 lists
$lists = \verbb\wishlist\elements\ListElement::find()
    ->limit(10)
    ->all();

offset#

Determines how many lists should be skipped in the results.

{# Fetch all lists except for the first 3 #}
{% set lists = craft.wishlist.lists()
    .offset(3)
    .all() %}
// Fetch all lists except for the first 3
$lists = \verbb\wishlist\elements\ListElement::find()
    ->offset(3)
    ->all();

orderBy#

Determines the order that the lists should be returned in.

{# Fetch all lists in order of date created #}
{% set lists = craft.wishlist.lists()
    .orderBy('elements.dateCreated asc')
    .all() %}
// Fetch all lists in order of date created
$lists = \verbb\wishlist\elements\ListElement::find()
    ->orderBy('elements.dateCreated asc')
    ->all();

reference#

Narrows the query results based on the list reference number.

Possible values include:

ValueFetches lists…
'••••••••••••••'with a matching list reference number
{# Fetch the requested order #}
{% set reference = craft.app.request.getQueryParam('reference') %}

{% set lists = craft.wishlist.lists()
    .reference(reference)
    .one() %}
// Fetch the requested order
$reference = Craft::$app->getRequest()->getQueryParam('reference');

$lists = \verbb\wishlist\elements\ListElement::find()
    ->reference($reference)
    ->one();

Narrows the query results to only lists that match a search query.

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

{# Get the search query from the 'q' query string param #}
{% set searchQuery = craft.app.request.getQueryParam('q') %}

{# Fetch all lists that match the search query #}
{% set lists = craft.wishlist.lists()
    .search(searchQuery)
    .all() %}
// Get the search query from the 'q' query string param
$searchQuery = \Craft::$app->getRequest()->getQueryParam('q');

// Fetch all lists that match the search query
$lists = \verbb\wishlist\elements\ListElement::find()
    ->search($searchQuery)
    ->all();

sessionId#

Narrows the query results based on the lists’ owners’ session ID.

{# Fetch lists by the owners’ session ID #}
{% set lists = craft.wishlist.lists()
    .sessionId('••••••••••••••')
    .all() %}
// Fetch lists by the owners’ session ID
$lists = \verbb\wishlist\elements\ListElement::find()
    .sessionId('••••••••••••••')
    ->all();

status#

Narrows the query results based on the lists’ statuses.

Possible values include:

ValueFetches lists…
'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 lists #}
{% set lists = craft.wishlist.lists()
    .status('disabled')
    .all() %}
// Fetch disabled lists
$lists = \verbb\wishlist\elements\ListElement::find()
    ->status('disabled')
    ->all();

type#

Narrows the query results based on the lists’ types.

Possible values include:

ValueFetches lists…
'foo'of a type with a handle of foo.
'not foo'not of a type with a handle of foo.
['foo', 'bar']of a type with a handle of foo or bar.
['not', 'foo', 'bar']not of a type with a handle of foo or bar.
a List Type objectof a type represented by the object.
{# Fetch lists with a Foo list type #}
{% set lists = craft.wishlist.lists()
    .type('foo')
    .all() %}
// Fetch lists with a Foo list type
$lists = \verbb\wishlist\elements\ListElement::find()
    ->type('foo')
    ->all();

typeId#

Narrows the query results based on the lists’ types, per the types’ IDs.

Possible values include:

ValueFetches lists…
1of a type with an ID of 1.
'not 1'not of a type with an ID of 1.
[1, 2]of a type with an ID of 1 or 2.
['not', 1, 2]not of a type with an ID of 1 or 2.
{# Fetch lists of the list type with an ID of 1 #}
{% set lists = craft.wishlist.lists()
    .typeId(1)
    .all() %}
// Fetch lists of the list type with an ID of 1
$lists = \verbb\wishlist\elements\ListElement::find()
    ->typeId(1)
    ->all();

uid#

Narrows the query results based on the lists’ UIDs.

{# Fetch the list by its UID #}
{% set list = craft.wishlist.lists()
    .uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
    .one() %}
// Fetch the list by its UID
$list = \verbb\wishlist\elements\ListElement::find()
    ->uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
    ->one();

userId#

Narrows the query results based on the lists’ users, per the users’ IDs.

Possible values include:

ValueFetches lists…
1of a user with an ID of 1.
'not 1'not of a user with an ID of 1.
[1, 2]of a user with an ID of 1 or 2.
['not', 1, 2]not of a user with an ID of 1 or 2.
{# Fetch lists of the user with an ID of 1 #}
{% set lists = craft.wishlist.lists()
    .userId(1)
    .all() %}
// Fetch lists of the user with an ID of 1
$lists = \verbb\wishlist\elements\ListElement::find()
    ->userId(1)
    ->all();

Previous ← PDF Template Next Item Queries →