Event Queries#

You can fetch events in your templates or PHP code using event queries.

{# Create a new event query #}
{% set myQuery = craft.events.events() %}
// Create a new event query
$myQuery = \verbb\events\elements\Event::find();

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

  1. Create an event query with craft.events.events().
  2. Set the type and limit parameters on it.
  3. Fetch all events with .all() and output.
  4. Loop through the events using a for (opens new window) tag to output the contents.
{# Create a events query with the 'type' and 'limit' parameters #}
{% set eventsQuery = craft.events.events()
    .type('generalEvents')
    .limit(10) %}

{# Fetch the Events #}
{% set events = eventsQuery.all() %}

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

By default, only current events will be returned when calling craft.events.events(). To change this, use craft.events.events({ endDate: null }). Events are also ordered from the oldest startDate to the newest, which you can also change with the orderBy parameter.

Parameters#

Event queries support the following parameters:

after#

Narrows the query results to only events that were posted on or after a certain date.

Possible values include:

ValueFetches events…
'2018-04-01'that were posted after 2018-04-01.
a DateTime (opens new window) objectthat were posted after the date represented by the object.
{# Fetch events posted this month #}
{% set firstDayOfMonth = date('first day of this month') %}

{% set events = craft.events.events()
    .after(firstDayOfMonth)
    .all() %}
// Fetch events posted this month
$firstDayOfMonth = new \DateTime('first day of this month');

$events = \verbb\events\elements\Event::find()
    ->after($firstDayOfMonth)
    ->all();

anyStatus#

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

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

asArray#

Causes the query to return matching events as arrays of data, rather than Event objects.

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

before#

Narrows the query results to only events that were posted before a certain date.

Possible values include:

ValueFetches events…
'2018-04-01'that were posted before 2018-04-01.
a DateTime (opens new window) objectthat were posted before the date represented by the object.
{# Fetch events posted before this month #}
{% set firstDayOfMonth = date('first day of this month') %}

{% set events = craft.events.events()
    .before(firstDayOfMonth)
    .all() %}
// Fetch events posted before this month
$firstDayOfMonth = new \DateTime('first day of this month');

$events = \verbb\events\elements\Event::find()
    ->before($firstDayOfMonth)
    ->all();

customer#

Narrows the query results to only events that have been purchased by a customer.

{# Fetch events that have been purchased by a customer #}
{% set events = craft.events.events()
    .customer(craft.commerce.getCarts().getCart().customer)
    .all() %}
// Fetch events that have been purchased by a customer
$events = \verbb\events\elements\Event::find()
    ->customer($customer)
    ->all();

dateCreated#

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

Possible values include:

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

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

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

dateUpdated#

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

Possible values include:

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

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

$events = \verbb\events\elements\Event::find()
    ->dateUpdated(">= {$lastWeek}")
    ->all();

endDate#

Narrows the query results based on the events’ end date.

Possible values include:

ValueFetches events…
'>= 2018-04-01'that has an end date on or after 2018-04-01.
'< 2018-05-01'that has an end date before 2018-05-01
['and', '>= 2018-04-04', '< 2018-05-01']that has an end date between 2018-04-01 and 2018-05-01.
{# Fetch events finishing after today #}
{% set end = date('today') | atom %}

{% set events = craft.events.events()
    .endDate(">= #{end}")
    .all() %}
// Fetch events created last month
$end = new \DateTime('today')->format(\DateTime::ATOM);

$events = \verbb\events\elements\Event::find()
    ->endDate(">= {$end}"])
    ->all();

expiryDate#

Narrows the query results based on the events’ expiry dates.

Possible values include:

ValueFetches events…
'>= 2020-04-01'that will expire on or after 2020-04-01.
'< 2020-05-01'that will expire before 2020-05-01
['and', '>= 2020-04-04', '< 2020-05-01']that will expire between 2020-04-01 and 2020-05-01.
{# Fetch events expiring this month #}
{% set nextMonth = date('first day of next month')|atom %}

{% set events = craft.events.events()
    .expiryDate("< #{nextMonth}")
    .all() %}
// Fetch events expiring this month
$nextMonth = new \DateTime('first day of next month')->format(\DateTime::ATOM);

$events = \verbb\events\elements\Event::find()
    ->expiryDate("< {$nextMonth}")
    ->all();

fixedOrder#

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

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

hasTicket#

Narrows the query results to only events that have certain tickets.

Possible values include:

ValueFetches events…
a TicketQuery objectwith tickets that match the query.

id#

Narrows the query results based on the events’ IDs.

Possible values include:

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

limit#

Determines the number of events that should be returned.

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

offset#

Determines how many events should be skipped in the results.

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

orderBy#

Determines the order that the events should be returned in.

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

postDate#

Narrows the query results based on the events’ post dates.

Possible values include:

ValueFetches events…
'>= 2018-04-01'that were posted on or after 2018-04-01.
'< 2018-05-01'that were posted before 2018-05-01
['and', '>= 2018-04-04', '< 2018-05-01']that were posted between 2018-04-01 and 2018-05-01.
{# Fetch events posted last month #}
{% set start = date('first day of last month')|atom %}
{% set end = date('first day of this month')|atom %}

{% set events = craft.events.events()
    .postDate(['and', ">= #{start}", "< #{end}"])
    .all() %}
// Fetch events posted last month
$start = new \DateTime('first day of next month')->format(\DateTime::ATOM);
$end = new \DateTime('first day of this month')->format(\DateTime::ATOM);

$events = \verbb\events\elements\Event::find()
    ->postDate(['and', ">= {$start}", "< {$end}"])
    ->all();

relatedTo#

Narrows the query results to only events 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 events that are related to myCategory #}
{% set events = craft.events.events()
    .relatedTo(myCategory)
    .all() %}
// Fetch all events that are related to $myCategory
$events = \verbb\events\elements\Event::find()
    ->relatedTo($myCategory)
    ->all();

Narrows the query results to only events 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 events that match the search query #}
{% set events = craft.events.events()
    .search(searchQuery)
    .all() %}
// Get the search query from the 'q' query string param
$searchQuery = \Craft::$app->getRequest()->getQueryParam('q');

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

site#

Determines which site the events should be queried in.

The current site will be used by default.

Possible values include:

ValueFetches events…
'foo'from the site with a handle of foo.
a \craft\commerce\elements\db\Site objectfrom the site represented by the object.
{# Fetch events from the Foo site #}
{% set events = craft.events.events()
    .site('foo')
    .all() %}
// Fetch events from the Foo site
$events = \verbb\events\elements\Event::find()
    ->site('foo')
    ->all();

siteId#

Determines which site the events should be queried in, per the site’s ID.

The current site will be used by default.

{# Fetch events from the site with an ID of 1 #}
{% set events = craft.events.events()
    .siteId(1)
    .all() %}
// Fetch events from the site with an ID of 1
$events = \verbb\events\elements\Event::find()
    ->siteId(1)
    ->all();

slug#

Narrows the query results based on the events’ slugs.

Possible values include:

ValueFetches events…
'foo'with a slug of foo.
'foo*'with a slug that begins with foo.
'*foo'with a slug that ends with foo.
'*foo*'with a slug that contains foo.
'not *foo*'with a slug that doesn’t contain foo.
['*foo*', '*bar*'with a slug that contains foo or bar.
['not', '*foo*', '*bar*']with a slug that doesn’t contain foo or bar.
{# Get the requested event slug from the URL #}
{% set requestedSlug = craft.app.request.getSegment(3) %}

{# Fetch the event with that slug #}
{% set event = craft.events.events()
    .slug(requestedSlug|literal)
    .one() %}
// Get the requested event slug from the URL
$requestedSlug = \Craft::$app->getRequest()->getSegment(3);

// Fetch the event with that slug
$event = \verbb\events\elements\Event::find()
    ->slug(\craft\helpers\Db::escapeParam($requestedSlug))
    ->one();

startDate#

Narrows the query results based on the events’ start date.

Possible values include:

ValueFetches events…
'>= 2018-04-01'that has a start date on or after 2018-04-01.
'< 2018-05-01'that has a start date before 2018-05-01
['and', '>= 2018-04-04', '< 2018-05-01']that has a start date between 2018-04-01 and 2018-05-01.
{# Fetch events from today onwards #}
{% set start = date('today') | atom %}

{% set events = craft.events.events()
    .startDate(">= #{start}")
    .all() %}
// Fetch events created last month
$start = new \DateTime('today')->format(\DateTime::ATOM);

$events = \verbb\events\elements\Event::find()
    ->startDate(">= {$start}"])
    ->all();

status#

Narrows the query results based on the events’ statuses.

Possible values include:

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

title#

Narrows the query results based on the events’ titles.

Possible values include:

ValueFetches events…
'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 events with a title that contains "Foo" #}
{% set events = craft.events.events()
    .title('*Foo*')
    .all() %}
// Fetch events with a title that contains "Foo"
$events = \verbb\events\elements\Event::find()
    ->title('*Foo*')
    ->all();

type#

Narrows the query results based on the events’ types.

Possible values include:

ValueFetches events…
'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.
an Event Type objectof a type represented by the object.
{# Fetch events with a Foo event type #}
{% set events = craft.events.events()
    .type('foo')
    .all() %}
// Fetch events with a Foo event type
$events = \verbb\events\elements\Event::find()
    ->type('foo')
    ->all();

typeId#

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

Possible values include:

ValueFetches events…
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 events of the event type with an ID of 1 #}
{% set events = craft.events.events()
    .typeId(1)
    .all() %}
// Fetch events of the event type with an ID of 1
$events = \verbb\events\elements\Event::find()
    ->typeId(1)
    ->all();

uid#

Narrows the query results based on the events’ UIDs.

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

uri#

Narrows the query results based on the events’ URIs.

Possible values include:

ValueFetches events…
'foo'with a URI of foo.
'foo*'with a URI that begins with foo.
'*foo'with a URI that ends with foo.
'*foo*'with a URI that contains foo.
'not *foo*'with a URI that doesn’t contain foo.
['*foo*', '*bar*'with a URI that contains foo or bar.
['not', '*foo*', '*bar*']with a URI that doesn’t contain foo or bar.
{# Get the requested URI #}
{% set requestedUri = craft.app.request.getPathInfo() %}

{# Fetch the event with that URI #}
{% set event = craft.events.events()
    .uri(requestedUri|literal)
    .one() %}
// Get the requested URI
$requestedUri = \Craft::$app->getRequest()->getPathInfo();

// Fetch the event with that URI
$event = \verbb\events\elements\Event::find()
    ->uri(\craft\helpers\Db::escapeParam($requestedUri))
    ->one();

with#

Causes the query to return matching events eager-loaded with related elements.

See Eager-Loading Elements (opens new window) for a full explanation of how to work with this parameter.

{# Fetch events eager-loaded with the "Related" field’s relations #}
{% set events = craft.events.events()
    .with(['related'])
    .all() %}
// Fetch events eager-loaded with the "Related" field’s relations
$events = \verbb\events\elements\Event::find()
    ->with(['related'])
    ->all();

Previous ← ICS Exporting Next Ticket Queries →