MegaCalendar API: PHP Wrapper

This documentation page is currently under construction, please reach out to us if you have questions about custom development.

Table of Contents

• Making API Requests
• Entity Types
  • Event
  • Venue
  • Category
  • User
  • TaggedUser
  • EventRecurrenceDetail
• Request Types
  • Event Request
  • Venue Request (Coming Soon)
  • Category Request (Coming Soon)
  • User Request (Coming Soon)
  • Auth Request (Coming Soon)
  • Ping Request (Coming Soon)
• Response Types
  • Event Response Types
  • Venue Response Types (Coming Soon)
  • Category Response Types (Coming Soon)
  • Auth Response Types (Coming Soon)

Making API Requests

NOTE: The following is complex custom development, and you should only need to access the API directly if you are trying to build a significant amount of custom functionality. If you are looking to write custom Event queries for your own templates, we have simpler methods outlined here.

Custom API requests can be made using a helper API accessor class that MegaCalendar exposes. The accessor class is MegaCalAPI.

The static method request is used in conjunction with the request type constants defined there, to build custom API requests. This provides a layer of abstraction between your WordPress site and the API, allowing you to interact directly with the MegaCalendar API, if you choose, without the need to reauthenticate or write raw requests. All requests take the following parameters:

• Request Type: The type of request – one of:
  • MegaCalAPI::EVENT_REQUEST
  • MegaCalAPI::AUTH_REQUEST
  • MegaCalAPI::PING_REQUEST
  • MegaCalAPI::USER_REQUEST
  • MegaCalAPI::VENUE_REQUEST
  • MegaCalAPI::CATEGORY_REQUEST

• Action: The request action – Will match the method names inside of the related request class
  • Event Request
  • Auth Request
  • Ping Request
  • User Request
  • Venue Request
  • Category Request

• Args: The request parameters to send to the API – Each request class contains a list of accepted and required parameters for each action

In the event of a failure requests will throw an ApiException.

For more information on the API itself, you can find the API specification here.

Examples

try {
    // Programattically create an event
    $event_upsert_response = MegaCalAPI::request( MegaCalAPI::EVENT_REQUEST, 'create_event', array(
        'title' => 'My New Event',
        'event_date' => '2023-03-25',
        'published' => true,
        'tagged_users' => array(),
    ) );

    // Programattically delete an event
    $event_delete_response = MegaCalAPI::request( MegaCalAPI::EVENT_REQUEST, 'create_event', array(
        'event_id' => 243,
        'change_type' => '',
    ) );

    // Get a list of all Venues
    $get_venue_response = MegaCalAPI::request( MegaCalAPI::VENUE_REQUEST, 'get_venues' );

} catch( ApiException $e ) {
    error_log( $e->get_simple_message() );
}

Entity Types

The API converts raw responses into convenient objects to make accessing and interacting with data simpler. Below we outline the different objects that you will be dealing with.

Event

Events are the core of MegaCalendar, and are likely the Entity that you will be interacting with most frequently. Any time you are working with a list of Events returned from the API, you can use the following methods to retrieve the data from the Event.

Source: class-event.php

get_id

Get the Event’s id

Returns: Integer

Examples:

echo esc_html( $event->get_id() ); // Print the Event's id

get_title

Get the Event’s Title

Returns: String

Examples:

echo esc_html( $event->get_title() ); // Print the Event's title

get_image_url

Get the Event’s full-sized image URL

Returns: String

Examples:

<img src="<?php echo esc_url( $event->get_image_url() ); ?>" />

get_image_url_square

Get the Event’s thumbnail-sized image URL, falls back to full-size if empty

Returns: String

Examples:

<img src="<?php echo esc_url( $event->get_image_url_square() ); ?>" />

get_image_url_detail

Get the Event’s large-sized image URL, falls back to full-size if empty

Returns: String

Examples:

<img src="<?php echo esc_url( $event->get_image_url_detail() ); ?>" />

get_image_url_banner

Get the Event’s banner-sized image URL, falls back to full-size if empty

Returns: String

Examples:

<img src="<?php echo esc_url( $event->get_image_url_banner() ); ?>" />

get_event_date

Get the Event’s date

Returns: String

Examples:

echo date( 'm/d/Y', strtotime( $event->get_event_date() ) ); // Print the Event date in 'm/d/Y' format

get_start_time

Get the Event’s start time

Returns: String

Examples:

echo date( 'g:ia', strtotime( $event->get_start_time() ) ); // Print the Event start time in 'g:ia' format

get_end_time

Get the Event’s end time

Returns: String

Examples:

