\WP_Stager_Integration\Calendar::render_next(array $args = array()): void

Full Code

/**
 * Renders the next upcoming events.
 *
 * Takes the next <code>$args['limit']</code> upcoming events and renders them as the date
 * range they happen to span, so labels, views and clipping behave exactly as they do for
 * any other range. Navigation is disabled, since the scope is a count rather than a span.
 *
 * Upcoming means "has not ended yet": an event that is running right now is included, and
 * an event that finished earlier today is not.
 *
 * <code>show_past_events</code> is forced on, because this scope has already chosen its
 * events. Without it the rendered range would be trimmed back to today, clipping out an
 * ongoing event that started earlier.
 *
 * Events whose status should not be displayed are dropped before the limit is applied, so
 * a hidden event never takes up one of the requested slots.
 *
 * @param array $args   (Optional) An array of calendar settings. See <code>\WP_Stager_Integration\Calendar::render_calendar()</code> for accepted arguments.
 *
 * @return void
 */
public static function render_next( $args = array() ) {

    // Type casting
    $args = (array) $args;

    // Override specific args
    $args[ 'show_nav' ]         = false;
    $args[ 'clip' ]             = true;
    $args[ 'show_past_events' ] = true;

    // Get data
    $limit = (int) ($args[ 'limit' ] ?? 0);
    $query = (array) self::normalize_query( $args[ 'query' ] ?? array() );

    // Use provided events when set, otherwise load events that have not ended yet
    if ( isset( $args[ 'events' ] ) ) {
        $events = (array) $args[ 'events' ];
    } else {
        $events = (array) (Event::get_unfinished_events( -1 ) ?: array());
    }

    // Apply the query filter before counting, so the limit is not spent on excluded events
    if ( ! empty( $query ) ) {
        $events = (array) (self::apply_query_filter( $events, $query ) ?: array());
    }

    // Drop events that would not be rendered, before the limit is applied
    $events = (array) (self::filter_events_by_displayed_status( $events ) ?: array());

    // Take the requested number of events
    if ( $limit > 0 ) {
        $events = array_slice( $events, 0, $limit );
    }

    // Render an empty list if nothing is left, so the no-events message is shown
    if ( empty( $events ) ) {
        $args[ 'scope' ]  = 'event';
        $args[ 'events' ] = array();
        self::render_calendar( $args );
        return;
    }

    // Calculate the range the selected events span
    $min_start = 0;
    $max_end   = 0;

    foreach ( $events as $event ) {

        // Get data
        $start_raw = (string) ($event[ 'programStartAt' ] ?? '');
        $end_raw   = (string) ($event[ 'programEndAt' ] ?? '');

        if ( $start_raw ) {

            $start_ts = (int) strtotime( $start_raw );

            if ( $start_ts ) {
                $min_start = $min_start ? min( $min_start, $start_ts ) : $start_ts;
            }
        }

        if ( $end_raw ) {

            $end_ts = (int) strtotime( $end_raw );

            if ( $end_ts ) {
                $max_end = max( $max_end, $end_ts );
            }
        }
    }

    // Fall back to the start day when no end could be determined
    if ( ! $max_end && $min_start ) {
        $max_end = $min_start;
    }

    // Render an empty list if no start could be determined
    if ( ! $min_start ) {
        $args[ 'scope' ]  = 'event';
        $args[ 'events' ] = array();
        self::render_calendar( $args );
        return;
    }

    // Add args
    $args[ 'class' ]  = trim( (string) ($args[ 'class' ] ?? '') . ' wpstager-calendar--scope-next' );
    $args[ 'events' ] = $events;

    // Delegate to the range renderer; pass through args
    self::render_range( $min_start, $max_end, $args );
}