For a project I'm working on I needed to interact with a Google Calendar. If you've ever worked with some API's by Google then you know their documentation can be very confusing. It's not that they don't have documentation, but code examples of common use cases are simply not present. You must wade through a lot of pages to learn basic things such as how to make an authorized request let alone how to fetch calendar events. In this post I'd like to explain in a human readable way how setup and use the Google Calendar API.

Getting credentials

The first thing you'll need to do is to get some credentials to use Google API's. I'm assuming that you've already created a Google account and are signed in. Head over to Google API's site and click "Select a project" in the header. Choose "Create a new project" in the menu that opens. You can give that project any name you'd like.

Next up we must specify which API's the project may consume. In the list of available API's click "Google Calendar API". On the next screen click "Enable".

Now that you've created a project that has access to the Calendar API it's time to download a file with these credentials. Click "Credentials" in the sidebar. You'll want to create a "Service account key".

On the next screen you can give the service account a name. You can name it anything you'd like. In the service account id you'll see an email address. We'll use this email address later on in this guide. Select "JSON" as the key type and click "Create" to download the JSON file.

Setting up the Google Calendar

Now that everything is set up on the API site, we'll need to configure some things on the Google Calendar site. Head over Google Calendar and view the settings of the calendar you want to work with via PHP. On the "Share this Calendar" tab add the service account id that was displayed when creating credentials on the API site.

Open up the "Calendar Details" tab to see the id of the calendar. We'll need this id later on.

Accessing the calendar in PHP

Now that everything is set up at Google, let's finally write some PHP. In your project make sure you require `google/apiclient` in your `composer.json`. This piece of code can be used to fetch all events on your calendar:

$client = new Google_Client();

// $credentialsJson should contain the path to the json file downloaded from the API site
$credentials = $client->loadServiceAccountJson(
   $credentialJson,
   'https://www.googleapis.com/auth/calendar'
);

$client->setAssertionCredentials($credentials);

$service = new Google_Service_Calendar($client);

// $calendarId should contain the calendar id found on the settings page of the calendar
$events = $service->events->listEvents($calendarId);

In the example above all events will get fetched. Of course the API can do a whole lot more. Take a look at the API docs to learn what's possible.

In closing

Setting up and using the calendar API, and the other Google API's is not that difficult. The key thing that's missing is proper documentation. I hope that in the future Google will add some easy to follow tutorials and practical examples to their docs. It took me about an hour to learn and set everything mentioned in this post. With good documentation the required time would be around 5 minutes (and there would be much less frustration).

If you're using Laravel you'll be happy to know that I'm currently developing a package that makes working with a Google Calendar a breeze. My goal is to make this code work:

use \Spatie\GoogleCalendar\Event;

//creating events
$event = new Event();
$event->title = 'My new event'
$event->start = Carbon::now();
$event->end = Carbon::now()->addHour();
$event->save();

//fetching all events
$allEvents = Event::all();

//updating an event
$event = $allEvents->first();
$event->name = 'updated name';
$event->save();

//deleting an event
$allEvents->last()->delete();

I'm not planning on supporting all the features of the native API, but if you need only the basic functionality, this will be the package for you.