echo date( 'g:ia', strtotime( $event->get_end_time() ) ); // Print the Event end time in 'g:ia' format

get_description

Get the Event’s description

Returns: String (HTML-allowed)

Examples:

echo wp_kses_post( $event->get_description() ); // Print the event description, allowing only HTML tags that wp_kses_post allows
echo strip_tags( $event->get_description() ); // Print the event description, allowing no HTML tags
echo apply_filters( 'the_content', $event->get_description() ); // Print the Event description without any escaping, and apply the_content

get_venue

Get the Event’s Venue

Returns: Venue

Examples:

// Print the Event's Venue name
$venue = $event->get_venue();
if( !empty( $venue ) ) {
    echo esc_html( $venue->get_name() );
}

get_owner

Gets the Event’s owner

Returns: User

Examples:

// Print the Event owner's handle
$owner = $event->get_owner();
echo esc_html( $owner->get_handle() );

get_event_category

Gets the Event’s Category

Returns: Category

Examples:

// Print the Event's Category name
$cat = $event->get_event_category();
echo esc_html( $cat->get_name() );

get_organizer

Gets the Event organizer details

Returns: String (HTML-allowed)

Examples:

echo wp_kses_post( $event->get_organizer() ); // Print the event organizer details, allowing only HTML tags that wp_kses_post allows
echo strip_tags( $event->get_organizer() ); // Print the event organizer details, allowing no HTML tags
echo apply_filters( 'the_content', $event->get_organizer() ); // Print the Event organizer details without any escaping, and apply the_content

get_private_note

Gets the Event private notes

Returns: String (HTML-allowed)

Examples:

echo wp_kses_post( $event->get_private_note() ); // Print the event private notes, allowing only HTML tags that wp_kses_post allows
echo strip_tags( $event->get_private_note() ); // Print the event private notes, allowing no HTML tags
echo apply_filters( 'the_content', $event->get_private_note() ); // Print the Event private notes without any escaping, and apply the_content

get_facebook_url

Gets the Event’s Facebook url

Returns: String

Examples:

<a href="<?php echo esc_url( $event->get_facebook_url() ); ?>">Facebook Link</a>

get_ticket_url

Gets the Event’s ticket URL

Returns: String

Examples:

<a href="<?php echo esc_url( $event->get_ticket_url() ); ?>">Get Tickets</a>

get_price_details

Gets the Event’s cost details

Returns: String

Examples:

echo esc_html( $event->get_price_details() ); // Print the Event's price

get_published

Gets the Event’s published status

Returns: Boolean

Examples:

$published = $event->get_published();
if( $published ) {
    echo 'Event ' . $event->get_id() . ' is public';
} else {
    echo 'Event ' . $event->get_id() . ' is not public';
}

get_tagged_users

Get an Event’s tagged users

Returns: Array<TaggedUser>

Examples:

// Print all tagged handles for the Event
foreach( $event->get_tagged_users() as $user ) {
    echo esc_html( $user->get_handle() ); 
}

get_created_by_me

Determine if an Event was created by your account, or shared with your account

Returns: Boolean

Examples:

$mine = $event->get_created_by_me();
if( $mine ) {
    echo esc_html( $event->get_id() ) . ' is mine';
} else {
    echo esc_html( $event->get_id() ) . ' is not mine';
}

get_recurrence

Get the Event’s recurrence details

Returns: EventRecurrenceDetail

Examples:

// Print the Event's recurrence type
$recurrence = $event->get_recurrence();
if( !empty( $recurrence ) ) {
    echo esc_html( $recurrence->get_type() ); 
}

Venue

A Venue is a place where an Event occurs. Not all Events have Venues, but when one does a Venue object is what will be returned.

The methods outlined below allow you to access the properties of a Venue.

Source: class-venue.php

get_id

Get the Venue’s id

Returns: Integer

Examples:

// Get a Venue from an Event
$venue = $event->get_venue();

// Check if the Event has a Venue
if( !empty( $venue ) ) {
    // Print the Venue id
    echo esc_html( $venue->get_id() );
}

get_name

Get the Venue’s name – Name should never be empty if a Venue exists

Returns: String

Examples:

// Get a Venue from an Event
$venue = $event->get_venue();

// Check if the Event has a Venue
if( !empty( $venue ) ) {
    // Print the Venue name
    echo esc_html( $venue->get_name() );
}

get_location

Get the Venue’s location – Location is a free-text string, used to provide additional details about a Venue. It can be empty

Returns: String

Examples:

// Get a Venue from an Event
$venue = $event->get_venue();

