Instance Methods

All of the following functions are available for you to use for custom development in your theme as needed, however they all need to be accessed through the plugin instance. Doing things this way helps to ensure that the API connection is always active, and you don’t run into any unexpected behavior.

Accessing the Plugin Instance

The following code will get you the current instance of the plugin.

NOTE: WordPress must be loaded, the MegaCalendar Plugin must be active, and plugins must have already been loaded in order for this to work as expected.

// Store the plugin instance in $megacalendar
$megacalendar = MegabaseCalendar::get_instance();

You only need to do this once in your template, and from then on all methods can be accessed using $megacalendar.

megacal_get_events

This method allows you to write a custom query to request a list of events from our API.

NOTE: By default, all event requests are paginated to show a max of 25 results, you can use the max_result and start_row args to change this or implement custom pagination. Alternatively, you can use the start_date and end_date args to fetch events in a given date range.

Params:

• Array $args: An array of query arguments:
  • String ‘return’: If this argument is set to ‘response’ this method will return the raw JSON response as a string
  • Bool ‘cache_bypass’: If this argument is set to true, Event caching will be fully bypassed.
  • See the Event Request documentation for a full list of valid args.

Return:

• Array|String|WP_Error $events: An array of Event objects, the raw JSON response, or WP_Error on failure

Examples:

// Get a list of published, upcoming events and print the event names
$megacalendar = MegabaseCalendar::get_instance();
$events = $megacalendar->megacal_get_events( array(
    'published' => true,
    'upcoming' => true,
) );

if( $events instanceof WP_Error ) { 
    wp_die( 'Error encountered in event query' );
}
foreach( $events as $event ) {
    echo esc_html( $event->get_title() );
}

Source (class-megabase-calendar.php)

megacal_get_public_events

This method is functionally the same as megacal_get_events, except that it sets ‘published’ => true in the args for you.

NOTE: By default, all event requests are paginated to show a max of 25 results, you can use the max_result and start_row args to change this or implement custom pagination. Alternatively, you can use the start_date and end_date args to fetch events in a given date range.

Params:

• Array $args: An array of query arguments:
  • String ‘return’: If this argument is set to ‘response’ this method will return the raw JSON response as a string
  • Bool ‘cache_bypass’: If this argument is set to true, Event caching will be fully bypassed.
  • See the Event Request documentation for a full list of valid args.

Return:

• Array|String|WP_Error $events: An array of Event objects, the raw JSON response, or WP_Error on failure

Examples:

// Get a list of published, upcoming events and print the event names 
$megacalendar = MegabaseCalendar::get_instance(); 
$events = $megacalendar->megacal_get_public_events( array( 
    'upcoming' => true, 
) ); 

if( $events instanceof WP_Error ) { 
    wp_die( 'Error encountered in event query' );
}
foreach( $events as $event ) { 
     echo esc_html( $event->get_title() ); 
}

Source (class-megabase-calendar.php)

megacal_get_event_request

This method contains the underlying API request used in megacal_get_events. You can use it to bypass any extra handling and deal directly with the get_events request and response.

NOTE: By default, all event requests are paginated to show a max of 25 results, you can use the max_result and start_row args to change this or implement custom pagination. Alternatively, you can use the start_date and end_date args to fetch events in a given date range.

Params:

• Array $args: An array of query arguments:
  • See the Event Request documentation for a full list of valid args.

Return:

• EventListResponse|WP_Error The EventListResponse object, or WP_Error on failure

Examples:

// Get a list of published, upcoming events, then print total number of events, and the event names 
$megacalendar = MegabaseCalendar::get_instance(); 
$response = $megacalendar->megacal_get_event_request( array( 
    'published' => true,
    'upcoming' => true, 
) ); 

if( $response instanceof WP_Error ) { 
    wp_die( 'Error encountered in event query' );
}

$events = $response->get_events();
$total_events = $response->get_count();

echo '<p>Total: ' . esc_html( $total_events ) . '</p>';
foreach( $events as $event ) { 
     echo esc_html( $event->get_title() ); 
}

Source (class-megabase-calendar.php):

/**
 * Fetches Events from the MegaCal API 
 * 
 * @param array $args The request args - see EventRequest for options
 * @return EventListResponse|WP_Error The EventListResponse object, or WP_Error on failure
 */
public function megacal_get_event_request( $args = array() ) {
    
    try {

        $response = MegaCalAPI::request( MegaCalAPI::EVENT_REQUEST, 'get_events', $args );

        if( !( $response instanceof EventListResponse ) ) {
            throw new ApiException( 'Unexpected response object' );
        }

        return $response;

    } catch( Exception $e ) {

        error_log( $e->getMessage() );
        return new WP_Error( $e->getCode(), $e->getMessage() );

    }

}

megacal_get_venue_name

Gets and formats a Venue name from the given Event.

Params:

