tribe_get_event( null|int|WP_Post $event = null, string|null $output = OBJECT, string $filter = 'raw', bool $force = false )
Fetches and returns a decorated post object representing an Event.
Contents
Parameters
- $event
-
(null|int|WP_Post) (Optional) The event ID or post object or
nullto use the global one.Default value: null
- $output
-
(string|null) (Optional) The required return type. One of
OBJECT,ARRAY_A, orARRAY_N, which correspond to a WP_Post object, an associative array, or a numeric array, respectively. Defaults toOBJECT.Default value: OBJECT
- $filter
-
(string) (Optional) Type of filter to apply. Accepts 'raw', a valid date string or object to localize the event in a specific time-frame.
Default value: 'raw'
- $force
-
(bool) (Optional) Whether to force a re-fetch ignoring cached results or not.
Default value: false
Return
(array|WP_Post|null) The Event post object or array, null if not found.
- 'start_date'
(string) The event start date, inY-m-d H:i:sformat. - 'start_date_utc'
(string) The event UTC start date, inY-m-d H:i:sformat. - 'end_date'
(string) The event end date, inY-m-d H:i:sformat. - 'end_date_utc'
(string) The event UTC end date, inY-m-d H:i:sformat. - 'dates'
(array) An array containing the event.start, end and UTC date objects. { - 'start'
(DateTimeImmutable) The event start date object. - 'start_utc'
(DateTimeImmutable) The event UTC start date object. - 'end'
(DateTimeImmutable) The event end date object. - 'end_utc'
(DateTimeImmutable) The event UTC end date object. - 'start_site'
(DateTimeImmutable) The event start date object in the site timezone. - 'end_site'
(DateTimeImmutable) The event end date object in the site timezone. - 'start_display'
(DateTimeImmutable) The event start date object in the site or event timezone depending on the setting. - 'end_display'
(DateTimeImmutable) The event end date object in the site or event timezone depending on the setting.
(string) The event timezone string.
(int) The event duration in seconds.
(false|int) Whether the event is multi-day or not and its day. duration if it is.
(bool) Whether the event is an all-day one or not.
(null|bool) Whether the event starts on the week of the date specified in the
$filter argument or not, null if no date is specified in the filter.(null|bool) Whether the event ends on the week of the date specified in the
$filter argument or not, null if no date is specified in the filter.(null|bool) Whether the event happens on the week of the date specified in the
$filter argument or not, null if no date is specified in the filter.(null|int) The days duration of the event on the week specified in the
$filter argument, null if no date is specified in the filter.(bool) Whether the event is a featured one or not.
(string) The event formatted cost string, as returned by the
tribe_get_cost tribe_get_cost function.(Lazy_Collection) A collection of Organizers, lazily fetched and eventually resolved to an array.
(Lazy_Collection) A collection of Venues, lazily fetched and eventually resolved to an array.
(Post_Thumbnail) The post thumbnail information.
(Lazy_String) The event schedule details, as produced by the
tribe_events_event_schedule_details function.(Lazy_String) The event schedule details, without HTML tags.
Source
File: src/functions/template-tags/event.php
function tribe_get_event( $event = null, $output = OBJECT, $filter = 'raw' ) {
/**
* Filters the event result before any logic applies.
*
* Returning a non `null` value here will short-circuit the function and return the value.
* Note: this value will not be cached and the caching of this value is a duty left to the filtering function.
*
* @since 4.9.7
*
* @param mixed $return The event object to return.
* @param mixed $event The event object to fetch.
* @param string|null $output The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which
* correspond to a `WP_Post` object, an associative array, or a numeric array,
* respectively. Defaults to `OBJECT`.
* @param string $filter Type of filter to apply. Accepts 'raw', a valid date string or
* object to localize the event in a specific time-frame.
*/
$return = apply_filters( 'tribe_get_event_before', null, $event, $output, $filter );
if ( null !== $return ) {
return $return;
}
$post = get_post( $event );
if ( ! $post instanceof WP_Post ) {
return null;
}
// Cache by post ID and filter.
$cache_key = 'events_' . $post->ID . '_' . $filter;
$cache = new Tribe__Cache();
$cached = $cache->get( $cache_key, Tribe__Cache_Listener::TRIGGER_SAVE_POST );
// Define a function to cache this event when, and if, one of the lazy properties is loaded.
$cache_this = static function () use ( $cache, $cache_key, $post ) {
/*
* Cache without expiration, but only until a post of the types managed by The Events Calendar is
* updated or created.
*/
$cache->set( $cache_key, $post, 0, Tribe__Cache_Listener::TRIGGER_SAVE_POST );
};
if ( false !== $cached ) {
switch ( $output ) {
case ARRAY_A:
return (array) $cached;
case ARRAY_N:
return array_values( (array) $cached );
case OBJECT:
default;
return $cached;
}
}
$post_id = $post->ID;
$start_date = get_post_meta( $post_id, '_EventStartDate', true );
$start_date_utc = get_post_meta( $post_id, '_EventStartDateUTC', true );
$end_date = get_post_meta( $post_id, '_EventEndDate', true );
$end_date_utc = get_post_meta( $post_id, '_EventEndDateUTC', true );
$duration = (int) get_post_meta( $post_id, '_EventDuration', true );
$timezone_string = Timezones::get_event_timezone_string( $post_id );
$all_day = tribe_is_truthy( get_post_meta( $post_id, '_EventAllDay', true ) );
// An event is multi-day if its end date is after the end-of-day cutoff of the start date.
$end_of_day = tribe_end_of_day( $start_date );
$timezone = Timezones::build_timezone_object( $timezone_string );
$utc_timezone = new DateTimezone('UTC');
$start_date_object = new DateTimeImmutable( $start_date, $timezone );
$end_date_object = new DateTimeImmutable( $end_date, $timezone );
$start_date_utc_object = new DateTimeImmutable( $start_date_utc, $utc_timezone );
$end_date_utc_object = new DateTimeImmutable( $end_date_utc, $utc_timezone );
$end_of_day_object = new DateTimeImmutable( $end_of_day, $timezone );
$is_multiday = $end_of_day_object < $end_date_object;
$multiday = false;
// Without a context these values will not make sense; we'll set them if the `$filter` argument is a date.
$starts_this_week = null;
$ends_this_week = null;
$happens_this_week = null;
$this_week_duration = null;
if ( Dates::is_valid_date( $filter ) ) {
$week_start = Dates::build_date_object( $filter, $timezone );
// Sunday is 0.
$week_start_day = (int) get_option( 'start_of_week' );
$offset = (int) $week_start->format( 'N' ) >= $week_start_day
? $week_start_day
: $week_start->format( 'N' ) - $week_start_day;
$week_start->setISODate( (int) $week_start->format( 'o' ), (int) $week_start->format( 'W' ), $offset );
$week_end = clone $week_start;
// 7 days later the week ends.
$week_end->add( new DateInterval( 'P7D' ) );
// Inclusive in respect to the start, exclusive to the end.
$starts_this_week = $week_start <= $start_date_object && $start_date_object < $week_end;
$ends_this_week = $week_start <= $end_date_object && $end_date_object < $week_end;
$happens_this_week = $week_start <= $end_date_object && $start_date_object <= $week_end;
if ( $happens_this_week ) {
$this_week_duration = 1;
if ( $is_multiday ) {
/*
* We add one second during this calculation to cope with all-day events starting on 12:00 AM.
* Due to how DateTime diff works diffing two following midnights would yield a diff of 2 days.
*/
$one_second = new \DateInterval( 'PT1S' );
$this_week_duration = min(
7,
$week_end->diff( $start_date_object->add( $one_second ) )->days + 1,
$end_date_object->diff( $week_start )->days + 1,
$end_date_object->diff( $start_date_object->add( $one_second ) )->days + 1
);
}
}
}
// Multi-day events will span at least two days: the day they start on and the following one.
if ( $is_multiday ) {
/*
* Count the number of cut-offs happening before the end date and add 1.
* Do not add 1 for all-day events as they span cut-off to cut-off.
*/
$multiday = $all_day ? 0 : 1;
$one_day = new DateInterval( 'P1D' );
// The end date should be inclusive, since it's not in the DatePeriod we work-around it adding a second.
$period = new DatePeriod( $end_of_day_object, $one_day, $end_date_object );
foreach ( $period as $date ) {
++ $multiday;
};
}
$featured = tribe_is_truthy( get_post_meta( $post_id, Tribe__Events__Featured_Events::FEATURED_EVENT_KEY, true ) );
$organizer_fetch = Tribe__Events__Organizer::get_fetch_callback( $post_id );
$venue_fetch = Tribe__Events__Venue::get_fetch_callback( $post_id );
$properties = [
'start_date' => $start_date,
'start_date_utc' => $start_date_utc,
'end_date' => $end_date,
'end_date_utc' => $end_date_utc,
'dates' => (object) [
'start' => $start_date_object,
'start_utc' => $start_date_utc_object,
'end' => $end_date_object,
'end_utc' => $end_date_utc_object,
],
'timezone' => $timezone_string,
'duration' => $duration,
'multiday' => $multiday,
'all_day' => $all_day,
'starts_this_week' => $starts_this_week,
'ends_this_week' => $ends_this_week,
'this_week_duration' => $this_week_duration,
'happens_this_week' => $happens_this_week,
'featured' => $featured,
'cost' => tribe_get_cost( $post_id ),
'organizers' => ( new Lazy_Collection( $organizer_fetch ) )->on_resolve( $cache_this ),
'venues' => ( new Lazy_Collection( $venue_fetch ) )->on_resolve( $cache_this ),
'thumbnail' => ( new Post_Thumbnail( $post_id ) )->on_resolve( $cache_this ),
'permalink' => get_permalink( $post_id ),
'schedule_details' => ( new Lazy_String(
static function () use ( $post_id ) {
return tribe_events_event_schedule_details( $post_id );
},
false
) )->on_resolve( $cache_this )
];
foreach ( $properties as $key => $value ) {
$post->{$key} = $value;
}
/**
* Filters the event post object before caching it and returning it.
*
* Note: this value will be cached; as such this filter might not run on each request.
* If you need to filter the output value on each call of this function then use the `tribe_get_event_before`
* filter.
*
* @since 4.9.7
*
* @param WP_Post $post The event post object, decorated with a set of custom properties.
* @param string $output The output format to use.
* @param string $filter The filter, or context of the fetch.
*/
$post = apply_filters( 'tribe_get_event', $post, $output, $filter );
if ( OBJECT !== $output ) {
$post = ARRAY_A === $output ? (array) $post : array_values( (array) $post );
}
return $post;
}
Changelog
| Version | Description |
|---|---|
| 4.9.7 | Introduced. |