// Check if the Event has a Venue
if( !empty( $venue ) ) {
    // Print the Venue's location details
    echo esc_html( $venue->get_location() );
}

get_published

Get the Venue’s published/unpublished status

Returns: Boolean

Examples:

// Get a Venue from an Event
$venue = $event->get_venue();

// Check if the Event has a Venue
if( !empty( $venue ) ) {
    // Print the Venue's Published status
    $pub_status = $venue->get_published();
    
    if( $pub_status ) {
        $published = 'Published';
    } else {
        $published = 'Unpublished';
    }

    echo esc_html( $venue->get_name() . ': ' . $published );
}

Category

Categories are used to group Events together through taxonomic terms that you define.

API Event Requests allow you to filter Events by category, and Events allow you to get or set the Category that they belong to.

Source: class-event-category.php

get_id

Get the Category’s id

Returns: Integer

Examples:

// Get a Category from an Event
$cat = $event->get_event_category();

// Print the Category id
echo esc_html( $cat->get_id() );

get_name

Get the Category’s name

Returns: String

Examples:

// Get a Category from an Event 
$cat = $event->get_event_category(); 

// Print the Category name
echo esc_html( $cat->get_name() );

get_published

Get the Category’s published/unpublished status

Returns: Boolean

Examples:

// Get a Category from an Event
$cat = $event->get_event_category();

// Print the Category's Published status
$pub_status = $cat->get_published();
    
if( $pub_status ) {
    $published = 'Published';
} else {
    $published = 'Unpublished';
}

echo esc_html( $cat->get_name() . ': ' . $published );

User

Users are other users of MegaCalendar. Since our platform allows you to share Events between calendars owned by different users, there may be cases where the Events that you are interacting with belong to other users. When a User object is returned, you can use the following methods to access the properties of the User.

Source: class-user.php

get_id

Gets the User’s id

Returns: Integer

Examples:

// Get a User from an Event 
$creator = $event->owner();

// Print the User id 
echo esc_html( $creator->get_id() );

get_handle

Gets the User’s handle

Returns: String

Examples:

// Get a User from an Event 
$creator = $event->owner();

// Print the User handle 
echo esc_html( $creator->get_handle() );

get_pro_account

Gets the User’s Pro Account status

Returns: Boolean

Examples:

// Get a User from an Event 
$creator = $event->owner();
$pro_status = $creator->get_pro_account() ? 'Pro' : 'Non-Pro';

// Print "user-handle: Pro" or "user-handle: Non-Pro"
echo esc_html( $creator->get_handle() . ': ' . $pro_status );

get_calendar_name

Gets the User’s calendar name

Returns: String

Examples:

// Get a User from an Event 
$creator = $event->owner();

// Print the User's Calendar Name
echo esc_html( $creator->get_calendar_name() );

TaggedUser

Tagged User is simply an extension of the User class used when dealing with shared Events. It has all of the same accessor methods that are outlined in User, as well as two unique methods related to Event sharing.

Source: class-tagged-user.php

get_valid

Checks if the User handle exists in MegaCal

Returns: Boolean

Examples:

// Print invalid Tagged User handles for an Event
foreach( $event->get_tagged_users() as $user ) {
    if( !$user->get_valid() ) {
        echo esc_html( $user->get_handle() ); 
    }
}

get_status

Gets the status of the attempted share action with this User

Returns: String

Return Values:

• APPROVAL_REQUESTED
• APPROVED
• AUTO_APPROVED
• INACTIVE_USER
• INVALID_CUSTOMER_ID
• INVALID_HANDLE
• NON_PRO
• PRE_VALIDATE
• PRO_EXPIRED
• REJECTED

Examples:

// Print status for all Tagged Users on an Event
foreach( $event->get_tagged_users() as $user ) {
    echo esc_html( $user->get_status() ); 
}

// Print handles of all Tagged Users who have been approved for an Event
foreach( $event->get_tagged_users() as $user ) {
    if( $user->get_status() === 'APPROVED' || $user->get_status() === 'AUTO_APPROVED' ) {
        echo esc_html( $user->get_status() );
    }
}

EventRecurrenceDetail

The EventRecurrenceDetail class will contain an Event’s recurrence details, if it is a recurring Event. You can access information such as recurrence type, the day or date associated with the recurrence, and even recurrence end conditions for custom recurrence.

Source: class-event-recurrence-detail.php

Request Types

Event Request

get_events

Get a list of Events

Returns: EventListResponse