• Event $event: The event to get the Venue name from

Return:

• String The Venue name, the null venue name from settings, or empty

Examples:

// Get a list of published, upcoming events, then print the formatted venue name for each Event
$megacalendar = MegabaseCalendar::get_instance(); 
$events = $megacalendar->megacal_get_public_events( array( 'upcoming' => true, ) ); 

if( $events instanceof WP_Error ) { 
    wp_die( 'Error encountered in event query' ); 
} 

foreach( $events as $event ) { 
    echo esc_html( $megacalendar->megacal_get_venue_name( $event ) );
}

Source (class-megabase-calendar.php):

/**
 * Gets and formats a Venue name from the given Event
 * 
 * @param Event $event The event object
 * @return string The Venue name, the null Venue name from settings, or empty
 */
public function megacal_get_venue_name( $event ) {

    if( empty( $event ) || !( $event instanceof Event ) ) {
        return '';
    }

    if( empty( $event->get_venue() ) ) {
        $settings = self::megacal_get_settings();

        if( empty( $settings['megacal_null_venue_label'] ) ) {
            return '';
        }
            
        return $settings['megacal_null_venue_label'];
    }

    return $event->get_venue()->get_name();
}

get_event_detail_url

Gets the url to a specific Event Detail page, or the Event Detail base url.

Params:

• Integer $event_id: The event ID to include in the url – Optional, if empty you will get the base URL without an event ID

Return:

• String The URL to the event detail page – Empty string (”) on failure

Examples:

// Get a list of published, upcoming events, then render a link for each Event 
$megacalendar = MegabaseCalendar::get_instance(); 
$events = $megacalendar->megacal_get_public_events( array( 'upcoming' => true, ) ); 

if( $events instanceof WP_Error ) { 
    wp_die( 'Error encountered in event query' ); 
} 

foreach( $events as $event ) { 
    echo '<a href="' . esc_url( $megacalendar->get_event_detail_url( $event->get_id() ) ) . '">Event Detail Link</a>'; 
}

// Display the base permalink for the Event Detail page
echo 'The event detail base url is ' . $megacalendar->get_event_detail_url();

Source (class-megabase-calendar.php):

/**
 * Return the url to the event detail page
 * 
 * @param int The event ID to include in the url - Optional, if empty you will get the base URL without an event ID
 * 
 * @return string The URL to the event detail page
 */
public function get_event_detail_url( $event_id = '' ) {

    $settings = $this->megacal_get_settings();
    $event_detail_page = get_post( $settings['megacal_events_page'] );

    if( empty( $event_detail_page ) ) {
        error_log( 'Event Detail Page is empty!' );
        return '';
    }

    if( !empty( $event_id ) && intval( $event_id ) != $event_id ) {
        error_log( sprintf( '%s is not a valid event ID', $event_id ) );
        $event_id = '';
    }

    return empty( $event_id ) ? get_permalink( $event_detail_page ) : trailingslashit( get_permalink( $event_detail_page ) ) . intval( $event_id );

}

megacal_get_category_list

Gets a list of all Categories, either from cache or the API.

This list will include both Categories that have been shared with you, and Categories that you have created.

Params:

• Array Arguments to apply to the result
  • Boolean ‘published’: Filter results by Published/Unpublished

Return:

• Array<Category> An array of all Categories associated with your account – Will be an empty array on failure, or if no Categories exist

Examples:https://megabase.co/help_docs

<?php
// List all categories
$megacalendar = MegabaseCalendar::get_instance(); 
$categories = $megacalendar->megacal_get_category_list();
?>
<?php if( !empty( $categories ) ): ?>
    <ul>
        <?php foreach( $categories as $category ): ?>
            <li><?php echo esc_html( $category->get_name() ); ?></li>
        <?php endforeach; ?>
    </ul>
<?php endif; ?>

Source (class-megabase-calendar.php):

/** 
 * Gets a list of Categories, either from cache or the API
 * 
 * @param array $args Arguments to apply to the result
 * @return array The list of Categories 
 */
public function megacal_get_category_list( $args = array() ) {

    $categories = get_transient( MEGACAL_CACHED_CATEGORIES_CACHE_KEY );

    if( false === $categories ) {

        $vals = $this->megacal_update_cached_upsert_vals();
        $categories = !empty( $vals['categories'] ) ? $vals['categories'] : array();

    }

    if( !empty( $args ) ) {
        if( isset( $args['published'] ) ) {
            $categories = array_filter( $categories, function( $e ) use ( $args ) {
                return $e->get_published() === $args['published'];
            } );
        }
    }

    return array_values( $categories );
    
}

megacal_get_my_category_list

Gets a list of your own Categories, either from cache or the API.

This list will include only Categories that you have created.

Params:

• Array Arguments to apply to the result
  • Boolean ‘published’: Filter results by Published/Unpublished

Return:

