GoogleCalendar Spark ReadMe

Intent

This spark is a supplement to the Google Client API (and Google Client API spark) intended to make integrating Google Calendar support within your CodeIgniter application or website easier.

The Google Client API is already pretty well designed and relatively easy to incorporate, so at first glance this spark might seem redundant, but it provides a number of features which compliment the Google API quite well, including:

• A local configurable cache to limit the number of requests your application is making, so that each page load does not initiate a connection to Google's servers
• Support for fetching public/shared calendars via Curl (e.g. for listing public upcoming events on your site)
• oAuth2 authentication for requests to protected information using the Google API
• Dynamic configuration of the URL visitors are redirected to after authenticating (for requests to private content)
• A CodeIgniter configuration file for the configuration variables required by the Google API
• Conversion of Unix timestamps to time strings set for all day and non-all day events
• Support for timezone offsets so that your application can pass on the user-defined timezone setting to generate accurate event update dates
• Calculation of the "sequence" (i.e. revision number) variable needed for event updates
• User-friendly error message display when required variables are missing, output of errors generated by Google
• Variable and function names match what Google uses in their API, so you don't have to learn an API on top of an API - this is indeed a supplement!
• A session variable tracking the last sync with Google

Limitations

This spark does not support every possible Google function provided in the Google API, nor does it support manipulating every single variable contained within an event. If you wish to support additional variables or functions please feel free to fork this Spark, make your modifications, and send a pull request for inclusion of your code to this spark. This extra stuff was left out simply to save time, because it was not needed at this time.

Functionality Supported

• Authentication (and logging out) - authentication is called automatically as needed, logging out: $this->gcal->deauth()
• Listing of calendars within an account - $this->gcal->listCalendarList()
• Retrieving metadata for a calendar - $this->gcal->calendarGet()
• Listing events within a calendar - $this->gcal->listEvents()
• Retrieving details for a single event - $this->gcal->eventGet()
• Updating information for an event - $this->gcal->eventUpdate()
• Creating a new event - $this->gcal->eventInsert()
• Deleting an event - $this->gcal->eventDelete()

Event Variables Supported

Again, if there are event variables you wish to support that are not included here, please fork/modify/pull request!

• summary (i.e. event title)
• location
• recurrence
• start and end dates/times for all day and non-all day events
• event updated date
• event sequence (i.e. revision number)

Change Log

1.0.3

• Inserts and updates now send description field to Google

1.0.2

• Correct dumb and careless mistake where Spark was fetching older version of Google API Client Spark

1.0.1

• Updated Google Client API version prerequisite

Using This Spark

Configuration

The following variables must be set in the spark's configuration file, each of these provided to you within Google's API Console upon registering your application

• client_id
• client_secret
• application_name (displayed on the authorization page)
• api_key (used for public URL requests)

You will also need to register the URLs you will use to initiate requests within the Google API Console.

Examples

The following are some examples for calling each function provided by this spark. Please note that sensible defaults are applied, you do not need to define each of these variables. Required variables are indicated:

$this->gcal->deauth()

no arguments necessary

$this->gcal->listCalendarList()

$calendars = $this->gcal->listCalendarList(array(
	'usecache' => true,  // defaults to true
	'cachefile' => '[/path/to/custom/cache/file]',  // optional, defaults to [yourClientID]-calendars.json
	'cacheduration' => 5,  // in minutes, defaults to 5
	'redirectURI' => '[url to redirect to after authorization of request]'  // defaults to the URL of the current page
));

$this->gcal->calendarGet()

$calendar = $this->gcal->calendarGet(array(
	'calendarId' => '[id of the calendar you wish to retrieve]',   // required
	'redirectURI' => '[url to redirect to after authorization of request]'  // defaults to the URL of the current page
));

$this->gcal->listEvents()

$events = $this->gcal->listEvents(array(
	'ispublic' => false,  // defaults to false
	'calendarId' => '[id of the calendar you wish to retrieve]',   // required
	'usecache' => true,  // defaults to true
	'cachefile' => '[/path/to/custom/cache/file]',  // optional, defaults to [yourClientID]-calendars.json
	'cacheduration' => 5,  // in minutes, defaults to 5
	'redirectURI' => '[url to redirect to after authorization of request]'  // defaults to the URL of the current page
));

$this->gcal->eventGet()

$event = $this->gcal->eventGet(array(
	'eventId' => '[id of event you wish to fetch]',  // required
	'calendarId' => '[id of the calendar you wish to retrieve]',   // required
	'ispublic' => false,  // defaults to false
	'redirectURI' => '[url to redirect to after authorization of request]'  // defaults to the URL of the current page
));

$this->gcal->eventUpdate()

Note that even if these variables will not change you still need to define them, or else they will be set with blank values (this is how the Google Client API works)

$response = $this->gcal->eventUpdate(array(
	'eventId' => '[id of event you wish to fetch]',  // required
	'calendarId' => '[id of the calendar you wish to retrieve]',   // required
	'allday' => true,  // all day event? defaults to true
	'start' => [Unix timestamp of start time],  // required
	'end' => [Unix timestamp of end time],  // required
	'summary' => 'event title',  // optional
	'location' => 'event location',  // optional
	'recurrence' => '[recurrence rule, e.g. FREQ=WEEKLY;BYDAY=TH;COUNT=16 - you'll probably need to study this syntax which you can do by examining any .ics file]',  // optional
	'timezone_offset' => '[numbers of hours to offset for setting updated date value, e.g. -5, +1, etc.]',  // optional, defaults to GMT
	'redirectURI' => '[url to redirect to after authorization of request]'  // defaults to the URL of the current page
));

$this->gcal->eventInsert()

$response = $this->gcal->eventInsert(array(
	'calendarId' => '[id of the calendar you wish to retrieve]',   // required
	'allday' => true,  // all day event? defaults to true
	'start' => [Unix timestamp of start time],  // required
	'end' => [Unix timestamp of end time],  // required
	'summary' => 'event title',  // optional
	'location' => 'event location',  // optional
	'recurrence' => '[recurrence rule, e.g. FREQ=WEEKLY;BYDAY=TH;COUNT=16 - you'll probably need to study this syntax which you can do by examining any .ics file]',  // optional
	'timezone_offset' => '[numbers of hours to offset for setting updated date value, e.g. -5, +1, etc.]',  // optional, defaults to GMT
	'redirectURI' => '[url to redirect to after authorization of request]'  // defaults to the URL of the current page
));

$this->gcal->eventDelete()

$response = $this->gcal->eventDelete(array(
	'eventId' => '[id of event you wish to fetch]',  // required
	'calendarId' => '[id of the calendar you wish to retrieve]',   // required
	'redirectURI' => '[url to redirect to after authorization of request]'  // defaults to the URL of the current page
));