• String ‘start_date’: Date in ‘Y-m-d’ format – Will fetch events with a start date on or after the specified date
• String ‘end_date’: Date in ‘Y-m-d’ format – Will fetch events with a start date on or before the specified date
• Boolean ‘upcoming’: true: Fetch all events on or after today / false: Fetch all events before today / unset: Fetch all events past, present, and upcoming
• Integer ‘start_row’: Used with max_result for pagination, the row to begin fetching events from
• Integer ‘max_result’: Used for pagination, the total number of events to fetch per page
• Integer ‘event_owner’: Fetch only events owned by the specified User id. NOTE: This should be an API user id, not a WordPress user id
• Integer ‘venue’: Fetch only events tagged with the specified Venue id
• Array<Integer> ‘category’: Fetch only events tagged with the specified Category ids.
• Boolean ‘published’: true: Fetch only published events / false: Fetch only unpublished events / unset: Fetch both published and unpublished events

get_event

Get a single Event’s details

Returns: EventDetailResponse

• Integer ‘event_id’: The id of the Event to fetch details for. – *Required

create_event

Creates a new Event

Returns: EventUpsertResponse

• String ‘title’: The title for the new Event. – *Required
• String ‘image_url’: A valid URL, pointing to the full-size Event image
• String ‘image_url_square’: A valid URL, pointing to a thumbnail-sized Event image
• String ‘image_url_detail’: A valid URL, pointing to a large-sized Event image
• String ‘image_url_banner’: A valid URL, pointing to a banner-sized Event image
• String ‘event_date’: Date in ‘Y-m-d’ format – The start date of the Event – *Required
• String ‘start_time’: The Event start time, in any time format – NOTE: We do not handle timezones, or time formatting on the API-level
• String ‘end_time’: The Event end time, in any time format – NOTE: We do not handle timezones, or time formatting on the API-level
• String ‘description’: The Event description – May include most HTML elements. Scripts and other potentially harmful tags will be stripped.
• Array ‘venue’: An associative array representing the Event’s Venue.
  • Integer ‘id’: An existing Venue’s id – To tag the Event with a Venue that already exists
  • String ‘name’: The Venue name – To tag the Event with a new Venue
  • String ‘location’: The Venue’s location – Used when adding a new Venue, to include additional details.
• Array ‘event_category’: => An associative array representing the Event’s Category
  • Integer ‘id’: An existing Category’s id – To tag the Event with a Category that already exists
    String ‘name’: The Category name – To tag the Event with a new Category
• Array<String> ‘tagged_users’: A list of user handles for users to share this event with on creation – If none, pass an empty array – *Required
• String ‘organizer’: The Event organizer details – May include most HTML elements. Scripts and other potentially harmful tags will be stripped.
• String ‘private_note’: The Event private notes – May include most HTML elements. Scripts and other potentially harmful tags will be stripped.
• String ‘facebook_url’: A valid URL pointing to the Event on Facebook
• String ‘ticket_url’: A valid URL pointing users to where they can purchase tickets for the Event
• String ‘price_details’: Details about the Event’s price
• Boolean ‘published’: True: publish the Event on creation / False: Unpublish the Event on creation – *Required
• EventRecurrenceDetail ‘recurrence’: The Event’s recurrence details, as an EventRecurrenceDetail model.

update_event

Update an existing Event’s details

Returns: EventUpsertResponse

• Integer ‘event_id’: The id of the Event to update. – *Required
• String ‘title’: The title for the new Event.
• String ‘image_url’: A valid URL, pointing to the full-size Event image
• String ‘image_url_square’: A valid URL, pointing to a thumbnail-sized Event image
• String ‘image_url_detail’: A valid URL, pointing to a large-sized Event image
• String ‘image_url_banner’: A valid URL, pointing to a banner-sized Event image
• String ‘event_date’: Date in ‘Y-m-d’ format – The start date of the Event
• String ‘start_time’: The Event start time, in any time format – NOTE: We do not handle timezones, or time formatting on the API-level
• String ‘end_time’: The Event end time, in any time format – NOTE: We do not handle timezones, or time formatting on the API-level
• String ‘description’: The Event description – May include most HTML elements. Scripts and other potentially harmful tags will be stripped.
• Array ‘venue’: An associative array representing the Event’s Venue.
  • Integer ‘id’: An existing Venue’s id – To tag the Event with a Venue that already exists
  • String ‘name’: The Venue name – To tag the Event with a new Venue
  • String ‘location’: The Venue’s location – Used when adding a new Venue, to include additional details.
• Array ‘event_category’: => An associative array representing the Event’s Category
  • Integer ‘id’: An existing Category’s id – To tag the Event with a Category that already exists
    String ‘name’: The Category name – To tag the Event with a new Category
