Knowledgebase | The Events Calendar

Using tribe_get_events

tribe_get_events() is a neat little helper function that makes it easy to retrieve event data when building customizations. In this tutorial, we’ll look at how it works and provide some examples to get you started.

If you’re already familiar with the WP_Query class or the get_posts() function provided by WordPress, then working with tribe_get_events() should feel very familiar. For anyone who is unfamiliar with those parts of WordPress, I’d definitely recommend reviewing the linked documentation – especially if you want to do something really gnarly.

Basic usage

When you call tribe_get_events() you can expect it to return an array of events (this could, of course, be an empty array if it can’t find what you’re looking for). Quite often you will also want to pass in some arguments to narrow down the sort of events you are trying to find, but that’s not actually necessary.

tribe_get_events(array('ends_after' => 'now'));

The above code simply retrieves a list of upcoming events.

We haven’t actually told it how many events we are interested in and so it will assume you want up to the same value specified in the number of events to show per page settings (found in the Events → Settings → General admin screen). By default that is 10 events.

As alluded to above, there is a very strong link between tribe_get_events() and the WP_Query class – we can, in fact, use most or all of the same query arguments in both cases.

Let’s look at how this works and how we might restrict the number of events we are interested in from the default value to just 5, by supplying a posts_per_page argument:

// Retrieve the next 5 upcoming events
$events = tribe_get_events( [
   'posts_per_page' => 5,
   'start_date'     => 'now',
] );

Our extra arguments are contained within an array and, this time, $events will contain an array of up to five upcoming events.

Displaying events

Quite often you will want to display your events after you have retrieved them. An obvious and simple approach – though not without its shortcomings – is to do something like this:

$events = tribe_get_events( [ 'posts_per_page' => 5 ] );

// Loop through the events, displaying the title and content for each
foreach ( $events as $event ) {
   echo '<h4>' . $event->post_title . '</h4>';
   echo wpautop( $event->post_content );
}

Such a “quick and dirty” approach could be fine if all you need to do is inspect some properties of each event but to display them it is generally better to do things the WordPress way and use the appropriate template tags:

// Ensure the global $post variable is in scope
global $post;

// Retrieve the next 5 upcoming events
$events = tribe_get_events( [ 'posts_per_page' => 5 ] );

// Loop through the events: set up each one as
// the current post then use template tags to
// display the title and content
foreach ( $events as $post ) {
   setup_postdata( $post );

   // This time, let's throw in an event-specific
   // template tag to show the date after the title!
   echo '<h4>' . $post->post_title . '</h4>';
   echo ' ' . tribe_get_start_date( $post ) . ' ';
}

This is arguably more readable – we’re not constantly referencing the event/post object – and we also benefit from all the many filters and other good things that WordPress (and to some extent The Events Calendar) take care of behind the scenes.

Event arguments

So far so good: we can retrieve events and apply standard WP_Query arguments, like posts_per_page, to control it. As we’re dealing with events here, rather than pages or blog posts, The Events Calendar exposes some additional arguments that are not normally available but which make life easier when working with events:

  • start_date is used to indicate the start of the date range you are interested in
  • end_date is of course what you would use to indicate the end of the date range you are interested in

There are some potential “gotchas” here that hopefully make some sense once you’ve thought them through.

One is that setting a start_date earlier than today when the query is for upcoming events will not have any impact. The flip side is that setting an end_date later than today when querying for past events similarly will have no effect, both will automatically be overwritten.

Also, when supplying values for the start_date and end_date, we recommend you use one of the following formats (others may work — but don’t count on it!):

  • Y-m-d H:i (i.e. 2014-12-31 12:00 for noon on December 31st, 2014) if you need to specify the time
  • Y-m-d (i.e. 2015-07-01 for July 1st, 2015) if you don’t need the extra accuracy specifying a time provides

Both start_date and end_date will accept any values that the PHP function strtotime() would. Examples:

  • now – For the current second
  • today – For the first second of today
  • last month – For the start of last month
  • next monday – For the start of the day on the next monday

Examples

We’ll finish off with a set of examples that you can use as the basis of your own tribe_get_events() queries.

Get all events in a specific time range:

// Retrieve all events in October 2014
$events = tribe_get_events( [
   'start_date'   => '2014-10-01 00:01',
   'end_date'     => '2014-10-31 23:59',
] );

Upcoming events taking place after a certain date:

// Retrieve any upcoming events starting January 1st, 2015, or later
$events = tribe_get_events( [
   'start_date'   => '2015-01-01',
] );

Grab the next 5 events with a specific tag:

// Grab the 5 next "party" events (by tag)
$events = tribe_get_events( [
   'start_date'     => 'now',
   'posts_per_page' => 5,
   'tag'            => 'party' // or whatever the tag name is
] );

// Grab the next 8 featured events
$events = tribe_get_events( [
   'start_date'     => 'now',
   'posts_per_page' => 8,
   'featured'       => true,
] );

Hopefully, this tutorial and the above examples can help you get started with tribe_get_events(). If you need help, you can always post to our Help Desk, and we’ll do our best to point you in the right direction.