• Array<Category> An array of all Categories that you’ve created – Will be an empty array on failure, or if no Categories exist

Examples:

<?php
// List all categories that you own
$megacalendar = MegabaseCalendar::get_instance(); 
$categories = $megacalendar->megacal_get_my_category_list();
?>
<?php if( !empty( $categories ) ): ?>
    <ul>
        <?php foreach( $categories as $category ): ?>
            <li><?php echo esc_html( $category->get_name() ); ?></li>
        <?php endforeach; ?>
    </ul>
<?php endif; ?>

Source (class-megabase-calendar.php):

/** 
 * Gets a list of User's Categories, either from cache or the API
 * 
 * @param array $args Arguments to apply to the result
 * @return array The list of User's Categories
 */
public function megacal_get_my_category_list( $args = array() ) {

    $my_categories = get_transient( MEGACAL_CACHED_MY_CATEGORIES_CACHE_KEY );

    if( false === $my_categories ) {

        $vals = $this->megacal_update_cached_upsert_vals();
        $my_categories = !empty( $vals['my_categories'] ) ? $vals['my_categories'] : array();

    }

    if( !empty( $args ) ) {
        if( isset( $args['published'] ) ) {
            $my_categories = array_filter( $my_categories, function( $e ) use ( $args ) {
                return $e->get_published() === $args['published'];
            } );
        }
    }

    return array_values( $my_categories );
    
}

megacal_get_venue_list

Gets a list of Venues, either from cache or the API.

Params:

• Array Arguments to apply to the result
  • Boolean ‘published’: Filter results by Published/Unpublished

Return:

• Array<Venue> An array of all Venues – Will be an empty array on failure, or if no Venues exist

Examples:

<?php
// List all venues
$megacalendar = MegabaseCalendar::get_instance(); 
$venues = $megacalendar->megacal_get_venue_list();
?>
<?php if( !empty( $venues ) ): ?>
    <ul>
        <?php foreach( $venues as $venue ): ?>
            <li><?php echo esc_html( $venue->get_name() ); ?></li>
        <?php endforeach; ?>
    </ul>
<?php endif; ?>

Source (class-megabase-calendar.php):

/** 
 * Gets a list of Venues, either from cache or the API
 * 
 * @param array $args Arguments to apply to the result
 * @return array The list of Venues 
*/
public function megacal_get_venue_list( $args = array() ) {

	$venues = get_transient( MEGACAL_CACHED_VENUES_CACHE_KEY );

	if( false === $venues ) {

		$vals = $this->megacal_update_cached_upsert_vals();
		$venues = !empty( $vals['venues'] ) ? $vals['venues'] : array();

	}

	if( !empty( $args ) ) {
		if( isset( $args['published'] ) ) {
			$venues = array_filter( $venues, function( $e ) use ( $args ) {
				return $e->get_published() === $args['published'];
			} );
		}
	}

	return array_values( $venues );
	
}

megacal_clear_debug_log

Allows you to clear the debug log

NOTE: We clear the debug log automatically on the first day of each month, but if you need to clear it yourself you can use this function to do so.

Examples:

// Clear the debug log
$megacalendar = MegabaseCalendar::get_instance();
$megacalendar->megacal_clear_debug_log();

Source (class-megabase-calendar.php):

public function megacal_clear_debug_log() {
    file_put_contents( trailingslashit( MEGACAL_PLUGIN_DIR ) . 'debug.log', '' );
}

Static Methods

There are a handful of static methods available for use.

Static methods are accessed a little bit differently than instance methods. See below for specific examples.

get_instance

Gets or creates the plugin instance – generally, you’ll only need to call this once as outlined in Accessing the Plugin Instace.

Examples:

// Assigning the plugin instance to a variable
$megacalendar = MegabaseCalendar::get_instance();

// Accessing the instance one-time to run a method
MegabaseCalendar::get_instance()->get_event_detail_url();

Source (class-megabase-calendar.php):

public static function get_instance() {
    if(!empty(self::$instance)) {
        return self::$instance;
    } else {
        return new self();
    }
}

megacal_get_settings

Allows you to get the plugin settings as an array.

We cache the result in memory to reduce database calls if you need to access settings multiple times in a single page load.

Params:

• String $option The option to load – ‘megacal_options‘ or ‘megacal_hidden_options‘

Return:

• Array The settings values as an associative array

Examples:

// Get the plugin settings
$megacal_settings = MegabaseCalendar::megacal_get_settings();

Source (class-megabase-calendar.php):

public static function megacal_get_settings( $option = 'megacal_options' ) {

	$settings = wp_cache_get( $option, 'megabase-calendar', false, $found );

	if( false === $found ) {
		
		$settings = get_option( $option );
		
		if( false == $settings ) {
			$settings = array();
		}
		
		wp_cache_set( $option, $settings, 'megabase-calendar' );
	}

	return $settings;

}