• Array<String> ‘tagged_users’: A list of user handles for users to share this event with on creation – If none, pass an empty array
• String ‘organizer’: The Event organizer details – May include most HTML elements. Scripts and other potentially harmful tags will be stripped.
• String ‘private_note’: The Event private notes – May include most HTML elements. Scripts and other potentially harmful tags will be stripped.
• String ‘facebook_url’: A valid URL pointing to the Event on Facebook
• String ‘ticket_url’: A valid URL pointing users to where they can purchase tickets for the Event
• String ‘price_details’: Details about the Event’s price
• Boolean ‘published’: True: publish the Event on creation / False: Unpublish the Event on creation
• EventRecurrenceDetail ‘recurrence’: The Event’s recurrence details, as an EventRecurrenceDetail model.
• String ‘change_type’: The change type to apply when updating the Event – Used with recurrence, empty string for a non-recurring Event – *Required
  • ”
  • ‘UPDATE_THIS’
  • ‘UPDATE_THIS_ONWARD’
  • ‘UPDATE_ALL’

delete_event

Delete an Event

Returns: EventDeleteResponse

• Integer ‘event_id’: The id of the Event to delete. – *Required
• String ‘change_type’: The change type to apply when deleting the Event – Used with recurrence, empty string for a non-recurring Event – *Required
  • ”
  • ‘DELETE_THIS’
  • ‘DELETE_THIS_ONWARD’
  • ‘DELETE_ALL’

publish_event

Publish or unpublish an Event

Returns: EventPublishResponse

• Integer ‘event_id’: The id of the Event to publish/unpublish. – *Required
• Boolean ‘published’: True: publish the Event / False: Unpublish the Event – *Required

get_event_upsert

Get upsert details for a specific Event

Returns: EventUpsertBodyResponse

• Integer ‘event_id’: The id of the Event to fetch upsert details for. – *Required

get_new_upsert

Get upsert details without a specific Event

Returns: EventUpsertBodyResponse

• Takes no params

get_event_filters

Get a list of Entities to filter Events by

Returns: EventFilterResponse

• Boolean ‘published’: True: Return only published Entities / False: Return only unpublished Entities / Unset: Return all Entities

get_event_recurrence

Process an Event date for recurrence, and return details to assist with building the recurrence details

Returns: EventRecurrenceResponse

• String ‘event_date’: Date in ‘Y-m-d’ format – The start date of the Event

get_event_processing

Get an Event’s processing details using the returned execution id – Generally used to check the status of recurring Event generation

Returns: EventProcessingResponse

• String  ‘execution_id’: The execution id for the creation action of the Event that you want to look up – *Required

More Coming Soon!

Response Types

Events

EventListResponse

EventListResponse is returned after a request to the Event list endpoint

get_events

Get the array of Events from the response

Returns: Array<Event>

• Takes no params

get_count

Get the total number of Events that match the request

Returns: Array<Event>

• Takes no params

EventDetailResponse

EventDetailResponse is returned after a request to the Event detail endpoint

get_event

Get the Event from the response

Returns: Event

• Takes no params

EventUpsertResponse

EventDetailResponse is returned after a request to the Event upsert endpoint

get_event_id

Get the Event id from the response

Returns: Integer

• Takes no params

EventDeleteResponse

EventDeleteResponse is returned after a request to the Event deletion endpoint. Aside from its type, there are no unique methods or properties for EventDeleteResponse.

EventUpsertBodyResponse

EventUpsertBodyReponse is returned after a request to the Event upsert details or new upsert details endpoints

get_event

Gets the Event details from the response, if applicable

Returns: Event

• Takes no params

get_categories

Gets the list of available Categories from the response

Returns: Array<Category>

• Takes no params

get_venues

Gets the list of available Venues from the response

Returns: Array<Venue>

• Takes no params

EventFilterResponse

EventFilterResponse is returned after a request to the Event filters endpoint

get_event_owners

Get the Event owners from the response

Returns: Array<User>

• Takes no params

get_venues

Get the Venues from the response

Returns: Array<Venue>

• Takes no params

get_event_categories

Get the Event Categories from the response

Returns: Array<Category>

• Takes no params

EventRecurrenceResponse

EventRecurrenceResponse is returned after a request to the Event Recurrence endpoint

get_event_recurrence_details

Get the Event Recurrence details from the response

Returns: EventRecurrenceDetail

• Takes no params

EventProcessingResponse

EventProcessingResponse is returned after a request to the Event Processing endpoint

get_event_processing_details

Get the Event processing details from the response

Returns: EventProcessingDetail

• Takes no params

More Coming Soon!