{"id":1896488,"date":"2019-10-18T13:19:14","date_gmt":"2019-10-18T17:19:14","guid":{"rendered":"https:\/\/staging.theeventscalendar.com\/knowledgebase\/using-tribe_get_events-2\/"},"modified":"2023-11-02T02:12:23","modified_gmt":"2023-11-02T06:12:23","slug":"using-tribe_get_events","status":"publish","type":"post","link":"https:\/\/staging.theeventscalendar.com\/knowledgebase\/using-tribe_get_events\/","title":{"rendered":"Using tribe_get_events"},"content":{"rendered":"\n<iframe loading=\"lazy\" width=\"560\" height=\"315\" src=\"https:\/\/www.youtube.com\/embed\/C3XIAMunn10\" title=\"YouTube video player\" frameborder=\"0\" allow=\"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share\" allowfullscreen><\/iframe>\n\n\n\n<p><code>tribe_get_events()<\/code> is a neat little helper function that makes it easy to retrieve event data when building customizations. In this tutorial, we&#8217;ll look at how it works and provide some examples to get you started.<\/p>\n\n\n\n<p>If you&#8217;re already familiar with the <a href=\"https:\/\/developer.wordpress.org\/reference\/classes\/wp_query\/\">WP_Query class<\/a> or the <a href=\"https:\/\/developer.wordpress.org\/reference\/functions\/get_posts\/\">get_posts() function<\/a> provided by WordPress, then working with tribe_get_events() should feel very familiar. For anyone who is unfamiliar with those parts of WordPress, I&#8217;d definitely recommend reviewing the linked documentation &#8211; especially if you want to do something really gnarly.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"basic-usage\">Basic usage<\/h3>\n\n\n\n<p>When you call <code>tribe_get_events()<\/code> you can expect it to return an array of events (this could, of course, be an empty array if it can&#8217;t find what you&#8217;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&#8217;s not actually necessary.<\/p>\n\n\n<div class=\"wp-block-syntaxhighlighter-code \"><pre class=\"brush: php; title: ; notranslate\" title=\"\">\ntribe_get_events(array(&#039;ends_after&#039; =&gt; &#039;now&#039;));\n<\/pre><\/div>\n\n\n<p>The above code simply retrieves a list of upcoming events.<\/p>\n\n\n\n<p>We haven&#8217;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 <em>number of events to show per page<\/em> settings (found in the Events \u2192 Settings \u2192 General admin screen). By default that is 10 events.<\/p>\n\n\n\n<p>As alluded to above, there is a very strong link between <code>tribe_get_events(<\/code>) and the <a href=\"http:\/\/codex.wordpress.org\/Class_Reference\/WP_Query\" target=\"_blank\" rel=\"noopener noreferrer\">WP_Query class<\/a> &#8211; we can, in fact, use most or all of the same query arguments in both cases.<\/p>\n\n\n\n<p>Let&#8217;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 <a href=\"http:\/\/codex.wordpress.org\/Class_Reference\/WP_Query#Pagination_Parameters\" target=\"_blank\" rel=\"noopener noreferrer\">posts_per_page<\/a> argument:<\/p>\n\n\n<div class=\"wp-block-syntaxhighlighter-code \"><pre class=\"brush: php; title: ; notranslate\" title=\"\">\n\/\/ Retrieve the next 5 upcoming events\n$events = tribe_get_events( &#x5B;\n   &#039;posts_per_page&#039; =&gt; 5,\n   &#039;start_date&#039;     =&gt; &#039;now&#039;,\n] );\n<\/pre><\/div>\n\n\n<p>Our extra arguments are contained within an array and, this time, $events will contain an array of up to five upcoming events.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"displaying-events\">Displaying events<\/h3>\n\n\n\n<p>Quite often you will want to display your events after you have retrieved them. An obvious and simple approach &#8211; though not without its shortcomings &#8211; is to do something like this:<\/p>\n\n\n<div class=\"wp-block-syntaxhighlighter-code \"><pre class=\"brush: php; title: ; notranslate\" title=\"\">\n$events = tribe_get_events( &#x5B; &#039;posts_per_page&#039; =&gt; 5 ] );\n\n\/\/ Loop through the events, displaying the title and content for each\nforeach ( $events as $event ) {\n   echo &#039;&lt;h4&gt;&#039; . $event-&gt;post_title . &#039;&lt;\/h4&gt;&#039;;\n   echo wpautop( $event-&gt;post_content );\n}\n<\/pre><\/div>\n\n\n<p>Such a &#8220;quick and dirty&#8221; 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:<\/p>\n\n\n<div class=\"wp-block-syntaxhighlighter-code \"><pre class=\"brush: php; title: ; notranslate\" title=\"\">\n\/\/ Ensure the global $post variable is in scope\nglobal $post;\n\n\/\/ Retrieve the next 5 upcoming events\n$events = tribe_get_events( &#x5B; &#039;posts_per_page&#039; =&gt; 5 ] );\n\n\/\/ Loop through the events: set up each one as\n\/\/ the current post then use template tags to\n\/\/ display the title and content\nforeach ( $events as $post ) {\n   setup_postdata( $post );\n\n   \/\/ This time, let&#039;s throw in an event-specific\n   \/\/ template tag to show the date after the title!\n   echo &#039;&lt;h4&gt;&#039; . $post-&gt;post_title . &#039;&lt;\/h4&gt;&#039;;\n   echo &#039; &#039; . tribe_get_start_date( $post ) . &#039; &#039;;\n}\n<\/pre><\/div>\n\n\n<p>This is arguably more readable &#8211; we&#8217;re not constantly referencing the event\/post object &#8211; 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.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"event-specific-arguments\">Event arguments<\/h3>\n\n\n\n<p>So far so good: we can retrieve events and apply standard <code>WP_Query<\/code> arguments, like <code>posts_per_page<\/code>, to control it. As we&#8217;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:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong><code>start_date<\/code><\/strong> is used to indicate the start of the date range you are interested in<\/li>\n\n\n\n<li><strong><code>end_date<\/code><\/strong> is of course what you would use to indicate the end of the date range you are interested in<\/li>\n<\/ul>\n\n\n\n<p>There are some potential &#8220;gotchas&#8221; here that hopefully make some sense once you&#8217;ve thought them through.<\/p>\n\n\n\n<p>One is that setting a&nbsp;<code>start_date<\/code> earlier than today when the query is for <em>upcoming<\/em> events will not have any impact. The flip side is that setting an <code>end_date<\/code> later than today when querying for <em>past<\/em> events similarly will have no effect, both will automatically be overwritten.<\/p>\n\n\n\n<p>Also, when supplying values for the <code>start_date<\/code> and <code>end_date<\/code>, we recommend you use one of the following formats (others may work \u2014 but don&#8217;t count on it!):<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><code>Y-m-d H:i<\/code> (i.e. 2014-12-31 12:00 for noon on December 31st, 2014) if you need to specify the time<\/li>\n\n\n\n<li><code>Y-m-d<\/code> (i.e. 2015-07-01 for July 1st, 2015) if you don&#8217;t need the extra accuracy specifying a time provides<\/li>\n<\/ul>\n\n\n\n<p>Both <code>start_date<\/code> and <code>end_date<\/code> will accept any values that the PHP function <code>strtotime()<\/code> would. Examples:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><code>now<\/code> &#8211; For the current second<\/li>\n\n\n\n<li><code>today<\/code> &#8211; For the first second of today<\/li>\n\n\n\n<li><code>last month<\/code> &#8211; For the start of last month<\/li>\n\n\n\n<li><code>next monday<\/code> &#8211; For the start of the day on the next monday<\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"examples\">Examples<\/h3>\n\n\n\n<p>We&#8217;ll finish off with a set of examples that you can use as the basis of your own tribe_get_events() queries.<\/p>\n\n\n\n<div style=\"height:25px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<p id=\"all-events-in-time-range\">Get all events in a specific time range:<\/p>\n\n\n<div class=\"wp-block-syntaxhighlighter-code \"><pre class=\"brush: php; title: ; notranslate\" title=\"\">\n\/\/ Retrieve all events in October 2014\n$events = tribe_get_events( &#x5B;\n   &#039;start_date&#039;   =&gt; &#039;2014-10-01 00:01&#039;,\n   &#039;end_date&#039;     =&gt; &#039;2014-10-31 23:59&#039;,\n] );\n<\/pre><\/div>\n\n\n<div style=\"height:25px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<p>Upcoming events taking place after a certain date<span style=\"color: #a6b2c0;\">:<\/span><\/p>\n\n\n<div class=\"wp-block-syntaxhighlighter-code \"><pre class=\"brush: php; title: ; notranslate\" title=\"\">\n\/\/ Retrieve any upcoming events starting January 1st, 2015, or later\n$events = tribe_get_events( &#x5B;\n   &#039;start_date&#039;   =&gt; &#039;2015-01-01&#039;,\n] );\n<\/pre><\/div>\n\n\n<div style=\"height:25px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<p>Grab the next 5 events with a specific tag:<\/p>\n\n\n<div class=\"wp-block-syntaxhighlighter-code \"><pre class=\"brush: php; title: ; notranslate\" title=\"\">\n\/\/ Grab the 5 next &quot;party&quot; events (by tag)\n$events = tribe_get_events( &#x5B;\n   &#039;start_date&#039;     =&gt; &#039;now&#039;,\n   &#039;posts_per_page&#039; =&gt; 5,\n   &#039;tag&#039;            =&gt; &#039;party&#039; \/\/ or whatever the tag name is\n] );\n<\/pre><\/div>\n\n\n<div style=\"height:25px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<p id=\"featured-events\">Display the next eight featured events:<\/p>\n\n\n<div class=\"wp-block-syntaxhighlighter-code \"><pre class=\"brush: php; title: ; notranslate\" title=\"\">\n\/\/ Grab the next 8 featured events\n$events = tribe_get_events( &#x5B;\n   &#039;start_date&#039;     =&gt; &#039;now&#039;,\n   &#039;posts_per_page&#039; =&gt; 8,\n   &#039;featured&#039;       =&gt; true,\n] );\n<\/pre><\/div>\n\n\n<p>Hopefully, this tutorial and the above examples can help you get started with <code>tribe_get_events()<\/code>. If you need help, you can always post to our <a href=\"https:\/\/support.theeventscalendar.com\" target=\"_blank\" rel=\"noreferrer noopener\">Help Desk<\/a>, and we&#8217;ll do our best to point you in the right direction.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>tribe_get_events() is a neat little helper function that makes it easy to retrieve event data when building customizations. In this tutorial, we&#8217;ll look at how it works and provide some examples to get you started. If you&#8217;re already familiar with the WP_Query class or the get_posts() function provided by WordPress, then working with tribe_get_events() should&#8230;<\/p>\n","protected":false},"author":3,"featured_media":1955565,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"_kad_blocks_custom_css":"","_kad_blocks_head_custom_js":"","_kad_blocks_body_custom_js":"","_kad_blocks_footer_custom_js":"","_swpsp_post_exclude":false,"_kad_post_transparent":"","_kad_post_title":"","_kad_post_layout":"","_kad_post_sidebar_id":"","_kad_post_content_style":"","_kad_post_vertical_padding":"","_kad_post_feature":"","_kad_post_feature_position":"","_kad_post_header":false,"_kad_post_footer":false,"ep_exclude_from_search":false,"footnotes":""},"categories":[59],"tags":[25,58],"stellar-product-taxonomy":[161],"class_list":["post-1896488","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-customizing-resources","tag-customizations","tag-php","stellar-product-taxonomy-the-events-calendar"],"acf":[],"taxonomy_info":{"category":[{"value":59,"label":"PHP &amp; Functions"}],"post_tag":[{"value":25,"label":"Customizations"},{"value":58,"label":"PHP"}],"stellar-product-taxonomy":[{"value":161,"label":"The Events Calendar"}]},"featured_image_src_large":["https:\/\/images.theeventscalendar.com\/kb\/uploads\/2023\/02\/social-share-1024x538.png",1024,538,true],"author_info":{"display_name":"Jaime Marchwinski","author_link":"https:\/\/staging.theeventscalendar.com\/knowledgebase\/author\/jaimetri-be\/"},"comment_info":0,"category_info":[{"term_id":59,"name":"PHP &amp; Functions","slug":"customizing-resources","term_group":0,"term_taxonomy_id":59,"taxonomy":"category","description":"","parent":24,"count":101,"filter":"raw","term_order":"0","cat_ID":59,"category_count":101,"category_description":"","cat_name":"PHP &amp; Functions","category_nicename":"customizing-resources","category_parent":24}],"tag_info":[{"term_id":25,"name":"Customizations","slug":"customizations","term_group":0,"term_taxonomy_id":25,"taxonomy":"post_tag","description":"","parent":0,"count":177,"filter":"raw","term_order":"0"},{"term_id":58,"name":"PHP","slug":"php","term_group":0,"term_taxonomy_id":58,"taxonomy":"post_tag","description":"","parent":20,"count":128,"filter":"raw","term_order":"0"}],"_links":{"self":[{"href":"https:\/\/staging.theeventscalendar.com\/knowledgebase\/wp-json\/wp\/v2\/posts\/1896488","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/staging.theeventscalendar.com\/knowledgebase\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/staging.theeventscalendar.com\/knowledgebase\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/staging.theeventscalendar.com\/knowledgebase\/wp-json\/wp\/v2\/users\/3"}],"replies":[{"embeddable":true,"href":"https:\/\/staging.theeventscalendar.com\/knowledgebase\/wp-json\/wp\/v2\/comments?post=1896488"}],"version-history":[{"count":4,"href":"https:\/\/staging.theeventscalendar.com\/knowledgebase\/wp-json\/wp\/v2\/posts\/1896488\/revisions"}],"predecessor-version":[{"id":1958394,"href":"https:\/\/staging.theeventscalendar.com\/knowledgebase\/wp-json\/wp\/v2\/posts\/1896488\/revisions\/1958394"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/staging.theeventscalendar.com\/knowledgebase\/wp-json\/wp\/v2\/media\/1955565"}],"wp:attachment":[{"href":"https:\/\/staging.theeventscalendar.com\/knowledgebase\/wp-json\/wp\/v2\/media?parent=1896488"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/staging.theeventscalendar.com\/knowledgebase\/wp-json\/wp\/v2\/categories?post=1896488"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/staging.theeventscalendar.com\/knowledgebase\/wp-json\/wp\/v2\/tags?post=1896488"},{"taxonomy":"stellar-product-taxonomy","embeddable":true,"href":"https:\/\/staging.theeventscalendar.com\/knowledgebase\/wp-json\/wp\/v2\/stellar-product-taxonomy?post=1896488"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}