Query Events Examples
This document is intended to demonstrate how each available argument can be used when querying the events in the database using the ORM. The ORM ->where() and ->by() options build SQL queries under the hood and return an array of events in the form of WP Post Objects.
Date Based Arguments
All arguments accept an additional optional parameter to specify the timezone, defaults to the site’s timezone setting which can be a timezone string, UTC offset, or DateTimeZone object.
'starts_before'
$results = tribe_events()->where( 'starts_before' , '-1 day' );Filters events whose start date occurs before the provided date using the filter_by_starts_before() function. An acceptable parameter can be a strtotime parseable string, a DateTime object, or a timestamp. Unaccepted parameters will result in the parameter defaulting to the current date.
Fetch is not inclusive, meaning if the event start date/time matches the query parameter exactly, it will not be included in the returned results.
'starts_after'
$results = tribe_events()->where( 'starts_after' , '01 January 2024' );Filters events whose start date occurs after the provided date using the filter_by_starts_after() function. An acceptable parameter can be a strtotime parseable string, a DateTime object, or a timestamp. Unaccepted parameters will result in the parameter defaulting to the current date.
Fetch is not inclusive.
'starts_on_or_after'
$results = tribe_events()->where( 'starts_on_or_after' , 'tomorrow' );Filters events whose start date occurs on or after the provided date using the filter_by_starts_on_or_after() function. An acceptable parameter can be a strtotime parseable string, a DateTime object, or a timestamp. Unaccepted parameters will result in the parameter defaulting to the current date.
Very similar to the 'starts_after' argument, but the fetch is inclusive, meaning the results will include the event(s) that match the start date.
'starts_between'
$results = tribe_events()->where( 'starts_between' , 'yesterday' , 'next Thursday' );Filters events whose start date occurs between a set of dates using the filter_by_starts_between() function, which requires two parameters – a start date and an end date; both can be a strtotime parseable string, a DateTime object, or a timestamp. Unaccepted parameters will result in the parameter defaulting to the current date. Passing a start date that occurs after the end date or the same value for both parameters will cause the results to return an empty array.
Fetch is inclusive.
'ends_before'
$results = tribe_events()->where( 'ends_before' , date( 'Y-m-d H:i:s' );Filters events whose end date occurs before the provided date using the filter_by_ends_before() function. An acceptable parameter can be a strtotime parseable string, a DateTime object, or a timestamp. Unaccepted parameters will result in the parameter defaulting to the current date.
Fetch is not inclusive.
'ends_after'
$results = tribe_events()->where( 'ends_after' , '31 December 2023' );Filters events whose end date occurs after the provided date using the filter_by_ends_after() function. An acceptable parameter can be a strtotime parseable string, a DateTime object, or a timestamp. Unaccepted parameters will result in the parameter defaulting to the current date.
Fetch is not inclusive.
'ends_on_or_before'
$results = tribe_events()->where( 'ends_on_or_before' , 'today' );Filters events whose end date occurs on or before the provided date using the filter_by_ends_on_or_before() function. An acceptable parameter can be a strtotime parseable string, a DateTime object, or a timestamp. Unaccepted parameters will result in the parameter defaulting to the current date.
Fetch is inclusive.
'ends_between'
$results = tribe_events()->where( 'ends_between' , '-1 month' , '+1 month' );Filters events whose end date occurs between a set of dates using the filter_by_ends_between() function, which requires two parameters – a start date and an end date; both can be a strtotime parseable string, a DateTime object, or a timestamp. Unaccepted parameters will result in the parameter defaulting to the current date. Passing a start date that occurs after the end date or the same value for both parameters will cause the results to return null.
Fetch is inclusive.
'date_overlaps'
$results = tribe_events()->where(
'date_overlaps',
'2024-04-09 00:00:00',
'2024-04-10 02:30:00',
'America/Denver',
.4 * HOUR_IN_SECONDS
);Filters events whose duration overlaps a given Start and End date. Will include multi-day events. Uses the filter_by_date_overlaps() function. Requires two parameters – a start date and an end date; both can be a strtotime parseable string, a DateTime object, or a timestamp. Two optional parameters are the $timezone and $min_sec_overlap (int), which is the minimum overlap, in seconds, an event should have with the interval; defaults to at least one second. The example above shows all four parameters, but only the start and end dates are required.
Fetch is inclusive.
'starts_and_ends_between'
$results = tribe_events()->where( 'starts_and_ends_between', 'tomorrow', '+3 days' ); Filters events that both start and end between two specified dates. Will include multi-day events. Uses the filter_by_starts_and_ends_between() function. Requires two parameters – a start date and an end date; both can be a strtotime parseable string, a DateTime object, or a timestamp. Passing a start date that occurs after the end date or the same value for both parameters will cause the results to return null.
Fetch is inclusive.
'runs_between'
$results = tribe_events()->where( 'runs_between', '04 January 2024', '06 January 2024' ); Filters events that both start or end between two specified dates. Will include multi-day events. Uses the filter_by_runs_between() function. Requires two parameters – a start date and an end date; both can be a strtotime parseable string, a DateTime object, or a timestamp. Passing a start date that occurs after the end date or the same value for both parameters will cause the results to return null.
Fetch is inclusive.
'on_date'
$results = tribe_events()->where( 'on_date', '04 January 2024' );Filters events to include only those that start on a specific date. Will include multi-day events. Uses the filter_by_on_date() function (which is a wrapper for the filter_by_starts_between function). Requires one parameter: a start date, which can be a strtotime parseable string, a DateTime object, or a timestamp. Unaccepted parameters will result in the parameter defaulting to the current date.
Event Properties Related
'all_day'
$results = tribe_events()->where( 'all_day' );Filters events by their all-day status. Uses the filter_by_all_day() function. Accepts an optional boolean parameter of whether to return events that are all day (true) or are not all day (false). Defaults to true. Accepted negative booleans are false or 0 – all other parameters passed will defer to the default true.
'multiday'
$results = tribe_events()->where( 'multiday' , false );Filters events to include only those that match the provided multiday state. An event is considered multiday when the end date is after the end-of-day cutoff of the start date. Uses the filter_by_multiday() function. Please note that an event might be multiday in its timezone but not in another; this filter will make the check on the event times localized to the event timezone. Furthermore, the end-of-day cutoff is taken into account, which may affect results based on how the site’s settings are configured.
Accepts an optional boolean parameter of whether to return events that are multiday (true) or are not multiday (false). Defaults to true. Accepted negative booleans are false or 0 – all other parameters passed will defer to the default true.
'on_calendar_grid'
$results = tribe_events()->where( 'on_calendar_grid' , 'January' , 2024 );Filters events to include only those events that appear on the given month’s calendar grid. This includes events that start or end on the previous or next month’s days that appear on the month view to make the calendar a square. Uses filter_by_on_calendar_grid() function. Accepts two required parameters: $month and $year, both of which can be either a string or an int. Uses the is_valid_date() function to check if the parameters are acceptable – unaccepted parameters will result in the filter being ignored.
'timezone'
$results = tribe_events()->where( 'timezone' , 'America/New_York' );Filters events to include only those events that use the given timezone. Uses filter_by_timezone() function. Accepts one required parameter: $timezone which must be a string that can be a timezone string, UTC offset, or DateTimeZone object
'hidden_from_upcoming'
$results = tribe_events()->where( 'hidden_from_upcoming' , 'true' );Filters events by their “Hidden from Event Listings” status. Uses filter_by_hidden_on_upcoming() function. Accepts one required parameter for whether to return events that are or are not hidden from upcoming. The parameter is parsed as a boolean using the tribe_is_truthy() function. If no events are hidden from upcoming and a truthy value is passed as the parameter, the filter will be ignored and all events will be returned.
'sticky'
$results = tribe_events()->where( 'sticky' , false );Filters events by their “sticky” status, meaning the option that enables in month view, the events will display first in the list of events shown within a given day block. Uses the filter_by_sticky() function. Accepts one optional boolean parameter for whether to return events that are or are not sticky.
'featured'
$results = tribe_events()->where( 'featured' , false );Filters events by their featured status. Uses the filter_by_featured() function. Accepts one optional boolean parameter for whether to return events that are or are not featured, defaulting to true.
'hidden'
$results = tribe_events()->where( 'hidden' , false );Filters events to include only those that match the provided hidden state. Uses the filter_by_hidden() function. Accepts one optional boolean parameter for whether to return events that are or are not hidden, defaulting to true. The difference between 'hidden' and 'hidden_from_upcoming' is that the parameter is optional, though both are filtering for the same _EventHideFromUpcoming metadata on events.
Event relationship to other Post Types
'linked_posts'
$results = tribe_events()->where( 'linked_posts' , '_EventVenueID' , $venue );Filters events to include only those that are linked to the given post. Uses filter_by_linked_post() function, which is an inner function for filtering by organizer or venue. Accepts two required parameters: string | $linked_post_meta_key (the linked post type meta key) and int|WP_Post|array | $linked_post (the linked post(s)).